org.classpath.icedtea.java.nio.file
Interface FileRef

All Known Implementing Classes:

AbstractPath, Path

public interface FileRef

A reference to a file.

A FileRef is an object that locates a file and defines methods to access the file. The means by which the file is located depends on the implementation. In many cases, a file is located by a Path but it may be located by other means such as a file-system identifier.

This interface defines the following operations:

• The newByteChannel method may be used to open a file and obtain a byte channel for reading or writing.

• The delete method may be used to delete a file.

• The checkAccess method may be used to check the existence or accessibility of a file.

• The isSameFile method may be used to test if two file references locate the same file.

• The getFileStore method may be used to obtain the FileStore representing the storage where a file is located.

Access to associated metadata or file attributes requires an appropriate FileAttributeView. The getFileAttributeView(Class,LinkOption[]) method may be used to obtain a file attribute view that defines type-safe methods to read or update file attributes. The getFileAttributeView(String,LinkOption[]) method may be used to obtain a file attribute view where dynamic access to file attributes where required.

A FileRef is immutable and safe for use by multiple concurrent threads.

Since:

1.7

Method Summary

void	checkAccess(AccessMode... modes) Checks the existence and optionally the accessibility of the file referenced by this object.
void	delete() Deletes the file referenced by this object.
boolean	equals(java.lang.Object ob) Tests this object for equality with another object.
<V extends FileAttributeView> V	getFileAttributeView(java.lang.Class<V> type, LinkOption... options) Returns a file attribute view of a given type.
FileAttributeView	getFileAttributeView(java.lang.String name, LinkOption... options) Returns a file attribute view of the given name.
FileStore	getFileStore() Returns the FileStore representing the file store where the file referenced by this object is stored.
int	hashCode() Returns the hash-code value for this object.
boolean	isSameFile(FileRef other) Tests if the file referenced by this object is the same file referenced by another object.
SeekableByteChannel	newByteChannel(OpenOption... options) Opens the file referenced by this object, returning a seekable byte channel to access the file.

Method Detail

newByteChannel

SeekableByteChannel newByteChannel(OpenOption... options)
                                   throws java.io.IOException

Opens the file referenced by this object, returning a seekable byte channel to access the file.

The options parameter determines how the file is opened. The READ and WRITE options determine if the file should be opened for reading and/or writing. If neither option (or the APPEND option) is contained in the array then the file is opened for reading. By default reading or writing commences at the beginning of the file.

In the addition to READ and WRITE, the following options may be present:

Option	Description
APPEND	If this option is present then the file is opened for writing and each invocation of the channel's write method first advances the position to the end of the file and then writes the requested data. Whether the advancement of the position and the writing of the data are done in a single atomic operation is system-dependent and therefore unspecified. This option may not be used in conjunction with the READ or TRUNCATE_EXISTING options.
TRUNCATE_EXISTING	If this option is present then the existing file is truncated to a size of 0 bytes. This option is ignored when the file is opened only for reading.
SYNC	Requires that every update to the file's content or metadata be written synchronously to the underlying storage device. (see Synchronized I/O file integrity).
DSYNC	Requires that every update to the file's content be written synchronously to the underlying storage device. (see Synchronized I/O file integrity).

An implementation of this interface may support additional options defined by the StandardOpenOption enumeration type or other implementation specific options.

The Channels utility classes defines methods to construct input and output streams where inter-operation with the java.io package is required.

Parameters:

options - Options specifying how the file is opened

Returns:

a new seekable byte channel

Throws:

java.lang.IllegalArgumentException - If an invalid combination of options is specified

java.lang.UnsupportedOperationException - If an unsupported open option is specified

java.io.IOException - If an I/O error occurs

java.lang.SecurityException - In the case of the default provider, and a security manager is installed, the checkRead method is invoked to check read access to the path if the file is opened for reading. The checkWrite method is invoked to check write access to the path if the file is opened for writing.

