FileSystem (GraalVM SDK Java API Reference)

```
public interface FileSystem
```
Service-provider for Truffle files.

Since:

19.0

Method Summary

All Methods Static Methods Instance Methods Abstract Methods Default Methods
Modifier and Type	Method and Description
`static FileSystem`	`allowLanguageHomeAccess(FileSystem fileSystem)` Decorates the given `fileSystem` by an implementation that forwards access to files in the language home to the default file system.
`void`	`checkAccess(Path path, Set<? extends AccessMode> modes, LinkOption... linkOptions)` Checks existence and accessibility of a file.
`default void`	`copy(Path source, Path target, CopyOption... options)` Copies source file to target file.
`void`	`createDirectory(Path dir, FileAttribute<?>... attrs)` Creates a directory.
`default void`	`createLink(Path link, Path existing)` Creates a new link for an existing file.
`default void`	`createSymbolicLink(Path link, Path target, FileAttribute<?>... attrs)` Creates a new symbolic link.
`void`	`delete(Path path)` Deletes a file.
`default Charset`	`getEncoding(Path path)` Returns an file encoding for given path.
`default String`	`getMimeType(Path path)` Returns a MIME type for given path.
`default String`	`getPathSeparator()` Returns the path separator used to separate filenames in a path list.
`default String`	`getSeparator()` Returns the name separator used to separate names in a path string.
`default Path`	`getTempDirectory()` Returns the default temporary directory.
`default boolean`	`isSameFile(Path path1, Path path2, LinkOption... options)` Tests if the given paths refer to the same physical file.
`default void`	`move(Path source, Path target, CopyOption... options)` Moves (renames) source file to target file.
`SeekableByteChannel`	`newByteChannel(Path path, Set<? extends OpenOption> options, FileAttribute<?>... attrs)` Opens or creates a file returning a `SeekableByteChannel` to access the file content.
`static FileSystem`	`newDefaultFileSystem()` Creates a `FileSystem` implementation based on the host Java NIO.
`DirectoryStream<Path>`	`newDirectoryStream(Path dir, DirectoryStream.Filter<? super Path> filter)` Returns directory entries.
`static FileSystem`	`newFileSystem(FileSystem fileSystem)` Creates a `FileSystem` implementation based on the given Java NIO filesystem.
`static FileSystem`	`newReadOnlyFileSystem(FileSystem fileSystem)` Decorates the given `fileSystem` by an implementation that makes the passed `fileSystem` read-only by forbidding all write operations.
`Path`	`parsePath(String path)` Parses a path from a `String`.
`Path`	`parsePath(URI uri)` Parses a path from an `URI`.
`Map<String,Object>`	`readAttributes(Path path, String attributes, LinkOption... options)` Reads a file's attributes as a bulk operation.
`default Path`	`readSymbolicLink(Path link)` Reads the target of the symbolic link.
`default void`	`setAttribute(Path path, String attribute, Object value, LinkOption... options)` Sets a file's attribute.
`default void`	`setCurrentWorkingDirectory(Path currentWorkingDirectory)` Sets the current working directory.
`Path`	`toAbsolutePath(Path path)` Resolves given path to an absolute path.
`Path`	`toRealPath(Path path, LinkOption... linkOptions)` Returns the real (canonical) path of an existing file.

- Method Detail
  - 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 FileSystem.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:
    
    IOAccess.Builder.fileSystem(FileSystem), Context.Builder.allowIO(IOAccess)
  - allowLanguageHomeAccess
```
static FileSystem allowLanguageHomeAccess(FileSystem 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
  - 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:
    
    IOAccess

Interface FileSystem

Method Summary

Method Detail

parsePath

parsePath

checkAccess

createDirectory

delete

newByteChannel

newDirectoryStream

toAbsolutePath

toRealPath

readAttributes

setAttribute

copy

move

createLink

createSymbolicLink

readSymbolicLink

setCurrentWorkingDirectory

getSeparator

getPathSeparator

getMimeType

getEncoding

getTempDirectory

isSameFile

newDefaultFileSystem

allowLanguageHomeAccess

newReadOnlyFileSystem

newFileSystem