1 /*
2 * Copyright (c) 2006, 2017, Oracle and/or its affiliates. All rights reserved.
3 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
4 *
5 * This code is free software; you can redistribute it and/or modify it
6 * under the terms of the GNU General Public License version 2 only, as
7 * published by the Free Software Foundation. Oracle designates this
8 * particular file as subject to the "Classpath" exception as provided
9 * by Oracle in the LICENSE file that accompanied this code.
10 *
11 * This code is distributed in the hope that it will be useful, but WITHOUT
12 * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
13 * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
14 * version 2 for more details (a copy is included in the LICENSE file that
15 * accompanied this code).
16 *
17 * You should have received a copy of the GNU General Public License version
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.File;
29 import java.io.IOException;
30 import java.nio.file.Path;
31 import java.util.Arrays;
32 import java.util.Collection;
33
34 import static javax.tools.FileManagerUtils.*;
35
36 /**
37 * File manager based on {@linkplain File java.io.File} and {@linkplain Path java.nio.file.Path}.
38 *
39 * A common way to obtain an instance of this class is using
40 * {@linkplain JavaCompiler#getStandardFileManager getStandardFileManager}, for example:
41 *
42 * <pre>
43 * JavaCompiler compiler = ToolProvider.getSystemJavaCompiler();
44 * {@code DiagnosticCollector<JavaFileObject>} diagnostics =
45 * new {@code DiagnosticCollector<JavaFileObject>()};
46 * StandardJavaFileManager fm = compiler.getStandardFileManager(diagnostics, null, null);
47 * </pre>
48 *
49 * This file manager creates file objects representing regular
50 * {@linkplain File files},
51 * {@linkplain java.util.zip.ZipEntry zip file entries}, or entries in
52 * similar file system based containers. Any file object returned
53 * from a file manager implementing this interface must observe the
54 * following behavior:
55 *
56 * <ul>
57 * <li>
58 * File names need not be canonical.
59 * </li>
60 * <li>
61 * For file objects representing regular files
62 * <ul>
63 * <li>
64 * the method <code>{@linkplain FileObject#delete()}</code>
65 * is equivalent to <code>{@linkplain File#delete()}</code>,
66 * </li>
67 * <li>
68 * the method <code>{@linkplain FileObject#getLastModified()}</code>
69 * is equivalent to <code>{@linkplain File#lastModified()}</code>,
70 * </li>
71 * <li>
72 * the methods <code>{@linkplain FileObject#getCharContent(boolean)}</code>,
73 * <code>{@linkplain FileObject#openInputStream()}</code>, and
74 * <code>{@linkplain FileObject#openReader(boolean)}</code>
75 * must succeed if the following would succeed (ignoring
76 * encoding issues):
77 * <blockquote>
78 * <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>
79 * </blockquote>
80 * </li>
81 * <li>
82 * and the methods
83 * <code>{@linkplain FileObject#openOutputStream()}</code>, and
84 * <code>{@linkplain FileObject#openWriter()}</code> must
85 * succeed if the following would succeed (ignoring encoding
86 * issues):
87 * <blockquote>
88 * <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>
89 * </blockquote>
90 * </li>
91 * </ul>
92 * </li>
93 * <li>
94 * The {@linkplain java.net.URI URI} returned from
95 * <code>{@linkplain FileObject#toUri()}</code>
96 * <ul>
97 * <li>
98 * must be {@linkplain java.net.URI#isAbsolute() absolute} (have a schema), and
99 * </li>
100 * <li>
101 * must have a {@linkplain java.net.URI#normalize() normalized}
102 * {@linkplain java.net.URI#getPath() path component} which
103 * can be resolved without any process-specific context such
104 * as the current directory (file names must be absolute).
105 * </li>
106 * </ul>
107 * </li>
108 * </ul>
109 *
110 * According to these rules, the following URIs, for example, are
111 * allowed:
112 * <ul>
113 * <li>
114 * <code>file:///C:/Documents%20and%20Settings/UncleBob/BobsApp/Test.java</code>
115 * </li>
116 * <li>
117 * <code>jar:///C:/Documents%20and%20Settings/UncleBob/lib/vendorA.jar!/com/vendora/LibraryClass.class</code>
118 * </li>
119 * </ul>
120 * Whereas these are not (reason in parentheses):
121 * <ul>
122 * <li>
123 * <code>file:BobsApp/Test.java</code> (the file name is relative
124 * and depend on the current directory)
125 * </li>
126 * <li>
127 * <code>jar:lib/vendorA.jar!/com/vendora/LibraryClass.class</code>
128 * (the first half of the path depends on the current directory,
129 * whereas the component after ! is legal)
130 * </li>
131 * <li>
132 * <code>Test.java</code> (this URI depends on the current
133 * directory and does not have a schema)
134 * </li>
135 * <li>
136 * <code>jar:///C:/Documents%20and%20Settings/UncleBob/BobsApp/../lib/vendorA.jar!com/vendora/LibraryClass.class</code>
137 * (the path is not normalized)
138 * </li>
139 * </ul>
140 *
141 * <p>All implementations of this interface must support Path objects representing
142 * files in the {@linkplain java.nio.file.FileSystems#getDefault() default file system.}
143 * It is recommended that implementations should support Path objects from any filesystem.</p>
144 *
145 *
146 * @apiNote
147 * Some methods on this interface take a {@code Collection<? extends Path>}
148 * instead of {@code Iterable<? extends Path>}.
149 * This is to prevent the possibility of accidentally calling the method
150 * with a single {@code Path} as such an argument, because although
151 * {@code Path} implements {@code Iterable<Path>}, it would almost never be
152 * correct to call these methods with a single {@code Path} and have it be treated as
153 * an {@code Iterable} of its components.
154 *
155 *
156 * @author Peter von der Ahé
157 * @since 1.6
158 */
159 public interface StandardJavaFileManager extends JavaFileManager {
160
161 /**
162 * Compares two file objects and return true if they represent the
163 * same canonical file, zip file entry, or entry in any file
164 * system based container.
165 *
166 * @param a a file object
167 * @param b a file object
168 * @return true if the given file objects represent the same
169 * canonical file, zip file entry or path; false otherwise
170 *
171 * @throws IllegalArgumentException if either of the arguments
172 * were created with another file manager implementation
173 */
174 @Override
175 boolean isSameFile(FileObject a, FileObject b);
176
177 /**
178 * Returns file objects representing the given files.
179 *
180 * @param files a list of files
181 * @return a list of file objects
182 * @throws IllegalArgumentException if the list of files includes
183 * a directory
184 */
185 Iterable<? extends JavaFileObject> getJavaFileObjectsFromFiles(
186 Iterable<? extends File> files);
187
188 /**
189 * Returns file objects representing the given paths.
190 *
191 * @implSpec
192 * The default implementation converts each path to a file and calls
193 * {@link #getJavaFileObjectsFromFiles getJavaObjectsFromFiles}.
194 * IllegalArgumentException will be thrown if any of the paths
195 * cannot be converted to a file.
196 *
197 * @param paths a list of paths
198 * @return a list of file objects
199 * @throws IllegalArgumentException if the list of paths includes
200 * a directory or if this file manager does not support any of the
201 * given paths.
202 *
203 * @since 9
204 */
205 default Iterable<? extends JavaFileObject> getJavaFileObjectsFromPaths(
206 Iterable<? extends Path> paths) {
207 return getJavaFileObjectsFromFiles(asFiles(paths));
208 }
209
210 /**
211 * Returns file objects representing the given files.
212 * Convenience method equivalent to:
213 *
214 * <pre>
215 * getJavaFileObjectsFromFiles({@linkplain java.util.Arrays#asList Arrays.asList}(files))
216 * </pre>
217 *
218 * @param files an array of files
219 * @return a list of file objects
220 * @throws IllegalArgumentException if the array of files includes
221 * a directory
222 * @throws NullPointerException if the given array contains null
223 * elements
224 */
225 Iterable<? extends JavaFileObject> getJavaFileObjects(File... files);
226
227 /**
228 * Returns file objects representing the given paths.
229 * Convenience method equivalent to:
230 *
231 * <pre>
232 * getJavaFileObjectsFromPaths({@linkplain java.util.Arrays#asList Arrays.asList}(paths))
233 * </pre>
234 *
235 * @param paths an array of paths
236 * @return a list of file objects
237 * @throws IllegalArgumentException if the array of files includes
238 * a directory
239 * @throws NullPointerException if the given array contains null
240 * elements
241 *
242 * @since 9
243 */
244 default Iterable<? extends JavaFileObject> getJavaFileObjects(Path... paths) {
245 return getJavaFileObjectsFromPaths(Arrays.asList(paths));
246 }
247
248 /**
249 * Returns file objects representing the given file names.
250 *
251 * @param names a list of file names
252 * @return a list of file objects
253 * @throws IllegalArgumentException if the list of file names
254 * includes a directory
255 */
256 Iterable<? extends JavaFileObject> getJavaFileObjectsFromStrings(
257 Iterable<String> names);
258
259 /**
260 * Returns file objects representing the given file names.
261 * Convenience method equivalent to:
262 *
263 * <pre>
264 * getJavaFileObjectsFromStrings({@linkplain java.util.Arrays#asList Arrays.asList}(names))
265 * </pre>
266 *
267 * @param names a list of file names
268 * @return a list of file objects
269 * @throws IllegalArgumentException if the array of file names
270 * includes a directory
271 * @throws NullPointerException if the given array contains null
272 * elements
273 */
274 Iterable<? extends JavaFileObject> getJavaFileObjects(String... names);
275
276 /**
277 * Associates the given search path with the given location. Any
278 * previous value will be discarded.
279 *
280 * If the location is a module-oriented or output location, any module-specific
281 * associations set up by {@linkplain #setLocationForModule setLocationForModule}
282 * will be cancelled.
283 *
284 * @param location a location
285 * @param files a list of files, if {@code null} use the default
286 * search path for this location
287 * @see #getLocation
288 * @throws IllegalArgumentException if {@code location} is an output
289 * location and {@code files} does not contain exactly one element
290 * @throws IOException if {@code location} is an output location and
291 * does not represent an existing directory
292 */
293 void setLocation(Location location, Iterable<? extends File> files)
294 throws IOException;
295
296 /**
297 * Associates the given search path with the given location.
298 * Any previous value will be discarded.
299 *
300 * If the location is a module-oriented or output location, any module-specific
301 * associations set up by {@linkplain #setLocationForModule setLocationForModule}
302 * will be cancelled.
303 *
304 * @implSpec
305 * The default implementation converts each path to a file and calls
306 * {@link #getJavaFileObjectsFromFiles getJavaObjectsFromFiles}.
307 * {@linkplain IllegalArgumentException IllegalArgumentException}
308 * will be thrown if any of the paths cannot be converted to a file.
309 *
310 * @param location a location
311 * @param paths a list of paths, if {@code null} use the default
312 * search path for this location
313 * @see #getLocation
314 * @throws IllegalArgumentException if {@code location} is an output
315 * location and {@code paths} does not contain exactly one element
316 * or if this file manager does not support any of the given paths
317 * @throws IOException if {@code location} is an output location and
318 * {@code paths} does not represent an existing directory
319 *
320 * @since 9
321 */
322 default void setLocationFromPaths(Location location, Collection<? extends Path> paths)
323 throws IOException {
324 setLocation(location, asFiles(paths));
325 }
326
327 /**
328 * Associates the given search path with the given module and location,
329 * which must be a module-oriented or output location.
330 * Any previous value will be discarded.
331 * This overrides any default association derived from the search path
332 * associated with the location itself.
333 *
334 * All such module-specific associations will be cancelled if a
335 * new search path is associated with the location by calling
336 * {@linkplain #setLocation setLocation } or
337 * {@linkplain #setLocationFromPaths setLocationFromPaths}.
338 *
339 * @throws IllegalStateException if the location is not a module-oriented
340 * or output location.
341 * @throws UnsupportedOperationException if this operation is not supported by
342 * this file manager.
343 * @throws IOException if {@code location} is an output location and
344 * {@code paths} does not represent an existing directory
345 *
346 * @param location the location
347 * @param moduleName the name of the module
348 * @param paths the search path to associate with the location and module.
349 *
350 * @see setLocation
351 * @see setLocationFromPaths
352 *
353 * @since 9
354 */
355 default void setLocationForModule(Location location, String moduleName,
356 Collection<? extends Path> paths) throws IOException {
357 throw new UnsupportedOperationException();
358 }
359
360 /**
361 * Returns the search path associated with the given location.
362 *
363 * @param location a location
364 * @return a list of files or {@code null} if this location has no
365 * associated search path
366 * @throws IllegalStateException if any element of the search path
367 * cannot be converted to a {@linkplain File}.
368 *
369 * @see #setLocation
370 * @see Path#toFile
371 */
372 Iterable<? extends File> getLocation(Location location);
373
374 /**
375 * Returns the search path associated with the given location.
376 *
377 * @implSpec
378 * The default implementation calls {@link #getLocation getLocation}
379 * and then returns an {@code Iterable} formed by calling {@code toPath()}
380 * on each {@code File} returned from {@code getLocation}.
381 *
382 * @param location a location
383 * @return a list of paths or {@code null} if this location has no
384 * associated search path
385 *
386 * @see #setLocationFromPaths
387 * @since 9
388 */
389 default Iterable<? extends Path> getLocationAsPaths(Location location) {
390 return asPaths(getLocation(location));
391 }
392
393 /**
394 * Returns the path, if any, underlying this file object (optional operation).
395 * File objects derived from a {@link java.nio.file.FileSystem FileSystem},
396 * including the default file system, typically have a corresponding underlying
397 * {@link java.nio.file.Path Path} object. In such cases, this method may be
398 * used to access that object.
399 *
400 * @implSpec
401 * The default implementation throws {@link UnsupportedOperationException}
402 * for all files.
403 *
404 * @param file a file object
405 * @return a path representing the same underlying file system artifact
406 * @throws IllegalArgumentException if the file object does not have an underlying path
407 * @throws UnsupportedOperationException if the operation is not supported by this file manager
408 *
409 * @since 9
410 */
411 default Path asPath(FileObject file) {
412 throw new UnsupportedOperationException();
413 }
414
415 /**
416 * Factory to create {@code Path} objects from strings.
417 *
418 * @since 9
419 */
420 interface PathFactory {
421 /**
422 * Converts a path string, or a sequence of strings that when joined form a path string, to a Path.
423 *
424 * @param first the path string or initial part of the path string
425 * @param more additional strings to be joined to form the path string
426 * @return the resulting {@code Path}
427 */
428 Path getPath(String first, String... more);
429 }
430
431 /**
432 * Specify a factory that can be used to generate a path from a string, or series of strings.
433 *
434 * If this method is not called, a factory whose {@code getPath} method is
435 * equivalent to calling
436 * {@link java.nio.file.Paths#get(String, String...) java.nio.file.Paths.get(first, more)}
437 * will be used.
438 *
439 * @implSpec
440 * The default implementation of this method ignores the factory that is provided.
441 *
442 * @param f the factory
443 *
444 * @since 9
445 */
446 default void setPathFactory(PathFactory f) { }
447 }