Package com.oracle.truffle.api

Class TruffleFile

java.lang.Object

com.oracle.truffle.api.TruffleFile

public final class TruffleFile
extends Object

An abstract representation of a file used by Truffle languages.

Since:

19.0

Nested Class Summary

Nested Classes

Modifier and Type	Class	Description
static final class	TruffleFile.AttributeDescriptor<T>	Represents a file's attribute.
static final class	TruffleFile.Attributes	A view over file's attributes values obtained by getAttributes.
static interface	TruffleFile.FileTypeDetector	A detector for finding file's MIME type and encoding.

Field Summary

Fields

Modifier and Type	Field	Description
static final TruffleFile.AttributeDescriptor<FileTime>	CREATION_TIME	The file's creation time.
static final TruffleFile.AttributeDescriptor<Boolean>	IS_DIRECTORY	Represents the file a directory.
static final TruffleFile.AttributeDescriptor<Boolean>	IS_OTHER	Represents the file a special file (device, named pipe).
static final TruffleFile.AttributeDescriptor<Boolean>	IS_REGULAR_FILE	Represents the file a regular file.
static final TruffleFile.AttributeDescriptor<Boolean>	IS_SYMBOLIC_LINK	Represents the file a symbolic link.
static final TruffleFile.AttributeDescriptor<FileTime>	LAST_ACCESS_TIME	The file's last access time.
static final TruffleFile.AttributeDescriptor<FileTime>	LAST_MODIFIED_TIME	The file's last modified time.
static final TruffleFile.AttributeDescriptor<Long>	SIZE	The file's size in bytes.
static final TruffleFile.AttributeDescriptor<FileTime>	UNIX_CTIME	The file's last status change time.
static final TruffleFile.AttributeDescriptor<Long>	UNIX_DEV	The id of a device containing the file.
static final TruffleFile.AttributeDescriptor<Integer>	UNIX_GID	The group id of file owner.
static final TruffleFile.AttributeDescriptor<GroupPrincipal>	UNIX_GROUP	The group owner of the file.
static final TruffleFile.AttributeDescriptor<Long>	UNIX_INODE	The file's inode number.
static final TruffleFile.AttributeDescriptor<Integer>	UNIX_MODE	The file's mode containing the protection and file type bits.
static final TruffleFile.AttributeDescriptor<Integer>	UNIX_NLINK	The number of hard links.
static final TruffleFile.AttributeDescriptor<UserPrincipal>	UNIX_OWNER	The owner of the file.
static final TruffleFile.AttributeDescriptor<Set<PosixFilePermission>>	UNIX_PERMISSIONS	The file's Posix permissions.
static final TruffleFile.AttributeDescriptor<Long>	UNIX_RDEV	The id of a device represented by the file.
static final TruffleFile.AttributeDescriptor<Integer>	UNIX_UID	The user id of file owner.

Method Summary

