18 * 2 along with this work; if not, write to the Free Software Foundation,
19 * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
20 *
21 * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
22 * or visit www.oracle.com if you need additional information or have any
23 * questions.
24 */
25
26 package javax.tools;
27
28 import java.io.Closeable;
29 import java.io.Flushable;
30 import java.io.IOException;
31 import java.util.Iterator;
32 import java.util.ServiceLoader;
33 import java.util.Set;
34
35 import static javax.tools.JavaFileObject.Kind;
36
37 /**
38 * File manager for tools operating on Java™ programming language
39 * source and class files. In this context, <em>file</em> means an
40 * abstraction of regular files and other sources of data.
41 *
42 * <p>When constructing new JavaFileObjects, the file manager must
43 * determine where to create them. For example, if a file manager
44 * manages regular files on a file system, it would most likely have a
45 * current/working directory to use as default location when creating
46 * or finding files. A number of hints can be provided to a file
47 * manager as to where to create files. Any file manager might choose
48 * to ignore these hints.
49 *
50 * <p>Some methods in this interface use class names. Such class
51 * names must be given in the Java Virtual Machine internal form of
52 * fully qualified class and interface names. For convenience '.'
53 * and '/' are interchangeable. The internal form is defined in
54 * chapter four of
55 * <cite>The Java™ Virtual Machine Specification</cite>.
56
57 * <blockquote><p>
58 * <i>Discussion:</i> this means that the names
59 * "java/lang.package-info", "java/lang/package-info",
60 * "java.lang.package-info", are valid and equivalent. Compare to
61 * binary name as defined in
62 * <cite>The Java™ Language Specification</cite>,
63 * section 13.1 "The Form of a Binary".
64 * </p></blockquote>
65 *
66 * <p>The case of names is significant. All names should be treated
67 * as case-sensitive. For example, some file systems have
68 * case-insensitive, case-aware file names. File objects representing
69 * such files should take care to preserve case by using {@link
70 * java.io.File#getCanonicalFile} or similar means. If the system is
71 * not case-aware, file objects must use other means to preserve case.
72 *
73 * <p><em><a id="relative_name">Relative names</a>:</em> some
74 * methods in this interface use relative names. A relative name is a
75 * non-null, non-empty sequence of path segments separated by '/'.
76 * '.' or '..' are invalid path segments. A valid relative name must
77 * match the "path-rootless" rule of <a
78 * href="http://www.ietf.org/rfc/rfc3986.txt">RFC 3986</a>,
79 * section 3.3. Informally, this should be true:
80 *
81 * <!-- URI.create(relativeName).normalize().getPath().equals(relativeName) -->
82 * <pre> URI.{@linkplain java.net.URI#create create}(relativeName).{@linkplain java.net.URI#normalize() normalize}().{@linkplain java.net.URI#getPath getPath}().equals(relativeName)</pre>
205 * @param packageName a package name
206 * @param kinds return objects only of these kinds
207 * @param recurse if true include "subpackages"
208 * @return an Iterable of file objects matching the given criteria
209 * @throws IOException if an I/O error occurred, or if {@link
210 * #close} has been called and this file manager cannot be
211 * reopened
212 * @throws IllegalArgumentException if the location is a module-oriented location
213 * @throws IllegalStateException if {@link #close} has been called
214 * and this file manager cannot be reopened
215 */
216 Iterable<JavaFileObject> list(Location location,
217 String packageName,
218 Set<Kind> kinds,
219 boolean recurse)
220 throws IOException;
221
222 /**
223 * Infers a binary name of a file object based on a package-oriented location.
224 * The binary name returned might not be a valid binary name according to
225 * <cite>The Java™ Language Specification</cite>.
226 *
227 * @param location a location
228 * @param file a file object
229 * @return a binary name or {@code null} the file object is not
230 * found in the given location
231 * @throws IllegalArgumentException if the location is a module-oriented location
232 * @throws IllegalStateException if {@link #close} has been called
233 * and this file manager cannot be reopened
234 */
235 String inferBinaryName(Location location, JavaFileObject file);
236
237 /**
238 * Compares two file objects and return true if they represent the
239 * same underlying object.
240 *
241 * @param a a file object
242 * @param b a file object
243 * @return true if the given file objects represent the same
244 * underlying object
245 *
|
18 * 2 along with this work; if not, write to the Free Software Foundation,
19 * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
20 *
21 * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
22 * or visit www.oracle.com if you need additional information or have any
23 * questions.
24 */
25
26 package javax.tools;
27
28 import java.io.Closeable;
29 import java.io.Flushable;
30 import java.io.IOException;
31 import java.util.Iterator;
32 import java.util.ServiceLoader;
33 import java.util.Set;
34
35 import static javax.tools.JavaFileObject.Kind;
36
37 /**
38 * File manager for tools operating on Java programming language
39 * source and class files. In this context, <em>file</em> means an
40 * abstraction of regular files and other sources of data.
41 *
42 * <p>When constructing new JavaFileObjects, the file manager must
43 * determine where to create them. For example, if a file manager
44 * manages regular files on a file system, it would most likely have a
45 * current/working directory to use as default location when creating
46 * or finding files. A number of hints can be provided to a file
47 * manager as to where to create files. Any file manager might choose
48 * to ignore these hints.
49 *
50 * <p>Some methods in this interface use class names. Such class
51 * names must be given in the Java Virtual Machine internal form of
52 * fully qualified class and interface names. For convenience '.'
53 * and '/' are interchangeable. The internal form is defined in
54 * chapter four of
55 * <cite>The Java Virtual Machine Specification</cite>.
56
57 * <blockquote><p>
58 * <i>Discussion:</i> this means that the names
59 * "java/lang.package-info", "java/lang/package-info",
60 * "java.lang.package-info", are valid and equivalent. Compare to
61 * binary name as defined in
62 * <cite>The Java Language Specification</cite>,
63 * section 13.1 "The Form of a Binary".
64 * </p></blockquote>
65 *
66 * <p>The case of names is significant. All names should be treated
67 * as case-sensitive. For example, some file systems have
68 * case-insensitive, case-aware file names. File objects representing
69 * such files should take care to preserve case by using {@link
70 * java.io.File#getCanonicalFile} or similar means. If the system is
71 * not case-aware, file objects must use other means to preserve case.
72 *
73 * <p><em><a id="relative_name">Relative names</a>:</em> some
74 * methods in this interface use relative names. A relative name is a
75 * non-null, non-empty sequence of path segments separated by '/'.
76 * '.' or '..' are invalid path segments. A valid relative name must
77 * match the "path-rootless" rule of <a
78 * href="http://www.ietf.org/rfc/rfc3986.txt">RFC 3986</a>,
79 * section 3.3. Informally, this should be true:
80 *
81 * <!-- URI.create(relativeName).normalize().getPath().equals(relativeName) -->
82 * <pre> URI.{@linkplain java.net.URI#create create}(relativeName).{@linkplain java.net.URI#normalize() normalize}().{@linkplain java.net.URI#getPath getPath}().equals(relativeName)</pre>
205 * @param packageName a package name
206 * @param kinds return objects only of these kinds
207 * @param recurse if true include "subpackages"
208 * @return an Iterable of file objects matching the given criteria
209 * @throws IOException if an I/O error occurred, or if {@link
210 * #close} has been called and this file manager cannot be
211 * reopened
212 * @throws IllegalArgumentException if the location is a module-oriented location
213 * @throws IllegalStateException if {@link #close} has been called
214 * and this file manager cannot be reopened
215 */
216 Iterable<JavaFileObject> list(Location location,
217 String packageName,
218 Set<Kind> kinds,
219 boolean recurse)
220 throws IOException;
221
222 /**
223 * Infers a binary name of a file object based on a package-oriented location.
224 * The binary name returned might not be a valid binary name according to
225 * <cite>The Java Language Specification</cite>.
226 *
227 * @param location a location
228 * @param file a file object
229 * @return a binary name or {@code null} the file object is not
230 * found in the given location
231 * @throws IllegalArgumentException if the location is a module-oriented location
232 * @throws IllegalStateException if {@link #close} has been called
233 * and this file manager cannot be reopened
234 */
235 String inferBinaryName(Location location, JavaFileObject file);
236
237 /**
238 * Compares two file objects and return true if they represent the
239 * same underlying object.
240 *
241 * @param a a file object
242 * @param b a file object
243 * @return true if the given file objects represent the same
244 * underlying object
245 *
|