KickJava   Java API By Example, From Geeks To Geeks.

Java > Open Source Codes > javax > tools > FileObject


1 /*
2  * @(#)FileObject.java 1.5 06/09/25
3  *
4  * Copyright 2006 Sun Microsystems, Inc. All rights reserved.
5  * SUN PROPRIETARY/CONFIDENTIAL. Use is subject to license terms.
6  */

7
8 package javax.tools;
9
10 import java.io.IOException JavaDoc;
11 import java.io.CharConversionException JavaDoc;
12 import java.io.InputStream JavaDoc;
13 import java.io.OutputStream JavaDoc;
14 import java.io.Reader JavaDoc;
15 import java.io.Writer JavaDoc;
16 import java.nio.CharBuffer JavaDoc;
17 import java.net.URI JavaDoc;
18
19 /**
20  * File abstraction for tools. In this context, <em>file</em> means
21  * an abstraction of regular files and other sources of data. For
22  * example, a file object can be used to represent regular files,
23  * memory cache, or data in databases.
24  *
25  * <p>All methods in this interface might throw a SecurityException if
26  * a security exception occurs.
27  *
28  * <p>Unless explicitly allowed, all methods in this interface might
29  * throw a NullPointerException if given a {@code null} argument.
30  *
31  * @author Peter von der Ah&eacute;
32  * @author Jonathan Gibbons
33  * @since 1.6
34  */

35 public interface FileObject {
36
37     /**
38      * Returns a URI identifying this file object.
39      * @return a URI
40      */

41     URI JavaDoc toUri();
42
43     /**
44      * Gets a user-friendly name for this file object. The exact
45      * value returned is not specified but implementations should take
46      * care to preserve names as given by the user. For example, if
47      * the user writes the filename {@code "BobsApp\Test.java"} on
48      * the command line, this method should return {@code
49      * "BobsApp\Test.java"} whereas the {@linkplain #toUri toUri}
50      * method might return {@code
51      * file:///C:/Documents%20and%20Settings/UncleBob/BobsApp/Test.java}.
52      *
53      * @return a user-friendly name
54      */

55     String JavaDoc getName();
56
57     /**
58      * Gets an InputStream for this file object.
59      *
60      * @return an InputStream
61      * @throws IllegalStateException if this file object was
62      * opened for writing and does not support reading
63      * @throws UnsupportedOperationException if this kind of file
64      * object does not support byte access
65      * @throws IOException if an I/O error occurred
66      */

67     InputStream JavaDoc openInputStream() throws IOException JavaDoc;
68
69     /**
70      * Gets an OutputStream for this file object.
71      *
72      * @return an OutputStream
73      * @throws IllegalStateException if this file object was
74      * opened for reading and does not support writing
75      * @throws UnsupportedOperationException if this kind of
76      * file object does not support byte access
77      * @throws IOException if an I/O error occurred
78      */

79     OutputStream JavaDoc openOutputStream() throws IOException JavaDoc;
80
81     /**
82      * Gets a reader for this object. The returned reader will
83      * replace bytes that cannot be decoded with the default
84      * translation character. In addition, the reader may report a
85      * diagnostic unless {@code ignoreEncodingErrors} is true.
86      *
87      * @param ignoreEncodingErrors ignore encoding errors if true
88      * @return a Reader
89      * @throws IllegalStateException if this file object was
90      * opened for writing and does not support reading
91      * @throws UnsupportedOperationException if this kind of
92      * file object does not support character access
93      * @throws IOException if an I/O error occurred
94      */

95     Reader JavaDoc openReader(boolean ignoreEncodingErrors) throws IOException JavaDoc;
96
97     /**
98      * Gets the character content of this file object, if available.
99      * Any byte that cannot be decoded will be replaced by the default
100      * translation character. In addition, a diagnostic may be
101      * reported unless {@code ignoreEncodingErrors} is true.
102      *
103      * @param ignoreEncodingErrors ignore encoding errors if true
104      * @return a CharSequence if available; {@code null} otherwise
105      * @throws IllegalStateException if this file object was
106      * opened for writing and does not support reading
107      * @throws UnsupportedOperationException if this kind of
108      * file object does not support character access
109      * @throws IOException if an I/O error occurred
110      */

111     CharSequence JavaDoc getCharContent(boolean ignoreEncodingErrors) throws IOException JavaDoc;
112
113     /**
114      * Gets a Writer for this file object.
115      *
116      * @return a Writer
117      * @throws IllegalStateException if this file object was
118      * opened for reading and does not support writing
119      * @throws UnsupportedOperationException if this kind of
120      * file object does not support character access
121      * @throws IOException if an I/O error occurred
122      */

123     Writer JavaDoc openWriter() throws IOException JavaDoc;
124
125     /**
126      * Gets the time this file object was last modified. The time is
127      * measured in milliseconds since the epoch (00:00:00 GMT, January
128      * 1, 1970).
129      *
130      * @return the time this file object was last modified; or 0 if
131      * the file object does not exist, if an I/O error occurred, or if
132      * the operation is not supported
133      */

134     long getLastModified();
135
136     /**
137      * Deletes this file object. In case of errors, returns false.
138      * @return true if and only if this file object is successfully
139      * deleted; false otherwise
140      */

141     boolean delete();
142
143 }
144
Popular Tags