Modifier and Type	Method	Description
void	copy(TruffleFile target, CopyOption... options)	Copies the file.
void	createDirectories(FileAttribute<?>... attributes)	Creates a directory and all nonexistent parent directories.
void	createDirectory(FileAttribute<?>... attributes)	Creates a new directory.
void	createFile(FileAttribute<?>... attributes)	Creates a new empty file.
void	createLink(TruffleFile target)	Creates a new link to an existing target (optional operation).
void	createSymbolicLink(TruffleFile target, FileAttribute<?>... attrs)	Creates a symbolic link to a target (optional operation).
void	delete()	Deletes the file.
String	detectMimeType()	Detects the file MIME type.
boolean	endsWith(TruffleFile other)	Tests if this TruffleFile path ends with the given TruffleFile path.
boolean	endsWith(String other)	Tests if this TruffleFile path ends with the given path.
boolean	equals(Object other)
boolean	exists(LinkOption... options)	Tests existence of a file.
TruffleFile	getAbsoluteFile()	Resolves this TruffleFile to absolute TruffleFile.
<T> T	getAttribute(TruffleFile.AttributeDescriptor<T> attribute, LinkOption... linkOptions)	Reads a single file's attribute.
TruffleFile.Attributes	getAttributes(Collection<? extends TruffleFile.AttributeDescriptor<?>> attributes, LinkOption... linkOptions)	Reads file's attributes as a bulk operation.
TruffleFile	getCanonicalFile(LinkOption... options)	Returns a TruffleFile representing the real (canonical) path of an existing file.
FileTime	getCreationTime(LinkOption... options)	Returns the creation time.
GroupPrincipal	getGroup(LinkOption... options)	Returns the group owner of the file.
FileTime	getLastAccessTime(LinkOption... options)	Returns the last access time.
FileTime	getLastModifiedTime(LinkOption... options)	Returns the last modified time.
String	getMimeType()	Deprecated. use detectMimeType()
String	getName()	Returns the name of this TruffleFile.
UserPrincipal	getOwner(LinkOption... options)	Returns the owner of the file.
TruffleFile	getParent()	Returns a parent TruffleFile or null when the file does not have a parent.
String	getPath()	Returns the string representation of this TruffleFile.
Set<PosixFilePermission>	getPosixPermissions(LinkOption... linkOptions)	Returns the file's Posix permissions.
int	hashCode()
boolean	isAbsolute()	Tests if this TruffleFile's path is absolute.
boolean	isDirectory(LinkOption... options)	Tests if a file is a directory.
boolean	isExecutable()	Tests if a file is executable.
boolean	isReadable()	Tests if a file is readable.
boolean	isRegularFile(LinkOption... options)	Tests if a file is a regular file.
boolean	isSameFile(TruffleFile other, LinkOption... options)	Tests if this and the given TruffleFile refer to the same physical file.
boolean	isSymbolicLink()	Tests if a file is a symbolic link.
boolean	isWritable()	Tests if a file is writable.
Collection<TruffleFile>	list()	Returns a collection of TruffleFiles in the directory denoted by this TruffleFile.
void	move(TruffleFile target, CopyOption... options)	Moves or renames the file.
BufferedReader	newBufferedReader()	Opens a file for reading returning a BufferedReader to access the file content.
BufferedReader	newBufferedReader(Charset charset)	Opens a file for reading returning a BufferedReader to access the file content.
BufferedWriter	newBufferedWriter(Charset charset, OpenOption... options)	Opens a file for writing returning an BufferedWriter.
BufferedWriter	newBufferedWriter(OpenOption... options)	Opens a file for writing returning an BufferedWriter.
SeekableByteChannel	newByteChannel(Set<? extends OpenOption> options, FileAttribute<?>... attributes)	Opens or creates a file returning a SeekableByteChannel to access the file content.
DirectoryStream<TruffleFile>	newDirectoryStream()	Opens a directory, returning a DirectoryStream to iterate over all entries in the directory.
InputStream	newInputStream(OpenOption... options)	Opens a file for reading returning an InputStream to access the file content.
OutputStream	newOutputStream(OpenOption... options)	Opens a file for writing returning an OutputStream.
TruffleFile	normalize()	Returns a TruffleFile with removed redundant name elements in it's path.
byte[]	readAllBytes()	Reads a file content as bytes.
TruffleFile	readSymbolicLink()	Reads the target of a symbolic link.
TruffleFile	relativize(TruffleFile other)	Creates a TruffleFile with a relative path between this TruffleFile and a given TruffleFile.
TruffleFile	resolve(String name)	Resolves given string path representation against this TruffleFile.
TruffleFile	resolveSibling(String name)	Resolves given string path representation against the parent of this TruffleFile.
<T> void	setAttribute(TruffleFile.AttributeDescriptor<T> attribute, T value, LinkOption... linkOptions)	Sets a single file's attribute.
void	setCreationTime(FileTime time, LinkOption... options)	Sets the file's creation time.
void	setLastAccessTime(FileTime time, LinkOption... options)	Sets the file's last access time.
void	setLastModifiedTime(FileTime time, LinkOption... options)	Sets the file's last modified time.
void	setPosixPermissions(Set<? extends PosixFilePermission> permissions, LinkOption... linkOptions)	Sets the file's Posix permissions.
long	size(LinkOption... options)	Returns the size of a file.
boolean	startsWith(TruffleFile other)	Tests if this TruffleFile path starts with the given TruffleFile path.
boolean	startsWith(String other)	Tests if this TruffleFile path starts with the given path.
URI	toRelativeUri()	Returns a relative URI representation of non absolute TruffleFile.
String	toString()
URI	toUri()	Returns the absolute URI representation of this TruffleFile.
void	visit(FileVisitor<TruffleFile> visitor, int maxDepth, FileVisitOption... options)	Visits this TruffleFile file tree.

Methods inherited from class java.lang.Object

clone, finalize, getClass, notify, notifyAll, wait, wait, wait

Field Details

LAST_MODIFIED_TIME

public static final TruffleFile.AttributeDescriptor<FileTime> LAST_MODIFIED_TIME

The file's last modified time. Supported by all filesystems.

Since:

19.0

LAST_ACCESS_TIME

public static final TruffleFile.AttributeDescriptor<FileTime> LAST_ACCESS_TIME

The file's last access time. Supported by all filesystems.

Since:

19.0

CREATION_TIME

