001: /*
002: * Copyright 2006 Sun Microsystems, Inc. All Rights Reserved.
003: * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
004: *
005: * This code is free software; you can redistribute it and/or modify it
006: * under the terms of the GNU General Public License version 2 only, as
007: * published by the Free Software Foundation. Sun designates this
008: * particular file as subject to the "Classpath" exception as provided
009: * by Sun in the LICENSE file that accompanied this code.
010: *
011: * This code is distributed in the hope that it will be useful, but WITHOUT
012: * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
013: * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
014: * version 2 for more details (a copy is included in the LICENSE file that
015: * accompanied this code).
016: *
017: * You should have received a copy of the GNU General Public License version
018: * 2 along with this work; if not, write to the Free Software Foundation,
019: * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
020: *
021: * Please contact Sun Microsystems, Inc., 4150 Network Circle, Santa Clara,
022: * CA 95054 USA or visit www.sun.com if you need additional information or
023: * have any questions.
024: */
025:
026: package javax.tools;
027:
028: import java.io.IOException;
029: import java.io.CharConversionException;
030: import java.io.InputStream;
031: import java.io.OutputStream;
032: import java.io.Reader;
033: import java.io.Writer;
034: import java.nio.CharBuffer;
035: import java.net.URI;
036:
037: /**
038: * File abstraction for tools. In this context, <em>file</em> means
039: * an abstraction of regular files and other sources of data. For
040: * example, a file object can be used to represent regular files,
041: * memory cache, or data in databases.
042: *
043: * <p>All methods in this interface might throw a SecurityException if
044: * a security exception occurs.
045: *
046: * <p>Unless explicitly allowed, all methods in this interface might
047: * throw a NullPointerException if given a {@code null} argument.
048: *
049: * @author Peter von der Ahé
050: * @author Jonathan Gibbons
051: * @since 1.6
052: */
053: public interface FileObject {
054:
055: /**
056: * Returns a URI identifying this file object.
057: * @return a URI
058: */
059: URI toUri();
060:
061: /**
062: * Gets a user-friendly name for this file object. The exact
063: * value returned is not specified but implementations should take
064: * care to preserve names as given by the user. For example, if
065: * the user writes the filename {@code "BobsApp\Test.java"} on
066: * the command line, this method should return {@code
067: * "BobsApp\Test.java"} whereas the {@linkplain #toUri toUri}
068: * method might return {@code
069: * file:///C:/Documents%20and%20Settings/UncleBob/BobsApp/Test.java}.
070: *
071: * @return a user-friendly name
072: */
073: String getName();
074:
075: /**
076: * Gets an InputStream for this file object.
077: *
078: * @return an InputStream
079: * @throws IllegalStateException if this file object was
080: * opened for writing and does not support reading
081: * @throws UnsupportedOperationException if this kind of file
082: * object does not support byte access
083: * @throws IOException if an I/O error occurred
084: */
085: InputStream openInputStream() throws IOException;
086:
087: /**
088: * Gets an OutputStream for this file object.
089: *
090: * @return an OutputStream
091: * @throws IllegalStateException if this file object was
092: * opened for reading and does not support writing
093: * @throws UnsupportedOperationException if this kind of
094: * file object does not support byte access
095: * @throws IOException if an I/O error occurred
096: */
097: OutputStream openOutputStream() throws IOException;
098:
099: /**
100: * Gets a reader for this object. The returned reader will
101: * replace bytes that cannot be decoded with the default
102: * translation character. In addition, the reader may report a
103: * diagnostic unless {@code ignoreEncodingErrors} is true.
104: *
105: * @param ignoreEncodingErrors ignore encoding errors if true
106: * @return a Reader
107: * @throws IllegalStateException if this file object was
108: * opened for writing and does not support reading
109: * @throws UnsupportedOperationException if this kind of
110: * file object does not support character access
111: * @throws IOException if an I/O error occurred
112: */
113: Reader openReader(boolean ignoreEncodingErrors) throws IOException;
114:
115: /**
116: * Gets the character content of this file object, if available.
117: * Any byte that cannot be decoded will be replaced by the default
118: * translation character. In addition, a diagnostic may be
119: * reported unless {@code ignoreEncodingErrors} is true.
120: *
121: * @param ignoreEncodingErrors ignore encoding errors if true
122: * @return a CharSequence if available; {@code null} otherwise
123: * @throws IllegalStateException if this file object was
124: * opened for writing and does not support reading
125: * @throws UnsupportedOperationException if this kind of
126: * file object does not support character access
127: * @throws IOException if an I/O error occurred
128: */
129: CharSequence getCharContent(boolean ignoreEncodingErrors)
130: throws IOException;
131:
132: /**
133: * Gets a Writer for this file object.
134: *
135: * @return a Writer
136: * @throws IllegalStateException if this file object was
137: * opened for reading and does not support writing
138: * @throws UnsupportedOperationException if this kind of
139: * file object does not support character access
140: * @throws IOException if an I/O error occurred
141: */
142: Writer openWriter() throws IOException;
143:
144: /**
145: * Gets the time this file object was last modified. The time is
146: * measured in milliseconds since the epoch (00:00:00 GMT, January
147: * 1, 1970).
148: *
149: * @return the time this file object was last modified; or 0 if
150: * the file object does not exist, if an I/O error occurred, or if
151: * the operation is not supported
152: */
153: long getLastModified();
154:
155: /**
156: * Deletes this file object. In case of errors, returns false.
157: * @return true if and only if this file object is successfully
158: * deleted; false otherwise
159: */
160: boolean delete();
161:
162: }
|