Package javax.tools

Interface StandardJavaFileManager

  • All Superinterfaces:
    AutoCloseable, Closeable, Flushable, JavaFileManager, OptionChecker

    public interface StandardJavaFileManager
    extends JavaFileManager
    File manager based on java.io.File and java.nio.file.Path. A common way to obtain an instance of this class is using getStandardFileManager, for example:
       JavaCompiler compiler = ToolProvider.getSystemJavaCompiler();
       DiagnosticCollector<JavaFileObject> diagnostics =
           new DiagnosticCollector<JavaFileObject>();
       StandardJavaFileManager fm = compiler.getStandardFileManager(diagnostics, null, null);
     
    This file manager creates file objects representing regular files, zip file entries, or entries in similar file system based containers. Any file object returned from a file manager implementing this interface must observe the following behavior: According to these rules, the following URIs, for example, are allowed:
    • file:///C:/Documents%20and%20Settings/UncleBob/BobsApp/Test.java
    • jar:///C:/Documents%20and%20Settings/UncleBob/lib/vendorA.jar!/com/vendora/LibraryClass.class
    Whereas these are not (reason in parentheses):
    • file:BobsApp/Test.java (the file name is relative and depend on the current directory)
    • jar:lib/vendorA.jar!/com/vendora/LibraryClass.class (the first half of the path depends on the current directory, whereas the component after ! is legal)
    • Test.java (this URI depends on the current directory and does not have a schema)
    • jar:///C:/Documents%20and%20Settings/UncleBob/BobsApp/../lib/vendorA.jar!com/vendora/LibraryClass.class (the path is not normalized)

    All implementations of this interface must support Path objects representing files in the default file system. It is recommended that implementations should support Path objects from any filesystem.

    API Note:
    Some methods on this interface take a Collection<? extends Path> instead of Iterable<? extends Path>. This is to prevent the possibility of accidentally calling the method with a single Path as such an argument, because although Path implements Iterable<Path>, it would almost never be correct to call these methods with a single Path and have it be treated as an Iterable of its components.
    Since:
    1.6
    • Method Detail

      • isSameFile

        boolean isSameFile​(FileObject a,
                           FileObject b)
        Compares two file objects and return true if they represent the same canonical file, zip file entry, or entry in any file system based container.
        Specified by:
        isSameFile in interface JavaFileManager
        Parameters:
        a - a file object
        b - a file object
        Returns:
        true if the given file objects represent the same canonical file, zip file entry or path; false otherwise
        Throws:
        IllegalArgumentException - if either of the arguments were created with another file manager implementation
      • getJavaFileObjectsFromFiles

        Iterable<? extends JavaFileObject> getJavaFileObjectsFromFiles​(Iterable<? extends File> files)
        Returns file objects representing the given files.
        Parameters:
        files - a list of files
        Returns:
        a list of file objects
        Throws:
        IllegalArgumentException - if the list of files includes a directory
      • getJavaFileObjectsFromPaths

        default Iterable<? extends JavaFileObject> getJavaFileObjectsFromPaths​(Collection<? extends Path> paths)
        Returns file objects representing the given paths.
        Implementation Requirements:
        The default implementation converts each path to a file and calls getJavaObjectsFromFiles. IllegalArgumentException will be thrown if any of the paths cannot be converted to a file.
        Parameters:
        paths - a list of paths
        Returns:
        a list of file objects
        Throws:
        IllegalArgumentException - if the list of paths includes a directory or if this file manager does not support any of the given paths.
        Since:
        13
      • getJavaFileObjectsFromPaths

        @Deprecated(since="13")
        default Iterable<? extends JavaFileObject> getJavaFileObjectsFromPaths​(Iterable<? extends Path> paths)
        Deprecated.
        use getJavaFileObjectsFromPaths(Collection) instead, to prevent the possibility of accidentally calling the method with a single Path as such an argument. Although Path implements Iterable<Path>, it would almost never be correct to pass a single Path and have it be treated as an Iterable of its components.
        Returns file objects representing the given paths.
        Implementation Requirements:
        The default implementation converts each path to a file and calls getJavaObjectsFromFiles. IllegalArgumentException will be thrown if any of the paths cannot be converted to a file.
        Parameters:
        paths - a list of paths
        Returns:
        a list of file objects
        Throws:
        IllegalArgumentException - if the list of paths includes a directory or if this file manager does not support any of the given paths.
        Since:
        9
      • getJavaFileObjects

        Iterable<? extends JavaFileObject> getJavaFileObjects​(File... files)
        Returns file objects representing the given files. Convenience method equivalent to:
             getJavaFileObjectsFromFiles(Arrays.asList(files))
         
        Parameters:
        files - an array of files
        Returns:
        a list of file objects
        Throws:
        IllegalArgumentException - if the array of files includes a directory
        NullPointerException - if the given array contains null elements
      • getJavaFileObjects

        default Iterable<? extends JavaFileObject> getJavaFileObjects​(Path... paths)
        Returns file objects representing the given paths. Convenience method equivalent to:
             getJavaFileObjectsFromPaths(Arrays.asList(paths))
         
        Parameters:
        paths - an array of paths
        Returns:
        a list of file objects
        Throws:
        IllegalArgumentException - if the array of files includes a directory
        NullPointerException - if the given array contains null elements
        Since:
        9
      • getJavaFileObjectsFromStrings

        Iterable<? extends JavaFileObject> getJavaFileObjectsFromStrings​(Iterable<String> names)
        Returns file objects representing the given file names.
        Parameters:
        names - a list of file names
        Returns:
        a list of file objects
        Throws:
        IllegalArgumentException - if the list of file names includes a directory
      • getJavaFileObjects

        Iterable<? extends JavaFileObject> getJavaFileObjects​(String... names)
        Returns file objects representing the given file names. Convenience method equivalent to:
             getJavaFileObjectsFromStrings(Arrays.asList(names))
         
        Parameters:
        names - a list of file names
        Returns:
        a list of file objects
        Throws:
        IllegalArgumentException - if the array of file names includes a directory
        NullPointerException - if the given array contains null elements
      • setLocationFromPaths

        default void setLocationFromPaths​(JavaFileManager.Location location,
                                          Collection<? extends Path> paths)
                                   throws IOException
        Associates the given search path with the given location. Any previous value will be discarded. If the location is a module-oriented or output location, any module-specific associations set up by setLocationForModule will be cancelled.
        Implementation Requirements:
        The default implementation converts each path to a file and calls getJavaObjectsFromFiles. IllegalArgumentException will be thrown if any of the paths cannot be converted to a file.
        Parameters:
        location - a location
        paths - a list of paths, if null use the default search path for this location
        Throws:
        IllegalArgumentException - if location is an output location and paths does not contain exactly one element or if this file manager does not support any of the given paths
        IOException - if location is an output location and paths does not represent an existing directory
        Since:
        9
        See Also:
        getLocation(javax.tools.JavaFileManager.Location)
      • asPath

        default Path asPath​(FileObject file)
        Returns the path, if any, underlying this file object (optional operation). File objects derived from a FileSystem, including the default file system, typically have a corresponding underlying Path object. In such cases, this method may be used to access that object.
        Implementation Requirements:
        The default implementation throws UnsupportedOperationException for all files.
        Parameters:
        file - a file object
        Returns:
        a path representing the same underlying file system artifact
        Throws:
        IllegalArgumentException - if the file object does not have an underlying path
        UnsupportedOperationException - if the operation is not supported by this file manager
        Since:
        9
      • setPathFactory

        default void setPathFactory​(StandardJavaFileManager.PathFactory f)
        Specify a factory that can be used to generate a path from a string, or series of strings. If this method is not called, a factory whose getPath method is equivalent to calling java.nio.file.Paths.get(first, more) will be used.
        Implementation Requirements:
        The default implementation of this method ignores the factory that is provided.
        Parameters:
        f - the factory
        Since:
        9