public static final TruffleFile.AttributeDescriptor<FileTime> CREATION_TIME

The file's creation time. Supported by all filesystems.

Since:

19.0

IS_REGULAR_FILE

public static final TruffleFile.AttributeDescriptor<Boolean> IS_REGULAR_FILE

Represents the file a regular file. Supported by all filesystems.

Since:

19.0

IS_DIRECTORY

public static final TruffleFile.AttributeDescriptor<Boolean> IS_DIRECTORY

Represents the file a directory. Supported by all filesystems.

Since:

19.0

IS_SYMBOLIC_LINK

public static final TruffleFile.AttributeDescriptor<Boolean> IS_SYMBOLIC_LINK

Represents the file a symbolic link. Supported by all filesystems.

Since:

19.0

IS_OTHER

public static final TruffleFile.AttributeDescriptor<Boolean> IS_OTHER

Represents the file a special file (device, named pipe). Supported by all filesystems.

Since:

19.0

SIZE

public static final TruffleFile.AttributeDescriptor<Long> SIZE

The file's size in bytes. Supported by all filesystems.

Since:

19.0

UNIX_OWNER

public static final TruffleFile.AttributeDescriptor<UserPrincipal> UNIX_OWNER

The owner of the file. Supported only by UNIX native filesystem.

Since:

19.0

UNIX_GROUP

public static final TruffleFile.AttributeDescriptor<GroupPrincipal> UNIX_GROUP

The group owner of the file. Supported only by UNIX native filesystem.

Since:

19.0

UNIX_PERMISSIONS

public static final TruffleFile.AttributeDescriptor<Set<PosixFilePermission>> UNIX_PERMISSIONS

The file's Posix permissions. Supported only by UNIX native filesystem.

Since:

19.0

UNIX_MODE

public static final TruffleFile.AttributeDescriptor<Integer> UNIX_MODE

The file's mode containing the protection and file type bits. Supported only by UNIX native filesystem.

Since:

19.0

UNIX_INODE

public static final TruffleFile.AttributeDescriptor<Long> UNIX_INODE

The file's inode number. Supported only by UNIX native filesystem.

Since:

19.0

UNIX_DEV

public static final TruffleFile.AttributeDescriptor<Long> UNIX_DEV

The id of a device containing the file. Supported only by UNIX native filesystem.

Since:

19.0

UNIX_RDEV

public static final TruffleFile.AttributeDescriptor<Long> UNIX_RDEV

The id of a device represented by the file. Supported only by UNIX native filesystem.

Since:

19.0

UNIX_NLINK

public static final TruffleFile.AttributeDescriptor<Integer> UNIX_NLINK

The number of hard links. Supported only by UNIX native filesystem.

Since:

19.0

UNIX_UID

public static final TruffleFile.AttributeDescriptor<Integer> UNIX_UID

The user id of file owner. Supported only by UNIX native filesystem.

Since:

19.0

UNIX_GID

public static final TruffleFile.AttributeDescriptor<Integer> UNIX_GID

The group id of file owner. Supported only by UNIX native filesystem.

Since:

19.0

UNIX_CTIME

public static final TruffleFile.AttributeDescriptor<FileTime> UNIX_CTIME

The file's last status change time. Supported only by UNIX native filesystem.

Since:

19.0

Method Details

exists

public boolean exists(LinkOption... options)

Tests existence of a file.

Parameters:

options - the options determining how the symbolic links should be handled

Returns:

true if the file exists

Throws:

SecurityException - if the FileSystem denied the operation

Since:

19.0

isReadable

public boolean isReadable()

Tests if a file is readable. Checks if the file exists and this Java virtual machine has enough privileges to read the file.

Returns:

true if the file exists and is readable

Throws:

SecurityException - if the FileSystem denied the operation

Since:

19.0

isWritable

public boolean isWritable()

Tests if a file is writable. Checks if the file exists and this Java virtual machine has enough privileges to write to the file.

Returns:

true if the file exists and is writable

Throws:

SecurityException - if the FileSystem denied the operation

Since:

19.0

isExecutable

public boolean isExecutable()

Tests if a file is executable. Checks if the file exists and this Java virtual machine has enough privileges to execute the file.

Returns:

true if the file exists and is executable

Throws:

SecurityException - if the FileSystem denied the operation

Since:

19.0

isDirectory

public boolean isDirectory(LinkOption... options)

Tests if a file is a directory. Checks if the file exists and is a directory.

Parameters:

options - the options determining how the symbolic links should be handled, by default the symbolic links are followed.

Returns:

true if the file exists and is a directory

Throws:

SecurityException - if the FileSystem denied the operation

