Package org.graalvm.polyglot.io

Interface FileSystem

public interface FileSystem
Service-provider for Truffle files.
Since:
19.0

  • Method Details

    • parsePath

      Path parsePath(URI uri)
      Parses a path from an URI.
      Parameters:
      uri - the URI to be converted to Path
      Returns:
      the Path representing given URI
      Throws:
      UnsupportedOperationException - when URI scheme is not supported
      IllegalArgumentException - if preconditions on the uri do not hold. The format of the URI is FileSystem specific.
      Since:
      19.0

    • parsePath

      Path parsePath(String path)
      Parses a path from a String. This method is called only on the FileSystem with file scheme.
      Parameters:
      path - the string path to be converted to Path
      Returns:
      the Path
      Throws:
      UnsupportedOperationException - when the FileSystem supports only URI
      IllegalArgumentException - if the path string cannot be converted to a Path
      Since:
      19.0

    • checkAccess

      void checkAccess(Path path, Set<? extends AccessMode> modes, LinkOption... linkOptions) throws IOException
      Checks existence and accessibility of a file.
      Parameters:
      path - the path to the file to check
      modes - the access modes to check, possibly empty to check existence only.
      linkOptions - options determining how the symbolic links should be handled
      Throws:
      NoSuchFileException - if the file denoted by the path does not exist
      IOException - in case of IO error
      SecurityException - if this FileSystem denied the operation
      Since:
      19.0

    • createDirectory

      void createDirectory(Path dir, FileAttribute<?>... attrs) throws IOException
      Creates a directory.
      Parameters:
      dir - the directory to create
      attrs - the optional attributes to set atomically when creating the directory
      Throws:
      FileAlreadyExistsException - if a file on given path already exists
      IOException - in case of IO error
      UnsupportedOperationException - if the attributes contain an attribute which cannot be set atomically
      SecurityException - if this FileSystem denied the operation
      Since:
      19.0

    • delete

      void delete(Path path) throws IOException
      Deletes a file.
      Parameters:
      path - the path to the file to delete
      Throws:
      NoSuchFileException - if a file on given path does not exist
      DirectoryNotEmptyException - if the path denotes a non empty directory
      IOException - in case of IO error
      SecurityException - if this FileSystem denied the operation
      Since:
      19.0

    • newByteChannel

      SeekableByteChannel newByteChannel(Path path, Set<? extends OpenOption> options, FileAttribute<?>... attrs) throws IOException
      Opens or creates a file returning a SeekableByteChannel to access the file content.
      Parameters:
      path - the path to the file to open
      options - the options specifying how the file should be opened
      attrs - the optional attributes to set atomically when creating the new file
      Returns:
      the created SeekableByteChannel
      Throws:
      FileAlreadyExistsException - if StandardOpenOption.CREATE_NEW option is set and a file already exists on given path
      IOException - in case of IO error
      UnsupportedOperationException - if the attributes contain an attribute which cannot be set atomically
      IllegalArgumentException - in case of invalid options combination
      SecurityException - if this FileSystem denied the operation
      Since:
      19.0

    • newDirectoryStream

      DirectoryStream<Path> newDirectoryStream(Path dir, DirectoryStream.Filter<? super Path> filter) throws IOException
      Returns directory entries.
      Parameters:
      dir - the path to the directory to iterate entries for
      filter - the filter
      Returns:
      the new DirectoryStream
      Throws:
      NotDirectoryException - when given path does not denote a directory
      IOException - in case of IO error
      SecurityException - if this FileSystem denied the operation
      Since:
      19.0

    • toAbsolutePath

      Path toAbsolutePath(Path path)
      Resolves given path to an absolute path.
      Parameters:
      path - the path to resolve, may be a non normalized path
      Returns:
      an absolute Path
      Throws:
      SecurityException - if this FileSystem denied the operation
      Since:
      19.0

    • toRealPath

      Path toRealPath(Path path, LinkOption... linkOptions) throws IOException
      Returns the real (canonical) path of an existing file.
      Parameters:
      path - the path to resolve, may be a non normalized path
      linkOptions - options determining how the symbolic links should be handled
      Returns:
      an absolute canonical path
      Throws:
      IOException - in case of IO error
      SecurityException - if this FileSystem denied the operation
      Since:
      19.0

    • readAttributes

      Map<String,Object> readAttributes(Path path, String attributes, LinkOption... options) throws IOException
      Reads a file's attributes as a bulk operation.
      Parameters:
      path - the path to file to read attributes for
      attributes - the attributes to read. The attributes parameter has the form: [view-name:]attribute-list. The optional view-name corresponds to AttributeView.name() and determines the set of attributes, the default value is "basic". The attribute-list is a comma separated list of attributes. If the attribute-list contains '*' then all the attributes from given view are read.
      options - the options determining how the symbolic links should be handled
      Returns:
      the Map containing the file attributes. The map's keys are attribute names, map's values are the attribute values. The map may contain a subset of required attributes in case when the FileSystem does not support some of the required attributes.
      Throws:
      UnsupportedOperationException - if the attribute view is not supported. At least the "basic" attribute view has to be supported by the file system.
      IllegalArgumentException - is the attribute-list is empty or contains an unknown attribute
      IOException - in case of IO error
      SecurityException - if this FileSystem denied the operation
      Since:
      19.0

    • setAttribute

      default void setAttribute(Path path, String attribute, Object value, LinkOption... options) throws IOException
      Sets a file's attribute.
      Parameters:
      path - the path to file to set an attribute to
      attribute - the attribute to set. The attribute parameter has the form: [view-name:]attribute-name. The optional view-name corresponds to AttributeView.name() and determines the set of attributes, the default value is "basic". The attribute-name is a name of an attribute.
      value - the attribute value
      options - the options determining how the symbolic links should be handled
      Throws:
      ClassCastException - if value is not of the expected type or value is a Collection containing element of a non expected type
      UnsupportedOperationException - if the attribute view is not supported.
      IllegalArgumentException - is the attribute-name is an unknown attribute or value has an inappropriate value
      IOException - in case of IO error
      SecurityException - if this FileSystem denied the operation
      Since:
      19.0

    • copy

      default void copy(Path source, Path target, CopyOption... options) throws IOException
      Copies source file to target file.
      Parameters:
      source - the path to file to copy
      target - the path to the target file
      options - the options specifying how the copy should be performed, see StandardCopyOption
      Throws:
      UnsupportedOperationException - if options contains unsupported option
      FileAlreadyExistsException - if the target path already exists and the options don't contain StandardCopyOption.REPLACE_EXISTING option
      DirectoryNotEmptyException - if the options contain StandardCopyOption.REPLACE_EXISTING but the target is a non empty directory
      IOException - in case of IO error
      SecurityException - if this FileSystem denied the operation
      Since:
      19.0

    • move

      default void move(Path source, Path target, CopyOption... options) throws IOException
      Moves (renames) source file to target file.
      Parameters:
      source - the path to file to move
      target - the path to the target file
      options - the options specifying how the move should be performed, see StandardCopyOption
      Throws:
      UnsupportedOperationException - if options contains unsupported option
      FileAlreadyExistsException - if the target path already exists and the options don't contain StandardCopyOption.REPLACE_EXISTING option
      DirectoryNotEmptyException - if the options contain StandardCopyOption.REPLACE_EXISTING but the target is a non empty directory
      AtomicMoveNotSupportedException - if the options contain StandardCopyOption.ATOMIC_MOVE but file cannot be moved atomically
      IOException - in case of IO error
      SecurityException - if this FileSystem denied the operation
      Since:
      19.0

    • createLink

      default void createLink(Path link, Path existing) throws IOException
      Creates a new link for an existing file.
      Parameters:
      link - the path to link to create
      existing - the path to existing file
      Throws:
      UnsupportedOperationException - if links are not supported by file system
      FileAlreadyExistsException - if a file on given link path already exists
      IOException - in case of IO error
      SecurityException - if this FileSystem denied the operation
      Since:
      19.0

    • createSymbolicLink

      default void createSymbolicLink(Path link, Path target, FileAttribute<?>... attrs) throws IOException
      Creates a new symbolic link.
      Parameters:
      link - the path to symbolic link to create
      target - the target path of the symbolic link
      attrs - the optional attributes to set atomically when creating the new symbolic link
      Throws:
      UnsupportedOperationException - if symbolic links are not supported by file system
      FileAlreadyExistsException - if a file on given link path already exists
      IOException - in case of IO error
      SecurityException - if this FileSystem denied the operation
      Since:
      19.0

    • readSymbolicLink

      default Path readSymbolicLink(Path link) throws IOException
      Reads the target of the symbolic link.
      Parameters:
      link - the path to symbolic link to read
      Returns:
      the Path representing the symbolic link target
      Throws:
      UnsupportedOperationException - if symbolic links are not supported by file system
      NotLinkException - if the link does not denote a symbolic link
      IOException - in case of IO error
      SecurityException - if this FileSystem denied the operation
      Since:
      19.0

    • setCurrentWorkingDirectory

      default void setCurrentWorkingDirectory(Path currentWorkingDirectory)
      Sets the current working directory. The current working directory is used to resolve non absolute paths in FileSystem operations.
      Parameters:
      currentWorkingDirectory - the new current working directory
      Throws:
      UnsupportedOperationException - if setting of the current working directory is not supported
      IllegalArgumentException - if the currentWorkingDirectory is not a valid current working directory
      SecurityException - if currentWorkingDirectory is not readable
      Since:
      19.0

    • getSeparator

      default String getSeparator()
      Returns the name separator used to separate names in a path string. The separator is used when creating path strings by invoking the toString() method.
      Returns:
      the name separator
      Since:
      19.0

    • getPathSeparator

      default String getPathSeparator()
      Returns the path separator used to separate filenames in a path list. On UNIX the path separator is ':'. On Windows it's ';'.
      Returns:
      the path separator
      Since:
      19.1.0

    • getMimeType

      default String getMimeType(Path path)
      Returns a MIME type for given path. An optional operation for filesystem implementations which can provide MIME types in an efficient way.
      Parameters:
      path - the file to find a MIME type for
      Returns:
      the MIME type or null if the MIME type is not recognized or the filesystem does not support MIME type detection
      Since:
      19.0

    • getEncoding

      default Charset getEncoding(Path path)
      Returns an file encoding for given path. An optional operation for filesystem implementations which can provide file encodings in an efficient way.
      Parameters:
      path - the file to find an file encoding for
      Returns:
      the file encoding or null if the file encoding is not detected or the filesystem does not support file encoding detection
      Since:
      19.0

    • getTempDirectory

      default Path getTempDirectory()
      Returns the default temporary directory.
      Since:
      19.3.0

    • isSameFile

      default boolean isSameFile(Path path1, Path path2, LinkOption... options) throws IOException
      Tests if the given paths refer to the same physical file. The default implementation firstly converts the paths into absolute paths. If the absolute paths are equal it returns true without checking if the file exists. Otherwise, this method converts the paths into canonical representations and tests the canonical paths for equality. The FileSystem may re-implement the method with a more efficient test. When re-implemented the method must have the same security privileges as the toAbsolutePath and toRealPath.
      Parameters:
      path1 - the path to the file
      path2 - the other path
      options - the options determining how the symbolic links should be handled
      Returns:
      true if the given paths refer to the same physical file
      Throws:
      IOException - in case of IO error
      SecurityException - if this FileSystem denied the operation
      Since:
      20.2.0

    • newDefaultFileSystem

      static FileSystem newDefaultFileSystem()
      Creates a FileSystem implementation based on the host Java NIO. The returned instance can be used as a delegate by a decorating FileSystem.

      For an untrusted code execution, access to the host filesystem should be prevented either by using IOAccess.NONE or an newFileSystem(java.nio.file.FileSystem) in-memory filesystem}. For more details on executing untrusted code, see the Polyglot Sandboxing Security Guide.

      The following example shows a FileSystem logging filesystem operations. 

       class TracingFileSystem implements FileSystem {

     private static final Logger LOGGER = Logger.getLogger(TracingFileSystem.class.getName());

     private final FileSystem delegate;

     TracingFileSystem() {
         this.delegate = FileSystem.newDefaultFileSystem();
     }

     @Override
     public Path parsePath(String path) {
         return delegate.parsePath(path);
     }

     @Override
     public Path parsePath(URI uri) {
         return delegate.parsePath(uri);
     }

     @Override
     public SeekableByteChannel newByteChannel(Path path,
                                               Set<? extends OpenOption> options,
                                               FileAttribute<?>... attrs) throws IOException {
         boolean success = false;
         try {
             SeekableByteChannel result =  delegate.newByteChannel(path, options, attrs);
             success = true;
             return result;
         } finally {
             trace("newByteChannel", path, success);
         }
     }

     ...

     private void trace(String operation, Path path, boolean success) {
         LOGGER.log(Level.FINE, "The {0} request for the path {1} {2}.",new Object[] {
                         operation, path, success ? "was successful" : "failed"
                 });
     }
 }
      Since:
      20.2.0
      See Also:

    • allowLanguageHomeAccess

      @Deprecated static FileSystem allowLanguageHomeAccess(FileSystem fileSystem)
      Deprecated.
      Use {allowInternalResourceAccess(FileSystem)}.
      Decorates the given fileSystem by an implementation that forwards access to files in the language home to the default file system. The method is intended to be used by custom filesystem implementations with non default storage to allow guest languages to access files in the languages homes. As the returned filesystem uses a default file system to access files in the language home, the fileSystem has to use the same Path type, separator and path separator as the default filesystem.
      Throws:
      IllegalArgumentException - when the fileSystem does not use the same Path type or has a different separator or path separator as the default file system.
      Since:
      22.2

    • allowInternalResourceAccess

      static FileSystem allowInternalResourceAccess(FileSystem fileSystem)
      Decorates the given fileSystem by an implementation that forwards access to the internal resources to the default file system. The method is intended to be used by custom filesystem implementations with non default storage to allow guest languages to access internal resources. As the returned filesystem uses a default file system to access internal resources, the fileSystem has to use the same Path type, separator and path separator as the default filesystem.
      Throws:
      IllegalArgumentException - when the fileSystem does not use the same Path type or has a different separator or path separator as the default file system.
      Since:
      24.0
      See Also:

    • newReadOnlyFileSystem

      static FileSystem newReadOnlyFileSystem(FileSystem fileSystem)
      Decorates the given fileSystem by an implementation that makes the passed fileSystem read-only by forbidding all write operations. This method can be used to make an existing file system, such as the default filesystem, read-only.
      Since:
      22.2

    • newFileSystem

      static FileSystem newFileSystem(FileSystem fileSystem)
      Creates a FileSystem implementation based on the given Java NIO filesystem. The returned FileSystem delegates all operations to fileSystem's provider.

      The following example shows how to configure Context so that languages read files from a prepared zip file. 

       Path zipFile = Paths.get("filesystem.zip");
 try (java.nio.file.FileSystem nioFs = FileSystems.newFileSystem(zipFile)) {
     IOAccess ioAccess = IOAccess.newBuilder().fileSystem(FileSystem.newFileSystem(nioFs)).build();
     try (Context ctx = Context.newBuilder().allowIO(ioAccess).build()) {
         Value result = ctx.eval("js", "load('scripts/app.sh'); execute()");
     }
 }
      Since:
      23.0
      See Also:

    • newDenyIOFileSystem

      static FileSystem newDenyIOFileSystem()
      Creates a FileSystem that denies all file operations except for path parsing. Any attempt to perform file operations such as reading, writing, or deletion will result in a SecurityException being thrown.

      Typically, this file system does not need to be explicitly installed to restrict access to host file systems. Instead, use Context.newBuilder().allowIO(IOAccess.NONE). This method is intended primarily for use as a fallback file system in a composite file system.

      Since:
      24.2

    • newCompositeFileSystem

      static FileSystem newCompositeFileSystem(FileSystem fallbackFileSystem, FileSystem.Selector... delegates)
      Creates a composite FileSystem that delegates operations to the provided delegates. The FileSystem of the first delegate whose FileSystem.Selector.test(Path) method accepts the path is used for the file system operation. If no delegate accepts the path, the fallbackFileSystem is used.

      The fallbackFileSystem is responsible for parsing Path objects. All provided file systems must use the same Path type, separator, and path separator. If any file system does not meet this requirement, an IllegalArgumentException is thrown.

      The composite file system maintains its own notion of the current working directory and ensures that the setCurrentWorkingDirectory(Path) method is not invoked on any of the delegates. When a request to set the current working directory is received, the composite file system verifies that the specified path corresponds to an existing directory by consulting either the appropriate delegate or the fallbackFileSystem. If an explicit current working directory has been set, the composite file system normalizes and resolves all relative paths to absolute paths prior to delegating operations. Conversely, if no explicit current working directory is set, the composite file system directly forwards the incoming path, whether relative or absolute, to the appropriate delegate. Furthermore, when an explicit current working directory is set, the composite file system does not delegate toAbsolutePath operations, as delegates do not maintain an independent notion of the current working directory. If the current working directory is unset, toAbsolutePath operations are delegated to the fallbackFileSystem.

      Operations that are independent of path context, including getTempDirectory, getSeparator, and getPathSeparator, are handled exclusively by the fallbackFileSystem.

      Throws:
      IllegalArgumentException - if the file systems do not use the same Path type, separator, or path separator
      Since:
      24.2