getFileStore

FileStore getFileStore()
                       throws java.io.IOException

Returns the FileStore representing the file store where the file referenced by this object is stored.

Once a reference to the FileStore is obtained it is implementation specific if operations on the returned FileStore, or FileStoreAttributeView objects obtained from it, continue to depend on the existence of the file. In particular the behavior is not defined for the case that the file is deleted or moved to a different file store.

Returns:

The file store where the file is stored

Throws:

java.io.IOException - If an I/O error occurs

java.lang.SecurityException - In the case of the default provider, and a security manager is installed, the checkRead method is invoked to check read access to the file.

checkAccess

void checkAccess(AccessMode... modes)
                 throws java.io.IOException

Checks the existence and optionally the accessibility of the file referenced by this object.

This method checks the existence of a file and that this Java virtual machine has appropriate privileges that would allow it access the file according to all of access modes specified in the modes parameter as follows:

Value	Description
READ	Checks that the file exists and that the Java virtual machine has permission to read the file.
WRITE	Checks that the file exists and that the Java virtual machine has permission to write to the file,
EXECUTE	Checks that the file exists and that the Java virtual machine has permission to execute the file. The semantics may differ when checking access to a directory. For example, on UNIX systems, checking for EXECUTE access checks that the Java virtual machine has permission to search the directory in order to access file or subdirectories.

If the modes parameter is of length zero, then the existence of the file is checked.

This method follows symbolic links if the file referenced by this object is a symbolic link. Depending on the implementation, this method may require to read file permissions, access control lists, or other file attributes in order to check the effective access to the file. To determine the effective access to a file may require access to several attributes and so in some implementations this method may not be atomic with respect to other file system operations. Furthermore, as the result of this method is immediately outdated, there is no guarantee that a subsequence access will succeed (or even that it will access the same file). Care should be taken when using this method in security sensitive applications.

Parameters:

modes - The access modes to check; may have zero elements

Throws:

java.lang.UnsupportedOperationException - An implementation is required to support checking for READ, WRITE, and EXECUTE access. This exception is specified to allow for the Access enum to be extended in future releases.

NoSuchFileException - If a file does not exist (optional specific exception)

AccessDeniedException - The requested access would be denied or the access cannot be determined because the Java virtual machine has insufficient privileges or other reasons. (optional specific exception)

java.io.IOException - If an I/O error occurs

java.lang.SecurityException - In the case of the default provider, and a security manager is installed, the checkRead is invoked when checking read access to the file or only the existence of the file, the checkWrite is invoked when checking write access to the file, and checkExec is invoked when checking execute access.

getFileAttributeView

<V extends FileAttributeView> V getFileAttributeView(java.lang.Class<V> type,
                                                     LinkOption... options)

Returns a file attribute view of a given type.

A file attribute view provides a read-only or updatable view of the file attributes that is supports. This method is intended to be used where the file attribute view defines type-safe methods to read or update the file attributes. The type parameter is the type of the attribute view required and the method returns an instance of that type if supported. The BasicFileAttributeView type supports access to the basic attributes of a file. Invoking this method to select a file attribute view of that type will always return an instance of that class.

The options array may be used to indicate how symbolic links are handled by the resulting file attribute view for the case that the file is a symbolic link. By default, symbolic links are followed. If the option NOFOLLOW_LINKS is present then symbolic links are not followed. This option is ignored by implementations that do not support symbolic links.

Parameters:

type - The Class object corresponding to the file attribute view

options - Options indicating how symbolic links are handled

Returns:

A file attribute view of the specified type, or null if the attribute view type is not available

Throws:

java.lang.UnsupportedOperationException - If options contains an unsupported option. This exception is specified to allow the LinkOption enum be extended in future releases.

See Also:

Attributes#readBasicFileAttributes

getFileAttributeView

FileAttributeView getFileAttributeView(java.lang.String name,
                                       LinkOption... options)