Since:

19.0

isRegularFile

public boolean isRegularFile(LinkOption... options)

Tests if a file is a regular file. Checks if the file exists and is a regular file.

Parameters:

options - the options determining how the symbolic links should be handled, by default the symbolic links are followed.

Returns:

true if the file exists and is a regular file

Throws:

SecurityException - if the FileSystem denied the operation

Since:

19.0

isSymbolicLink

public boolean isSymbolicLink()

Tests if a file is a symbolic link. Checks if the file exists and is a symbolic link.

Returns:

true if the file exists and is a symbolic link

Throws:

SecurityException - if the FileSystem denied the operation

Since:

19.0

isAbsolute

public boolean isAbsolute()

Tests if this TruffleFile's path is absolute.

Returns:

true if the file path is absolute

Since:

19.0

getName

public String getName()

Returns the name of this TruffleFile.

Returns:

the name of file or directory denoted by this TruffleFile, or null if the file is a root directory

Since:

19.0

getPath

public String getPath()

Returns the string representation of this TruffleFile.

Returns:

the path of this TruffleFile

Since:

19.0

toUri

public URI toUri()

Returns the absolute URI representation of this TruffleFile.

Returns:

the absolute URI representing the TruffleFile

Throws:

SecurityException - if the FileSystem denied a resolution of an absolute path

Since:

19.0

toRelativeUri

public URI toRelativeUri()

Returns a relative URI representation of non absolute TruffleFile. If this TruffleFile is relative it returns a relative URI. For an absolute TruffleFile it returns an absolute URI.

Returns:

the URI representing the TruffleFile

Since:

19.0

getAbsoluteFile

public TruffleFile getAbsoluteFile()

Resolves this TruffleFile to absolute TruffleFile. If this TruffleFile is already absolute this method returns this TruffleFile without any resolution.

Returns:

the absolute TruffleFile

Throws:

SecurityException - if the FileSystem denied a resolution of an absolute path

Since:

19.0

getCanonicalFile

public TruffleFile getCanonicalFile(LinkOption... options)
                             throws IOException

Returns a TruffleFile representing the real (canonical) path of an existing file.

Parameters:

options - the options determining how the symbolic links should be handled

Returns:

a TruffleFile representing the absolute canonical path

Throws:

IOException - in case of IO error

SecurityException - if the FileSystem denied the operation

Since:

19.0

getParent

public TruffleFile getParent()

Returns a parent TruffleFile or null when the file does not have a parent.

Returns:

the parent TruffleFile

Since:

19.0

resolve

public TruffleFile resolve(String name)

Resolves given string path representation against this TruffleFile.

Parameters:

name - the path to resolve

Returns:

the resolved TruffleFile

Throws:

InvalidPathException - if the path string contains non valid characters

Since:

19.0

resolveSibling

public TruffleFile resolveSibling(String name)

Resolves given string path representation against the parent of this TruffleFile.

Parameters:

name - the path to resolve

Returns:

the resolved TruffleFile

Throws:

InvalidPathException - if the path string contains non valid characters

Since:

19.0

size

public long size(LinkOption... options)
          throws IOException

Returns the size of a file.

Parameters:

options - the options determining how the symbolic links should be handled

Returns:

the file size in bytes

Throws:

IOException - in case of IO error

SecurityException - if the FileSystem denied the operation

Since:

19.0

getLastModifiedTime

public FileTime getLastModifiedTime(LinkOption... options)
                             throws IOException

Returns the last modified time.

Parameters:

options - the options determining how the symbolic links should be handled

Returns:

the FileTime representing the time this TruffleFile was last modified

Throws:

IOException - in case of IO error

SecurityException - if the FileSystem denied the operation

Since:

19.0

setLastModifiedTime

public void setLastModifiedTime(FileTime time,
 LinkOption... options)
                         throws IOException

Sets the file's last modified time.

Parameters:

time - the new value of the last modified time

options - the options determining how the symbolic links should be handled

Throws:

IOException - in case of IO error

SecurityException - if the FileSystem denied the operation

Since:

19.0

getLastAccessTime

public FileTime getLastAccessTime(LinkOption... options)
                           throws IOException

Returns the last access time.

Parameters:

options - the options determining how the symbolic links should be handled

Returns:

the FileTime representing the time this TruffleFile was last accessed

Throws:

IOException - in case of IO error

SecurityException - if the FileSystem denied the operation

Since:

19.0

setLastAccessTime

public void setLastAccessTime(FileTime time,
 LinkOption... options)
                       throws IOException

Sets the file's last access time.

Parameters:

time - the new value of the last access time

options - the options determining how the symbolic links should be handled

