• file
• revisions
• annotate
• diff
• comparison
• raw

src/share/classes/javax/tools/StandardJavaFileManager.java@2eb010b6cb22 (annotated)

src/share/classes/javax/tools/StandardJavaFileManager.java

Thu, 31 Aug 2017 15:17:03 +0800

author

aoqi

date

Thu, 31 Aug 2017 15:17:03 +0800

changeset 2525

2eb010b6cb22

parent 554

9d9f26857129

parent 0

959103a6100f

permissions

-rw-r--r--

merge

aoqi@0	1	/*
aoqi@0	2	* Copyright (c) 2006, Oracle and/or its affiliates. All rights reserved.
aoqi@0	3	* DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
aoqi@0	4	*
aoqi@0	5	* This code is free software; you can redistribute it and/or modify it
aoqi@0	6	* under the terms of the GNU General Public License version 2 only, as
aoqi@0	7	* published by the Free Software Foundation. Oracle designates this
aoqi@0	8	* particular file as subject to the "Classpath" exception as provided
aoqi@0	9	* by Oracle in the LICENSE file that accompanied this code.
aoqi@0	10	*
aoqi@0	11	* This code is distributed in the hope that it will be useful, but WITHOUT
aoqi@0	12	* ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
aoqi@0	13	* FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
aoqi@0	14	* version 2 for more details (a copy is included in the LICENSE file that
aoqi@0	15	* accompanied this code).
aoqi@0	16	*
aoqi@0	17	* You should have received a copy of the GNU General Public License version
aoqi@0	18	* 2 along with this work; if not, write to the Free Software Foundation,
aoqi@0	19	* Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
aoqi@0	20	*
aoqi@0	21	* Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
aoqi@0	22	* or visit www.oracle.com if you need additional information or have any
aoqi@0	23	* questions.
aoqi@0	24	*/
aoqi@0	25
aoqi@0	26	package javax.tools;
aoqi@0	27
aoqi@0	28	import java.io.File;
aoqi@0	29	import java.io.IOException;
aoqi@0	30	import java.util.*;
aoqi@0	31
aoqi@0	32	/**
aoqi@0	33	* File manager based on {@linkplain File java.io.File}. A common way
aoqi@0	34	* to obtain an instance of this class is using {@linkplain
aoqi@0	35	* JavaCompiler#getStandardFileManager
aoqi@0	36	* getStandardFileManager}, for example:
aoqi@0	37	*
aoqi@0	38	* <pre>
aoqi@0	39	* JavaCompiler compiler = ToolProvider.getSystemJavaCompiler();
aoqi@0	40	* {@code DiagnosticCollector<JavaFileObject>} diagnostics =
aoqi@0	41	* new {@code DiagnosticCollector<JavaFileObject>()};
aoqi@0	42	* StandardJavaFileManager fm = compiler.getStandardFileManager(diagnostics, null, null);
aoqi@0	43	* </pre>
aoqi@0	44	*
aoqi@0	45	* This file manager creates file objects representing regular
aoqi@0	46	* {@linkplain File files},
aoqi@0	47	* {@linkplain java.util.zip.ZipEntry zip file entries}, or entries in
aoqi@0	48	* similar file system based containers. Any file object returned
aoqi@0	49	* from a file manager implementing this interface must observe the
aoqi@0	50	* following behavior:
aoqi@0	51	*
aoqi@0	52	* <ul>
aoqi@0	53	* <li>
aoqi@0	54	* File names need not be canonical.
aoqi@0	55	* </li>
aoqi@0	56	* <li>
aoqi@0	57	* For file objects representing regular files
aoqi@0	58	* <ul>
aoqi@0	59	* <li>
aoqi@0	60	* the method <code>{@linkplain FileObject#delete()}</code>
aoqi@0	61	* is equivalent to <code>{@linkplain File#delete()}</code>,
aoqi@0	62	* </li>
aoqi@0	63	* <li>
aoqi@0	64	* the method <code>{@linkplain FileObject#getLastModified()}</code>
aoqi@0	65	* is equivalent to <code>{@linkplain File#lastModified()}</code>,
aoqi@0	66	* </li>
aoqi@0	67	* <li>
aoqi@0	68	* the methods <code>{@linkplain FileObject#getCharContent(boolean)}</code>,
aoqi@0	69	* <code>{@linkplain FileObject#openInputStream()}</code>, and
aoqi@0	70	* <code>{@linkplain FileObject#openReader(boolean)}</code>
aoqi@0	71	* must succeed if the following would succeed (ignoring
aoqi@0	72	* encoding issues):
aoqi@0	73	* <blockquote>
aoqi@0	74	* <pre>new {@linkplain java.io.FileInputStream#FileInputStream(File) FileInputStream}(new {@linkplain File#File(java.net.URI) File}({@linkplain FileObject fileObject}.{@linkplain FileObject#toUri() toUri}()))</pre>
aoqi@0	75	* </blockquote>
aoqi@0	76	* </li>
aoqi@0	77	* <li>
aoqi@0	78	* and the methods
aoqi@0	79	* <code>{@linkplain FileObject#openOutputStream()}</code>, and
aoqi@0	80	* <code>{@linkplain FileObject#openWriter()}</code> must
aoqi@0	81	* succeed if the following would succeed (ignoring encoding
aoqi@0	82	* issues):
aoqi@0	83	* <blockquote>
aoqi@0	84	* <pre>new {@linkplain java.io.FileOutputStream#FileOutputStream(File) FileOutputStream}(new {@linkplain File#File(java.net.URI) File}({@linkplain FileObject fileObject}.{@linkplain FileObject#toUri() toUri}()))</pre>
aoqi@0	85	* </blockquote>
aoqi@0	86	* </li>
aoqi@0	87	* </ul>
aoqi@0	88	* </li>
aoqi@0	89	* <li>
aoqi@0	90	* The {@linkplain java.net.URI URI} returned from
aoqi@0	91	* <code>{@linkplain FileObject#toUri()}</code>
aoqi@0	92	* <ul>
aoqi@0	93	* <li>
aoqi@0	94	* must be {@linkplain java.net.URI#isAbsolute() absolute} (have a schema), and
aoqi@0	95	* </li>
aoqi@0	96	* <li>
aoqi@0	97	* must have a {@linkplain java.net.URI#normalize() normalized}
aoqi@0	98	* {@linkplain java.net.URI#getPath() path component} which
aoqi@0	99	* can be resolved without any process-specific context such
aoqi@0	100	* as the current directory (file names must be absolute).
aoqi@0	101	* </li>
aoqi@0	102	* </ul>
aoqi@0	103	* </li>
aoqi@0	104	* </ul>
aoqi@0	105	*
aoqi@0	106	* According to these rules, the following URIs, for example, are
aoqi@0	107	* allowed:
aoqi@0	108	* <ul>
aoqi@0	109	* <li>
aoqi@0	110	* <code>file:///C:/Documents%20and%20Settings/UncleBob/BobsApp/Test.java</code>
aoqi@0	111	* </li>
aoqi@0	112	* <li>
aoqi@0	113	* <code>jar:///C:/Documents%20and%20Settings/UncleBob/lib/vendorA.jar!com/vendora/LibraryClass.class</code>
aoqi@0	114	* </li>
aoqi@0	115	* </ul>
aoqi@0	116	* Whereas these are not (reason in parentheses):
aoqi@0	117	* <ul>
aoqi@0	118	* <li>
aoqi@0	119	* <code>file:BobsApp/Test.java</code> (the file name is relative
aoqi@0	120	* and depend on the current directory)
aoqi@0	121	* </li>
aoqi@0	122	* <li>
aoqi@0	123	* <code>jar:lib/vendorA.jar!com/vendora/LibraryClass.class</code>
aoqi@0	124	* (the first half of the path depends on the current directory,
aoqi@0	125	* whereas the component after ! is legal)
aoqi@0	126	* </li>
aoqi@0	127	* <li>
aoqi@0	128	* <code>Test.java</code> (this URI depends on the current
aoqi@0	129	* directory and does not have a schema)
aoqi@0	130	* </li>
aoqi@0	131	* <li>
aoqi@0	132	* <code>jar:///C:/Documents%20and%20Settings/UncleBob/BobsApp/../lib/vendorA.jar!com/vendora/LibraryClass.class</code>
aoqi@0	133	* (the path is not normalized)
aoqi@0	134	* </li>
aoqi@0	135	* </ul>
aoqi@0	136	*
aoqi@0	137	* @author Peter von der Ah&eacute;
aoqi@0	138	* @since 1.6
aoqi@0	139	*/
aoqi@0	140	public interface StandardJavaFileManager extends JavaFileManager {
aoqi@0	141
aoqi@0	142	/**
aoqi@0	143	* Compares two file objects and return true if they represent the
aoqi@0	144	* same canonical file, zip file entry, or entry in any file
aoqi@0	145	* system based container.
aoqi@0	146	*
aoqi@0	147	* @param a a file object
aoqi@0	148	* @param b a file object
aoqi@0	149	* @return true if the given file objects represent the same
aoqi@0	150	* canonical file or zip file entry; false otherwise
aoqi@0	151	*
aoqi@0	152	* @throws IllegalArgumentException if either of the arguments
aoqi@0	153	* were created with another file manager implementation
aoqi@0	154	*/
aoqi@0	155	boolean isSameFile(FileObject a, FileObject b);
aoqi@0	156
aoqi@0	157	/**
aoqi@0	158	* Gets file objects representing the given files.
aoqi@0	159	*
aoqi@0	160	* @param files a list of files
aoqi@0	161	* @return a list of file objects
aoqi@0	162	* @throws IllegalArgumentException if the list of files includes
aoqi@0	163	* a directory
aoqi@0	164	*/
aoqi@0	165	Iterable<? extends JavaFileObject> getJavaFileObjectsFromFiles(
aoqi@0	166	Iterable<? extends File> files);
aoqi@0	167
aoqi@0	168	/**
aoqi@0	169	* Gets file objects representing the given files.
aoqi@0	170	* Convenience method equivalent to:
aoqi@0	171	*
aoqi@0	172	* <pre>
aoqi@0	173	* getJavaFileObjectsFromFiles({@linkplain java.util.Arrays#asList Arrays.asList}(files))
aoqi@0	174	* </pre>
aoqi@0	175	*
aoqi@0	176	* @param files an array of files
aoqi@0	177	* @return a list of file objects
aoqi@0	178	* @throws IllegalArgumentException if the array of files includes
aoqi@0	179	* a directory
aoqi@0	180	* @throws NullPointerException if the given array contains null
aoqi@0	181	* elements
aoqi@0	182	*/
aoqi@0	183	Iterable<? extends JavaFileObject> getJavaFileObjects(File... files);
aoqi@0	184
aoqi@0	185	/**
aoqi@0	186	* Gets file objects representing the given file names.
aoqi@0	187	*
aoqi@0	188	* @param names a list of file names
aoqi@0	189	* @return a list of file objects
aoqi@0	190	* @throws IllegalArgumentException if the list of file names
aoqi@0	191	* includes a directory
aoqi@0	192	*/
aoqi@0	193	Iterable<? extends JavaFileObject> getJavaFileObjectsFromStrings(
aoqi@0	194	Iterable<String> names);
aoqi@0	195
aoqi@0	196	/**
aoqi@0	197	* Gets file objects representing the given file names.
aoqi@0	198	* Convenience method equivalent to:
aoqi@0	199	*
aoqi@0	200	* <pre>
aoqi@0	201	* getJavaFileObjectsFromStrings({@linkplain java.util.Arrays#asList Arrays.asList}(names))
aoqi@0	202	* </pre>
aoqi@0	203	*
aoqi@0	204	* @param names a list of file names
aoqi@0	205	* @return a list of file objects
aoqi@0	206	* @throws IllegalArgumentException if the array of file names
aoqi@0	207	* includes a directory
aoqi@0	208	* @throws NullPointerException if the given array contains null
aoqi@0	209	* elements
aoqi@0	210	*/
aoqi@0	211	Iterable<? extends JavaFileObject> getJavaFileObjects(String... names);
aoqi@0	212
aoqi@0	213	/**
aoqi@0	214	* Associates the given path with the given location. Any
aoqi@0	215	* previous value will be discarded.
aoqi@0	216	*
aoqi@0	217	* @param location a location
aoqi@0	218	* @param path a list of files, if {@code null} use the default
aoqi@0	219	* path for this location
aoqi@0	220	* @see #getLocation
aoqi@0	221	* @throws IllegalArgumentException if location is an output
aoqi@0	222	* location and path does not contain exactly one element
aoqi@0	223	* @throws IOException if location is an output location and path
aoqi@0	224	* does not represent an existing directory
aoqi@0	225	*/
aoqi@0	226	void setLocation(Location location, Iterable<? extends File> path)
aoqi@0	227	throws IOException;
aoqi@0	228
aoqi@0	229	/**
aoqi@0	230	* Gets the path associated with the given location.
aoqi@0	231	*
aoqi@0	232	* @param location a location
aoqi@0	233	* @return a list of files or {@code null} if this location has no
aoqi@0	234	* associated path
aoqi@0	235	* @see #setLocation
aoqi@0	236	*/
aoqi@0	237	Iterable<? extends File> getLocation(Location location);
aoqi@0	238
aoqi@0	239	}