Returns a file attribute view of the given name.

A file attribute view provides a read-only or updatable view of the file attributes that is supports. This method is intended to be used where dynamic access to the file attributes is required. The name parameter specifies the name of the file attribute view and this method returns an instance of that view if supported. The BasicFileAttributeView type supports access to the basic attributes of a file and is name "basic". Invoking this method to select a file attribute view named "basic" will always return an instance of that class.

The options array may be used to indicate how symbolic links are handled by the resulting file attribute view for the case that the file is a symbolic link. By default, symbolic links are followed. If the option NOFOLLOW_LINKS is present then symbolic links are not followed. This option is ignored by implementations that do not support symbolic links.

Parameters:

name - The name of the file attribute view

options - Options indicating how symbolic links are handled

Returns:

A file attribute view of the given name, or null if the attribute view is not available

Throws:

java.lang.UnsupportedOperationException - If options contains an unsupported option. This exception is specified to allow the LinkOption enum be extended in future releases.

isSameFile

boolean isSameFile(FileRef other)
                   throws java.io.IOException

Tests if the file referenced by this object is the same file referenced by another object.

If this FileRef and the given FileRef are equal then this method returns true without checking if the file exists. If the FileRef and the given FileRef are associated with different providers, or the given FileRef is null then this method returns false. Otherwise, this method checks if both FileRefs locate the same file, and depending on the implementation, may require to open or access both files.

If the file system and files remain static, then this method implements an equivalence relation for non-null FileRefs.

• It is reflexive: for a non-null FileRef f, f.isSameFile(f) should return true.
• It is symmetric: for two non-null FileRefs f and g, f.isSameFile(g) will equal g.isSameFile(f).
• It is transitive: for three FileRefs f, g, and h, if f.isSameFile(g) returns true and g.isSameFile(h) returns true, then f.isSameFile(h) will return return true.

Parameters:

other - The other file reference

Returns:

true if, and only if, this object and the given object locate the same file

Throws:

java.io.IOException - If an I/O error occurs

java.lang.SecurityException - In the case of the default provider, and a security manager is installed, the checkRead method is invoked to check read access to both files.

See Also:

java.nio.file.attribute.BasicFileAttributes#fileKey

delete

void delete()
            throws java.io.IOException

Deletes the file referenced by this object.

An implementation may require to examine the file to determine if the file is a directory. Consequently this method may not be atomic with respect to other file system operations. If the file is a symbolic-link then the link is deleted and not the final target of the link.

If the file is a directory then the directory must be empty. In some implementations a directory has entries for special files or links that are created when the directory is created. In such implementations a directory is considered empty when only the special entries exist.

On some operating systems it may not be possible to remove a file when it is open and in use by this Java virtual machine or other programs.

Throws:

NoSuchFileException - If the file does not exist (optional specific exception)

DirectoryNotEmptyException - If the file is a directory and could not otherwise be deleted because the directory is not empty (optional specific exception)

java.io.IOException - If an I/O error occurs

java.lang.SecurityException - In the case of the default provider, and a security manager is installed, the SecurityManager.checkDelete(String) method is invoked to check delete access to the file

equals

boolean equals(java.lang.Object ob)

Tests this object for equality with another object.

If the given object is not a FileRef then this method immediately returns false.

For two file references to be considered equal requires that they are both the same type of FileRef and encapsulate components to locate the same file. This method does not access the file system and the file may not exist.

This method satisfies the general contract of the Object.equals method.

Overrides:

equals in class java.lang.Object

Parameters:

ob - The object to which this object is to be compared

Returns:

true if, and only if, the given object is a FileRef that is identical to this FileRef

See Also:

isSameFile(org.classpath.icedtea.java.nio.file.FileRef)

hashCode

int hashCode()

Returns the hash-code value for this object.

This method satisfies the general contract of the Object.hashCode method.

Overrides:

hashCode in class java.lang.Object