Throws:

IOException - in case of IO error

SecurityException - if the FileSystem denied the operation

Since:

19.0

getCreationTime

public FileTime getCreationTime(LinkOption... options)
                         throws IOException

Returns the creation time.

Parameters:

options - the options determining how the symbolic links should be handled

Returns:

the FileTime representing the time this TruffleFile was created

Throws:

IOException - in case of IO error

SecurityException - if the FileSystem denied the operation

Since:

19.0

setCreationTime

public void setCreationTime(FileTime time,
 LinkOption... options)
                     throws IOException

Sets the file's creation time.

Parameters:

time - the new value of the creation time

options - the options determining how the symbolic links should be handled

Throws:

IOException - in case of IO error

SecurityException - if the FileSystem denied the operation

Since:

19.0

list

public Collection<TruffleFile> list()
                             throws IOException

Returns a collection of TruffleFiles in the directory denoted by this TruffleFile.

Returns:

a collection of TruffleFiles located in the directory denoted by this TruffleFile

Throws:

IOException - in case of IO error

SecurityException - if the FileSystem denied the operation

Since:

19.0

newByteChannel

public SeekableByteChannel newByteChannel(Set<? extends OpenOption> options,
 FileAttribute<?>... attributes)
                                   throws IOException

Opens or creates a file returning a SeekableByteChannel to access the file content. In most cases, the returned SeekableByteChannel should be closed using try-with-resources construct. When the channel must keep being opened for the lifetime of a context it should be registered for automatic close on context dispose.

Parameters:

options - the options specifying how the file should be opened

attributes - 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 the FileSystem denied the operation

Since:

19.0

newInputStream

public InputStream newInputStream(OpenOption... options)
                           throws IOException

Opens a file for reading returning an InputStream to access the file content. In most cases, the returned InputStream should be closed using try-with-resources construct. When the stream must keep being opened for the lifetime of a context it should be registered for automatic close on context dispose.

Parameters:

options - the options specifying how the file should be opened

Returns:

the created InputStream

Throws:

IOException - in case of IO error

IllegalArgumentException - in case of invalid options combination

SecurityException - if the FileSystem denied the operation

Since:

19.0

newBufferedReader

public BufferedReader newBufferedReader(Charset charset)
                                 throws IOException

Opens a file for reading returning a BufferedReader to access the file content. In most cases, the returned BufferedReader should be closed using try-with-resources construct. When the reader must keep being opened for the lifetime of a context it should be registered for automatic close on context dispose.

Parameters:

charset - the file encoding

Returns:

the created BufferedReader

Throws:

IOException - in case of IO error

SecurityException - if the FileSystem denied the operation

Since:

19.0

newBufferedReader

public BufferedReader newBufferedReader()
                                 throws IOException

Opens a file for reading returning a BufferedReader to access the file content. See newBufferedReader(Charset).

Returns:

the created BufferedReader

Throws:

IOException - in case of IO error

SecurityException - if the FileSystem denied the operation

Since:

19.0

readAllBytes

public byte[] readAllBytes()
                    throws IOException

Reads a file content as bytes.

Returns:

the created byte[]

Throws:

IOException - in case of IO error

OutOfMemoryError - if an array of a file size cannot be allocated

SecurityException - if the FileSystem denied the operation

Since:

19.0

newOutputStream

public OutputStream newOutputStream(OpenOption... options)
                             throws IOException

Opens a file for writing returning an OutputStream. In most cases, the returned OutputStream should be closed using try-with-resources construct. When the stream must keep being opened for the lifetime of a context it should be registered for automatic close on context dispose.

Parameters:

options - the options specifying how the file should be opened

Returns:

the created OutputStream

Throws:

IOException - in case of IO error

IllegalArgumentException - in case of invalid options combination

SecurityException - if the FileSystem denied the operation

Since:

19.0

newBufferedWriter

public BufferedWriter newBufferedWriter(Charset charset,
 OpenOption... options)
                                 throws IOException

Opens a file for writing returning an BufferedWriter. In most cases, the returned BufferedWriter should be closed using try-with-resources construct. When the writer must keep being opened for the lifetime of a context it should be registered for automatic close on context dispose.

Parameters:

charset - the file encoding

options - the options specifying how the file should be opened

Returns:

the created BufferedWriter

Throws:

IOException - in case of IO error

IllegalArgumentException - in case of invalid options combination

SecurityException - if the FileSystem denied the operation

Since:

19.0

newBufferedWriter

public BufferedWriter newBufferedWriter(OpenOption... options)
                                 throws IOException

Opens a file for writing returning an BufferedWriter. See newBufferedWriter(Charset, OpenOption...).

