1 /*

     2  * Copyright 2005-2006 Sun Microsystems, Inc.  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.  Sun designates this

     8  * particular file as subject to the "Classpath" exception as provided

     9  * by Sun 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 Sun Microsystems, Inc., 4150 Network Circle, Santa Clara,

    22  * CA 95054 USA or visit www.sun.com if you need additional information or

    23  * have any 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.Set;

    33 import static javax.tools.JavaFileObject.Kind;

    34 

    35 /**

    36  * File manager for tools operating on Java™ programming language

    37  * source and class files.  In this context, <em>file</em> means an

    38  * abstraction of regular files and other sources of data.

    39  *

    40  * <p>When constructing new JavaFileObjects, the file manager must

    41  * determine where to create them.  For example, if a file manager

    42  * manages regular files on a file system, it would most likely have a

    43  * current/working directory to use as default location when creating

    44  * or finding files.  A number of hints can be provided to a file

    45  * manager as to where to create files.  Any file manager might choose

    46  * to ignore these hints.

    47  *

    48  * <p>Some methods in this interface use class names.  Such class

    49  * names must be given in the Java Virtual Machine internal form of

    50  * fully qualified class and interface names.  For convenience '.'

    51  * and '/' are interchangeable.  The internal form is defined in

    52  * chapter four of the

    53  * <a href="http://java.sun.com/docs/books/vmspec/2nd-edition/jvms-maintenance.html">Java

    54  * Virtual Machine Specification</a>.

    55 

    56  * <blockquote><p>

    57  *   <i>Discussion:</i> this means that the names

    58  *   "java/lang.package-info", "java/lang/package-info",

    59  *   "java.lang.package-info", are valid and equivalent.  Compare to

    60  *   binary name as defined in the

    61  *   <a href="http://java.sun.com/docs/books/jls/">Java Language

    62  *   Specification (JLS)</a> section 13.1 "The Form of a Binary".

    63  * </p></blockquote>

    64  *

    65  * <p>The case of names is significant.  All names should be treated

    66  * as case-sensitive.  For example, some file systems have

    67  * case-insensitive, case-aware file names.  File objects representing

    68  * such files should take care to preserve case by using {@link

    69  * java.io.File#getCanonicalFile} or similar means.  If the system is

    70  * not case-aware, file objects must use other means to preserve case.

    71  *

    72  * <p><em><a name="relative_name">Relative names</a>:</em> some

    73  * methods in this interface use relative names.  A relative name is a

    74  * non-null, non-empty sequence of path segments separated by '/'.

    75  * '.' or '..'  are invalid path segments.  A valid relative name must

    76  * match the "path-rootless" rule of <a

    77  * href="http://www.ietf.org/rfc/rfc3986.txt">RFC&nbsp;3986</a>,

    78  * section 3.3.  Informally, this should be true:

    79  *

    80  * <!-- URI.create(relativeName).normalize().getPath().equals(relativeName) -->

    81  * <pre>  URI.{@linkplain java.net.URI#create create}(relativeName).{@linkplain java.net.URI#normalize normalize}().{@linkplain java.net.URI#getPath getPath}().equals(relativeName)</pre>

    82  *

    83  * <p>All methods in this interface might throw a SecurityException.

    84  *

    85  * <p>An object of this interface is not required to support

    86  * multi-threaded access, that is, be synchronized.  However, it must

    87  * support concurrent access to different file objects created by this

    88  * object.

    89  *

    90  * <p><em>Implementation note:</em> a consequence of this requirement

    91  * is that a trivial implementation of output to a {@linkplain

    92  * java.util.jar.JarOutputStream} is not a sufficient implementation.

    93  * That is, rather than creating a JavaFileObject that returns the

    94  * JarOutputStream directly, the contents must be cached until closed

    95  * and then written to the JarOutputStream.

    96  *

    97  * <p>Unless explicitly allowed, all methods in this interface might

    98  * throw a NullPointerException if given a {@code null} argument.

    99  *

   100  * @author Peter von der Ahé

   101  * @author Jonathan Gibbons

   102  * @see JavaFileObject

   103  * @see FileObject

   104  * @since 1.6

   105  */

   106 public interface JavaFileManager extends Closeable, Flushable, OptionChecker {

   107 

   108     /**

   109      * Interface for locations of file objects.  Used by file managers

   110      * to determine where to place or search for file objects.

   111      */

   112     interface Location {

   113         /**

   114          * Gets the name of this location.

   115          *

   116          * @return a name

   117          */

   118         String getName();

   119 

   120         /**

   121          * Determines if this is an output location.  An output

   122          * location is a location that is conventionally used for

   123          * output.

   124          *

   125          * @return true if this is an output location, false otherwise

   126          */

   127         boolean isOutputLocation();

   128     }

   129 

   130     /**

   131      * Gets a class loader for loading plug-ins from the given

   132      * location.  For example, to load annotation processors, a

   133      * compiler will request a class loader for the {@link

   134      * StandardLocation#ANNOTATION_PROCESSOR_PATH

   135      * ANNOTATION_PROCESSOR_PATH} location.

   136      *

   137      * @param location a location

   138      * @return a class loader for the given location; or {@code null}

   139      * if loading plug-ins from the given location is disabled or if

   140      * the location is not known

   141      * @throws SecurityException if a class loader can not be created

   142      * in the current security context

   143      * @throws IllegalStateException if {@link #close} has been called

   144      * and this file manager cannot be reopened

   145      */

   146     ClassLoader getClassLoader(Location location);

   147 

   148     /**

   149      * Lists all file objects matching the given criteria in the given

   150      * location.  List file objects in "subpackages" if recurse is

   151      * true.

   152      *

   153      * <p>Note: even if the given location is unknown to this file

   154      * manager, it may not return {@code null}.  Also, an unknown

   155      * location may not cause an exception.

   156      *

   157      * @param location     a location

   158      * @param packageName  a package name

   159      * @param kinds        return objects only of these kinds

   160      * @param recurse      if true include "subpackages"

   161      * @return an Iterable of file objects matching the given criteria

   162      * @throws IOException if an I/O error occurred, or if {@link

   163      * #close} has been called and this file manager cannot be

   164      * reopened

   165      * @throws IllegalStateException if {@link #close} has been called

   166      * and this file manager cannot be reopened

   167      */

   168     Iterable<JavaFileObject> list(Location location,

   169                                   String packageName,

   170                                   Set<Kind> kinds,

   171                                   boolean recurse)

   172         throws IOException;

   173 

   174     /**

   175      * Infers a binary name of a file object based on a location.  The

   176      * binary name returned might not be a valid JLS binary name.

   177      *

   178      * @param location a location

   179      * @param file a file object

   180      * @return a binary name or {@code null} the file object is not

   181      * found in the given location

   182      * @throws IllegalStateException if {@link #close} has been called

   183      * and this file manager cannot be reopened

   184      */

   185     String inferBinaryName(Location location, JavaFileObject file);

   186 

   187     /**

   188      * Compares two file objects and return true if they represent the

   189      * same underlying object.

   190      *

   191      * @param a a file object

   192      * @param b a file object

   193      * @return true if the given file objects represent the same

   194      * underlying object

   195      *

   196      * @throws IllegalArgumentException if either of the arguments

   197      * were created with another file manager and this file manager

   198      * does not support foreign file objects

   199      */

   200     boolean isSameFile(FileObject a, FileObject b);

   201 

   202     /**

   203      * Handles one option.  If {@code current} is an option to this

   204      * file manager it will consume any arguments to that option from

   205      * {@code remaining} and return true, otherwise return false.

   206      *

   207      * @param current current option

   208      * @param remaining remaining options

   209      * @return true if this option was handled by this file manager,

   210      * false otherwise

   211      * @throws IllegalArgumentException if this option to this file

   212      * manager is used incorrectly

   213      * @throws IllegalStateException if {@link #close} has been called

   214      * and this file manager cannot be reopened

   215      */

   216     boolean handleOption(String current, Iterator<String> remaining);

   217 

   218     /**

   219      * Determines if a location is known to this file manager.

   220      *

   221      * @param location a location

   222      * @return true if the location is known

   223      */

   224     boolean hasLocation(Location location);

   225 

   226     /**

   227      * Gets a {@linkplain JavaFileObject file object} for input

   228      * representing the specified class of the specified kind in the

   229      * given location.

   230      *

   231      * @param location a location

   232      * @param className the name of a class

   233      * @param kind the kind of file, must be one of {@link

   234      * JavaFileObject.Kind#SOURCE SOURCE} or {@link

   235      * JavaFileObject.Kind#CLASS CLASS}

   236      * @return a file object, might return {@code null} if the

   237      * file does not exist

   238      * @throws IllegalArgumentException if the location is not known

   239      * to this file manager and the file manager does not support

   240      * unknown locations, or if the kind is not valid

   241      * @throws IOException if an I/O error occurred, or if {@link

   242      * #close} has been called and this file manager cannot be

   243      * reopened

   244      * @throws IllegalStateException if {@link #close} has been called

   245      * and this file manager cannot be reopened

   246      */

   247     JavaFileObject getJavaFileForInput(Location location,

   248                                        String className,

   249                                        Kind kind)

   250         throws IOException;

   251 

   252     /**

   253      * Gets a {@linkplain JavaFileObject file object} for output

   254      * representing the specified class of the specified kind in the

   255      * given location.

   256      *

   257      * <p>Optionally, this file manager might consider the sibling as

   258      * a hint for where to place the output.  The exact semantics of

   259      * this hint is unspecified.  Sun's compiler, javac, for

   260      * example, will place class files in the same directories as

   261      * originating source files unless a class file output directory

   262      * is provided.  To facilitate this behavior, javac might provide

   263      * the originating source file as sibling when calling this

   264      * method.

   265      *

   266      * @param location a location

   267      * @param className the name of a class

   268      * @param kind the kind of file, must be one of {@link

   269      * JavaFileObject.Kind#SOURCE SOURCE} or {@link

   270      * JavaFileObject.Kind#CLASS CLASS}

   271      * @param sibling a file object to be used as hint for placement;

   272      * might be {@code null}

   273      * @return a file object for output

   274      * @throws IllegalArgumentException if sibling is not known to

   275      * this file manager, or if the location is not known to this file

   276      * manager and the file manager does not support unknown

   277      * locations, or if the kind is not valid

   278      * @throws IOException if an I/O error occurred, or if {@link

   279      * #close} has been called and this file manager cannot be

   280      * reopened

   281      * @throws IllegalStateException {@link #close} has been called

   282      * and this file manager cannot be reopened

   283      */

   284     JavaFileObject getJavaFileForOutput(Location location,

   285                                         String className,

   286                                         Kind kind,

   287                                         FileObject sibling)

   288         throws IOException;

   289 

   290     /**

   291      * Gets a {@linkplain FileObject file object} for input

   292      * representing the specified <a href="JavaFileManager.html#relative_name">relative

   293      * name</a> in the specified package in the given location.

   294      *

   295      * <p>If the returned object represents a {@linkplain

   296      * JavaFileObject.Kind#SOURCE source} or {@linkplain

   297      * JavaFileObject.Kind#CLASS class} file, it must be an instance

   298      * of {@link JavaFileObject}.

   299      *

   300      * <p>Informally, the file object returned by this method is

   301      * located in the concatenation of the location, package name, and

   302      * relative name.  For example, to locate the properties file

   303      * "resources/compiler.properties" in the package

   304      * "com.sun.tools.javac" in the {@linkplain

   305      * StandardLocation#SOURCE_PATH SOURCE_PATH} location, this method

   306      * might be called like so:

   307      *

   308      * <pre>getFileForInput(SOURCE_PATH, "com.sun.tools.javac", "resources/compiler.properties");</pre>

   309      *

   310      * <p>If the call was executed on Windows, with SOURCE_PATH set to

   311      * <code>"C:\Documents&nbsp;and&nbsp;Settings\UncleBob\src\share\classes"</code>,

   312      * a valid result would be a file object representing the file

   313      * <code>"C:\Documents&nbsp;and&nbsp;Settings\UncleBob\src\share\classes\com\sun\tools\javac\resources\compiler.properties"</code>.

   314      *

   315      * @param location a location

   316      * @param packageName a package name

   317      * @param relativeName a relative name

   318      * @return a file object, might return {@code null} if the file

   319      * does not exist

   320      * @throws IllegalArgumentException if the location is not known

   321      * to this file manager and the file manager does not support

   322      * unknown locations, or if {@code relativeName} is not valid

   323      * @throws IOException if an I/O error occurred, or if {@link

   324      * #close} has been called and this file manager cannot be

   325      * reopened

   326      * @throws IllegalStateException if {@link #close} has been called

   327      * and this file manager cannot be reopened

   328      */

   329     FileObject getFileForInput(Location location,

   330                                String packageName,

   331                                String relativeName)

   332         throws IOException;

   333 

   334     /**

   335      * Gets a {@linkplain FileObject file object} for output

   336      * representing the specified <a href="JavaFileManager.html#relative_name">relative

   337      * name</a> in the specified package in the given location.

   338      *

   339      * <p>Optionally, this file manager might consider the sibling as

   340      * a hint for where to place the output.  The exact semantics of

   341      * this hint is unspecified.  Sun's compiler, javac, for

   342      * example, will place class files in the same directories as

   343      * originating source files unless a class file output directory

   344      * is provided.  To facilitate this behavior, javac might provide

   345      * the originating source file as sibling when calling this

   346      * method.

   347      *

   348      * <p>If the returned object represents a {@linkplain

   349      * JavaFileObject.Kind#SOURCE source} or {@linkplain

   350      * JavaFileObject.Kind#CLASS class} file, it must be an instance

   351      * of {@link JavaFileObject}.

   352      *

   353      * <p>Informally, the file object returned by this method is

   354      * located in the concatenation of the location, package name, and

   355      * relative name or next to the sibling argument.  See {@link

   356      * #getFileForInput getFileForInput} for an example.

   357      *

   358      * @param location a location

   359      * @param packageName a package name

   360      * @param relativeName a relative name

   361      * @param sibling a file object to be used as hint for placement;

   362      * might be {@code null}

   363      * @return a file object

   364      * @throws IllegalArgumentException if sibling is not known to

   365      * this file manager, or if the location is not known to this file

   366      * manager and the file manager does not support unknown

   367      * locations, or if {@code relativeName} is not valid

   368      * @throws IOException if an I/O error occurred, or if {@link

   369      * #close} has been called and this file manager cannot be

   370      * reopened

   371      * @throws IllegalStateException if {@link #close} has been called

   372      * and this file manager cannot be reopened

   373      */

   374     FileObject getFileForOutput(Location location,

   375                                 String packageName,

   376                                 String relativeName,

   377                                 FileObject sibling)

   378         throws IOException;

   379 

   380     /**

   381      * Flushes any resources opened for output by this file manager

   382      * directly or indirectly.  Flushing a closed file manager has no

   383      * effect.

   384      *

   385      * @throws IOException if an I/O error occurred

   386      * @see #close

   387      */

   388     void flush() throws IOException;

   389 

   390     /**

   391      * Releases any resources opened by this file manager directly or

   392      * indirectly.  This might render this file manager useless and

   393      * the effect of subsequent calls to methods on this object or any

   394      * objects obtained through this object is undefined unless

   395      * explicitly allowed.  However, closing a file manager which has

   396      * already been closed has no effect.

   397      *

   398      * @throws IOException if an I/O error occurred

   399      * @see #flush

   400      */

   401     void close() throws IOException;

   402 }