libjava/classpath/javax/tools/FileObject.java

   1 /* FileObject.java --
   2    Copyright (C) 2008  Free Software Foundation, Inc.
   3
   4 This file is part of GNU Classpath.
   5
   6 GNU Classpath is free software; you can redistribute it and/or modify
   7 it under the terms of the GNU General Public License as published by
   8 the Free Software Foundation; either version 2, or (at your option)
   9 any later version.
  10
  11 GNU Classpath is distributed in the hope that it will be useful, but
  12 WITHOUT ANY WARRANTY; without even the implied warranty of
  13 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
  14 General Public License for more details.
  15
  16 You should have received a copy of the GNU General Public License
  17 along with GNU Classpath; see the file COPYING.  If not, write to the
  18 Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA
  19 02110-1301 USA.
  20
  21 Linking this library statically or dynamically with other modules is
  22 making a combined work based on this library.  Thus, the terms and
  23 conditions of the GNU General Public License cover the whole
  24 combination.
  25
  26 As a special exception, the copyright holders of this library give you
  27 permission to link this library with independent modules to produce an
  28 executable, regardless of the license terms of these independent
  29 modules, and to copy and distribute the resulting executable under
  30 terms of your choice, provided that you also meet, for each linked
  31 independent module, the terms and conditions of the license of that
  32 module.  An independent module is a module which is not derived from
  33 or based on this library.  If you modify this library, you may extend
  34 this exception to your version of the library, but you are not
  35 obligated to do so.  If you do not wish to do so, delete this
  36 exception statement from your version. */
  37
  38 package javax.tools;
  39
  40 import java.io.IOException;
  41 import java.io.InputStream;
  42 import java.io.OutputStream;
  43 import java.io.Reader;
  44 import java.io.Writer;
  45 import java.net.URI;
  46
  47 /**
  48  * Abstraction for all kinds of file objects used by tools, e.g. regular files,
  49  * memory cache, or database data.
  50  *
  51  * @author Roman Kennke (roman@kennke.org)
  52  *
  53  * @since 1.6
  54  */
  55 public interface FileObject
  56 {
  57
  58   /**
  59    * Returns a URI that represents this file object.
  60    *
  61    * @return a URI that represents this file object
  62    */
  63   URI toUri();
  64
  65   /**
  66    * Returns a name for this file object. The exact name is implementation
  67    * dependent.
  68    *
  69    * @return a name for this file object
  70    */
  71   String getName();
  72
  73   /**
  74    * Opens this file for reading and returns an input stream.
  75    *
  76    * @return an input stream to read this file object
  77    *
  78    * @throws IOException if an I/O error occured
  79    * @throws IllegalStateException if this file was opened for writing and
  80    *         does not support reading
  81    * @throws UnsupportedOperationException if this kind of file does not allow
  82    *         byte reading
  83    */
  84   InputStream openInputStream() throws IOException;
  85
  86   /**
  87    * Opens this file for writing and returns an output stream.
  88    *
  89    * @return an output stream for writing this file object
  90    *
  91    * @throws IOException if an I/O error occurs
  92    * @throws IllegalStateException if this file was opened for reading and
  93    *         does not support writing
  94    * @throws UnsupportedOperationException if this kind of file does not allow
  95    *         byte writing
  96    */
  97   OutputStream openOutputStream() throws IOException;
  98
  99   /**
 100    * Opens this file for reading and returns a reader.
 101    *
 102    * @param ignoreEncodingErrors <code>true</code> when encoding errors should be ignored
 103    *                             <code>false</code> otherwise
 104    * @return a reader for reading this file object
 105    *
 106    * @throws IOException if an I/O error occurs
 107    * @throws IllegalStateException if this file was opened for writing and
 108    *         does not support reading
 109    * @throws UnsupportedOperationException if this kind of file does not allow
 110    *         character reading
 111    */
 112   Reader openReader(boolean ignoreEncodingErrors) throws IOException;
 113
 114   /**
 115    * Returns the character content of the file, if available. Any byte
 116    * that cannot be decoded will be replaced by the default replacement
 117    * character. A diagnostic may be reported, unless
 118    * <code>ignoreEncodingErrors</code> is <code>true</code>.
 119    *
 120    * @param ignoreEncodingErrors <code>true</code> when encoding errors should be ignored
 121    *                             <code>false</code> otherwise
 122    * @return the character content, or <code>null</code> if not available
 123    *
 124    * @throws IOException if an I/O error occurs
 125    */
 126   CharSequence getCharContent(boolean ignoreEncodingErrors) throws IOException;
 127
 128   /**
 129    * Opens this file for writer and returns a writer.
 130    *
 131    * @return a writer for writing this file object
 132    *
 133    * @throws IOException if an I/O error occurs
 134    * @throws IllegalStateException if this file was opened for reading and
 135    *         does not support writing
 136    * @throws UnsupportedOperationException if this kind of file does not allow
 137    *         character writing
 138    */
 139   Writer openWriter() throws IOException;
 140
 141   /**
 142    * Returns the time when the file was last modified. The time is measured
 143    * like in <code>System.currentTimeMillis()</code>.
 144    *
 145    * @return the time when the file was last modified
 146    */
 147   long getLastModified();
 148
 149   /**
 150    * Deletes this file object. In case of errors this returns
 151    * <code>false</code>.
 152    *
 153    * @return <code>true</code> when the file deletion was successful,
 154    *         <code>false</code> otherwise
 155    */
 156   boolean delete();
 157 }