Parameters:

options - the options specifying how the file should be opened

Returns:

the created BufferedWriter

Throws:

IOException - in case of IO error

IllegalArgumentException - in case of invalid options combination

SecurityException - if the FileSystem denied the operation

Since:

19.0

createFile

public void createFile(FileAttribute<?>... attributes)
                throws IOException

Creates a new empty file.

Parameters:

attributes - the optional attributes to set atomically when creating the new file

Throws:

FileAlreadyExistsException - if the file already exists on given path

IOException - in case of IO error

UnsupportedOperationException - if the attributes contain an attribute which cannot be set atomically

SecurityException - if the FileSystem denied the operation

Since:

19.0

createDirectory

public void createDirectory(FileAttribute<?>... attributes)
                     throws IOException

Creates a new directory.

Parameters:

attributes - the optional attributes to set atomically when creating the new file

Throws:

FileAlreadyExistsException - if the file or directory already exists on given path

IOException - in case of IO error

UnsupportedOperationException - if the attributes contain an attribute which cannot be set atomically

SecurityException - if the FileSystem denied the operation

Since:

19.0

createDirectories

public void createDirectories(FileAttribute<?>... attributes)
                       throws IOException

Creates a directory and all nonexistent parent directories. Unlike the createDirectory(java.nio.file.attribute.FileAttribute<?>...) the FileAlreadyExistsException is not thrown if the directory already exists.

Parameters:

attributes - the optional attributes to set atomically when creating the new file

Throws:

FileAlreadyExistsException - if a file (not a directory) already exists on given path

IOException - in case of IO error

UnsupportedOperationException - if the attributes contain an attribute which cannot be set atomically

SecurityException - if the FileSystem denied the operation

Since:

19.0

delete

public void delete()
            throws IOException

Deletes the file. If the TruffleFile denotes a directory, the directory must be empty before deleting. If the TruffleFile denotes a symbolic link the symbolic link itself is deleted not its target.

Throws:

NoSuchFileException - if the file does not exist

DirectoryNotEmptyException - if the TruffleFile denotes a non empty directory

IOException - in case of IO error

SecurityException - if the FileSystem denied the operation

Since:

19.0

move

public void move(TruffleFile target,
 CopyOption... options)
          throws IOException

Moves or renames the file.

Parameters:

target - the path of a 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 the FileSystem denied the operation

Since:

19.0

getPosixPermissions

public Set<PosixFilePermission> getPosixPermissions(LinkOption... linkOptions)
                                             throws IOException

Returns the file's Posix permissions.

Parameters:

linkOptions - the options determining how the symbolic links should be handled

Returns:

the the file's Posix permissions

Throws:

IOException - in case of IO error

UnsupportedOperationException - when the Posix permissions are not supported by filesystem

SecurityException - if the FileSystem denied the operation

Since:

19.0

setPosixPermissions

public void setPosixPermissions(Set<? extends PosixFilePermission> permissions,
 LinkOption... linkOptions)
                         throws IOException

Sets the file's Posix permissions.

Parameters:

permissions - the Posix permissions to set

linkOptions - the options determining how the symbolic links should be handled

Throws:

IOException - in case of IO error

UnsupportedOperationException - when the Posix permissions are not supported by filesystem

SecurityException - if the FileSystem denied the operation

Since:

19.0

toString

public String toString()

Overrides:

toString in class Object

Since:

19.0

hashCode

public int hashCode()

Overrides:

hashCode in class Object

Since:

19.0

equals

public boolean equals(Object other)

Overrides:

equals in class Object

Since:

19.0

normalize

public TruffleFile normalize()

Returns a TruffleFile with removed redundant name elements in it's path.

Returns:

the normalized TruffleFile

Since:

19.0

relativize

public TruffleFile relativize(TruffleFile other)

Creates a TruffleFile with a relative path between this TruffleFile and a given TruffleFile.

Relativization is the inverse of resolution. Relativization constructs a TruffleFile with relative path that when resolved against this TruffleFile yields a TruffleFile locating the same file as given TruffleFile. A relative path cannot be constructed if only one of the TruffleFiles is absolute.

Parameters:

other - the TruffleFile to relativize against this TruffleFile

Returns:

the TruffleFile with relative path between this and other TruffleFiles

Throws:

IllegalArgumentException - when other cannot be relativized against this TruffleFile

Since:

19.0

startsWith

public boolean startsWith(String other)

Tests if this TruffleFile path starts with the given path. The path foo/bar starts with foo and foo/bar but does not start with f.

Parameters:

other - the path

Returns:

true if this TruffleFile path starts with given path

Throws:

IllegalArgumentException - if the path cannot be parsed.

Since:

19.0

startsWith

public boolean startsWith(TruffleFile other)

Tests if this TruffleFile path starts with the given TruffleFile path. The path foo/bar starts with foo and foo/bar but does not start with f.

Parameters:

other - the TruffleFile

Returns:

true if this TruffleFile path starts with given TruffleFile path

Since:

19.0

endsWith

public boolean endsWith(String other)

Tests if this TruffleFile path ends with the given path. The path foo/bar ends with bar and foo/bar but does not end with r.

Parameters:

other - the path

Returns:

true if this TruffleFile path ends with given path

Throws:

IllegalArgumentException - if the path cannot be parsed.

Since:

19.0

endsWith

public boolean endsWith(TruffleFile other)

Tests if this TruffleFile path ends with the given TruffleFile path. The path foo/bar ends with bar and foo/bar but does not end with r.

Parameters:

other - the TruffleFile

Returns:

true if this TruffleFile path ends with given TruffleFile path

Since:

19.0

createLink

public void createLink(TruffleFile target)
                throws IOException

Creates a new link to an existing target (optional operation).

Parameters:

target - the existing file to link

Throws:

FileAlreadyExistsException - if the file or directory already exists on given path

IOException - in case of IO error

UnsupportedOperationException - if the FileSystem implementation does not support links

SecurityException - if the FileSystem denied the operation

Since:

19.0

createSymbolicLink

public void createSymbolicLink(TruffleFile target,
 FileAttribute<?>... attrs)
                        throws IOException

Creates a symbolic link to a target (optional operation).

Parameters:

target - the target of the symbolic link

attrs - the optional attributes to set atomically when creating the symbolic link

Throws:

FileAlreadyExistsException - if the file or directory already exists on given path

IOException - in case of IO error

UnsupportedOperationException - if the FileSystem implementation does not support symbolic links or the attributes contain an attribute which cannot be set atomically

SecurityException - if the FileSystem denied the operation

Since:

19.0

readSymbolicLink

public TruffleFile readSymbolicLink()
                             throws IOException

Reads the target of a symbolic link.

Returns:

the TruffleFile representing the target of the symbolic link

Throws:

NotLinkException - if the TruffleFile is not a symbolic link

IOException - in case of IO error

UnsupportedOperationException - if the FileSystem implementation does not support symbolic links

SecurityException - if the FileSystem denied the operation

Since:

20.3

getOwner

public UserPrincipal getOwner(LinkOption... options)
                       throws IOException

Returns the owner of the file.

Parameters:

options - the options determining how the symbolic links should be handled

Returns:

the file owner

Throws:

IOException - in case of IO error

UnsupportedOperationException - if the FileSystem implementation does not support owner attribute

SecurityException - if the FileSystem denied the operation

Since:

19.0

getGroup

public GroupPrincipal getGroup(LinkOption... options)
                        throws IOException

Returns the group owner of the file.

Parameters:

options - the options determining how the symbolic links should be handled

Returns:

the file owner

Throws:

IOException - in case of IO error

UnsupportedOperationException - if the FileSystem implementation does not support group owner attribute

SecurityException - if the FileSystem denied the operation

Since:

19.0

newDirectoryStream

public DirectoryStream<TruffleFile> newDirectoryStream()
                                                throws IOException

Opens a directory, returning a DirectoryStream to iterate over all entries in the directory.

The TruffleFiles returned by the directory stream's iterator are created as if by resolving the name of the directory entry against this TruffleFile.

In most cases, the returned DirectoryStream should be closed using try-with-resources construct. When the stream must keep being opened for the lifetime of a context it should be registered for automatic close on context dispose. When not using the try-with-resources construct, then the directory stream's close method should be called after iteration is completed.

The code which iterates over all files can use simpler list() method.

Returns:

a new opened DirectoryStream object

Throws:

IOException - in case of IO error

SecurityException - if the FileSystem denied the operation

Since:

19.0

visit

public void visit(FileVisitor<TruffleFile> visitor,
 int maxDepth,
 FileVisitOption... options)
           throws IOException

Visits this TruffleFile file tree.

This method walks a file tree rooted at this TruffleFile. The file tree traversal is depth-first. The appropriate method on give FileVisitor is invoked for each met file. File tree traversal completes when all accessible files in the tree have been visited, a FileVisitor visit method returns a FileVisitResult.TERMINATE or a FileVisitor method terminates due to an uncaught exception.

For each file encountered this method attempts to read its BasicFileAttributes. If the file is not a directory then the visitFile method is invoked with the file attributes. If the file attributes cannot be read, due to an I/O exception, then the visitFileFailed method is invoked with the I/O exception.

Where the file is a directory, and the directory could not be opened, then the visitFileFailed method is invoked with the I/O exception, after which, the file tree walk continues, by default, at the next sibling of the directory.

Where the directory is opened successfully, then the entries in the directory, and their descendants are visited. When all entries have been visited, or an I/O error occurs during iteration of the directory, then the directory is closed and the visitor's postVisitDirectory method is invoked. The file tree walk then continues, by default, at the next sibling of the directory.

By default, symbolic links are not automatically followed by this method. If the options parameter contains the FOLLOW_LINKS option then symbolic links are followed.

The maxDepth parameter is the maximum number of levels of directories to visit. A value of 0 means that only the starting file is visited. The visitFile method is invoked for all files, including directories, encountered at maxDepth, unless the basic file attributes cannot be read, in which case the visitFileFailed method is invoked.

Parameters:

visitor - the FileVisitor to invoke for each file

maxDepth - the maximum number of directory levels to visit, MAX_VALUE may be used to indicate that all levels should be visited.

options - the options configuring the file tree traversal

Throws:

IllegalArgumentException - if the maxDepth parameter is negative

IOException - in case of IO error

SecurityException - if the FileSystem denied the operation

Since:

19.0

copy

public void copy(TruffleFile target,
 CopyOption... options)
          throws IOException

Copies the file. When the file is a directory the copy creates an empty directory in the target location, the directory entries are not copied. This method can be used with the visit method to copy the whole sub-tree.

Parameters:

target - the path of a 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 the FileSystem denied the operation

Since:

19.0

getMimeType

@Deprecated(since="20.2")
public String getMimeType()
                   throws IOException

Deprecated.

use detectMimeType()

Returns the file MIME type.

Returns:

the MIME type or null if the MIME type is not recognized

Throws:

IOException - in case of IO error

SecurityException - if the FileSystem denied the operation

Since:

19.0

detectMimeType

public String detectMimeType()

Detects the file MIME type.

Returns:

the MIME type or null if the MIME type is not recognized

Throws:

SecurityException - if the FileSystem denied the operation

Since:

22.2

isSameFile

public boolean isSameFile(TruffleFile other,
 LinkOption... options)
                   throws IOException

Tests if this and the given TruffleFile refer to the same physical file. If both TruffleFile objects are equal then this method returns true without any checks. If the TruffleFiles have different filesystems then this method returns false. Otherwise, this method checks if both TruffleFiles refer to the same physical file. Depending on the FileSystem implementation it may require to read the files attributes. This implies:

• Public and Internal files with disabled IO are never the same.
• Public and Internal files with allowed IO are potentially the same.
• Files created by different languages are potentially the same.
• Files created during the Context pre-initialization and files created during Context execution are potentially the same.

Parameters:

other - the other TruffleFile

Returns:

true if this and the given TruffleFile refer to the same physical file

Throws:

IOException - in case of IO error

SecurityException - if the FileSystem denied the operation

Since:

20.2.0

getAttribute

public <T> T getAttribute(TruffleFile.AttributeDescriptor<T> attribute,
 LinkOption... linkOptions)
                   throws IOException

Reads a single file's attribute.

Parameters:

attribute - the attribute to read

linkOptions - the options determining how the symbolic links should be handled

Returns:

the attribute value

Throws:

IOException - in case of IO error

UnsupportedOperationException - when the filesystem does not support required attribute.

SecurityException - if the FileSystem denied the operation

Since:

19.0

setAttribute

public <T> void setAttribute(TruffleFile.AttributeDescriptor<T> attribute,
 T value,
 LinkOption... linkOptions)
                      throws IOException

Sets a single file's attribute.

Parameters:

attribute - the attribute to set

value - the attribute value

linkOptions - the options determining how the symbolic links should be handled

Throws:

IOException - in case of IO error

UnsupportedOperationException - when the filesystem does not support given attribute

IllegalArgumentException - when the attribute value has an inappropriate value

SecurityException - if the FileSystem denied the operation

Since:

19.1.0

getAttributes

public TruffleFile.Attributes getAttributes(Collection<? extends TruffleFile.AttributeDescriptor<?>> attributes,
 LinkOption... linkOptions)
                                     throws IOException

Reads file's attributes as a bulk operation.

Parameters:

attributes - the attributes to read

linkOptions - the options determining how the symbolic links should be handled

Returns:

the attributes view

Throws:

IllegalArgumentException - when no attributes are given

IOException - in case of IO error

UnsupportedOperationException - when the filesystem does not support some of the required attributes.

SecurityException - if the FileSystem denied the operation

Since:

19.0