java.nio.file
Interface FileRef

All Known Implementing Classes:

Path

public interface FileRef

Disabled: no SafeJ information.

A reference to a file.

A FileRef is an object that locates a file and defines methods to open the file for reading or writing. It also provides access to associated metadata or file attributes.

Since:

1.7

See Also:

Attributes, File.toPath()

Method Summary

Object	getAttribute(String attribute, LinkOption... options) Reads the value of a file attribute.
<V extends FileAttributeView> V	getFileAttributeView(Class<V> type, LinkOption... options) Returns a file attribute view of a given type.
InputStream	newInputStream(OpenOption... options) Opens the file referenced by this object, returning an input stream to read from the file.
OutputStream	newOutputStream(OpenOption... options) Opens or creates the file located by this object for writing, returning an output stream to write bytes to the file.
Map<String,?>	readAttributes(String attributes, LinkOption... options) Reads a set of file attributes as a bulk operation.
void	setAttribute(String attribute, Object value, LinkOption... options) Sets the value of a file attribute.

Method Detail

newInputStream

InputStream newInputStream(OpenOption... options)
                           throws IOException

Class is disabled.

Opens the file referenced by this object, returning an input stream to read from the file. The stream will not be buffered, and is not required to support the mark or reset methods. The stream will be safe for access by multiple concurrent threads. Reading commences at the beginning of the file.

The options parameter determines how the file is opened. If no options are present then it is equivalent to opening the file with the READ option. In addition to the READ option, an implementation may also support additional implementation specific options.

Returns:

an input stream to read bytes from the file

Throws:

IllegalArgumentException - if an invalid combination of options is specified

UnsupportedOperationException - if an unsupported option is specified

IOException - if an I/O error occurs

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.

newOutputStream

OutputStream newOutputStream(OpenOption... options)
                             throws IOException

Class is disabled.

Opens or creates the file located by this object for writing, returning an output stream to write bytes to the file.

The options parameter determines how the file is opened. If no options are present then this method creates a new file for writing or truncates an existing file. In addition to the standard options, an implementation may also support additional implementation specific options.

The resulting stream will not be buffered. The stream will be safe for access by multiple concurrent threads.

Parameters:

options - options specifying how the file is opened

Returns:

a new output stream

Throws:

IllegalArgumentException - if options contains an invalid combination of options

UnsupportedOperationException - if an unsupported option is specified

IOException - if an I/O error occurs

SecurityException - In the case of the default provider, and a security manager is installed, the checkWrite method is invoked to check write access to the file.

getFileAttributeView

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

Class is disabled.

Returns a file attribute view of a given type.

A file attribute view provides a read-only or updatable view of a set of file attributes. 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:

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(java.nio.file.FileRef, java.nio.file.LinkOption...)

setAttribute

void setAttribute(String attribute,
                  Object value,
                  LinkOption... options)
                  throws IOException

Class is disabled.

Sets the value of a file attribute.

The attribute parameter identifies the attribute to be set and takes the form:

[view-name:]attribute-name

where square brackets [...] delineate an optional component and the character ':' stands for itself.

view-name is the name of a FileAttributeView that identifies a set of file attributes. If not specified then it defaults to "basic", the name of the file attribute view that identifies the basic set of file attributes common to many file systems. attribute-name is the name of the attribute within the set.

Usage Example: Suppose we want to set the DOS "hidden" attribute:

    file.setAttribute("dos:hidden", true);
 

Parameters:

attribute - the attribute to set

value - the attribute value

options - options indicating how symbolic links are handled

Throws:

UnsupportedOperationException - if the attribute view is not available or it does not support updating the attribute

IllegalArgumentException - if the attribute value is of the correct type but has an inappropriate value

ClassCastException - If the attribute value is not of the expected type or is a collection containing elements that are not of the expected type

IOException - If an I/O error occurs

SecurityException - In the case of the default provider, and a security manager is installed, its checkWrite method denies write access to the file. If this method is invoked to set security sensitive attributes then the security manager may be invoked to check for additional permissions.

getAttribute

Object getAttribute(String attribute,
                    LinkOption... options)
                    throws IOException

Class is disabled.

Reads the value of a file attribute.

The attribute parameter identifies the attribute to be read and takes the form:

[view-name:]attribute-name

where square brackets [...] delineate an optional component and the character ':' stands for itself.

view-name is the name of a FileAttributeView that identifies a set of file attributes. If not specified then it defaults to "basic", the name of the file attribute view that identifies the basic set of file attributes common to many file systems. attribute-name is the name of the attribute.

The options array may be used to indicate how symbolic links are handled for the case that the file is a symbolic link. By default, symbolic links are followed and the file attribute of the final target of the link is read. If the option NOFOLLOW_LINKS is present then symbolic links are not followed and so the method returns the file attribute of the symbolic link.

Usage Example: Suppose we require the user ID of the file owner on a system that supports a "unix" view:

    int uid = (Integer)file.getAttribute("unix:uid");
 

Parameters:

attribute - the attribute to read

options - options indicating how symbolic links are handled

Returns:

the attribute value or null if the attribute view is not available or it does not support reading the attribute reading the attribute

Throws:

IOException - if an I/O error occurs

SecurityException - In the case of the default provider, and a security manager is installed, its checkRead method denies read access to the file. If this method is invoked to read security sensitive attributes then the security manager may be invoked to check for additional permissions.

readAttributes

Map<String,?> readAttributes(String attributes,
                             LinkOption... options)
                             throws IOException

Class is disabled.

Reads a set of file attributes as a bulk operation.

The attributes parameter identifies the attributes to be read and takes the form:

[view-name:]attribute-list

where square brackets [...] delineate an optional component and the character ':' stands for itself.

view-name is the name of a FileAttributeView that identifies a set of file attributes. If not specified then it defaults to "basic", the name of the file attribute view that identifies the basic set of file attributes common to many file systems.

The attribute-list component is a comma separated list of zero or more names of attributes to read. If the list contains the value "*" then all attributes are read. Attributes that are not supported are ignored and will not be present in the returned map. It is implementation specific if all attributes are read as an atomic operation with respect to other file system operations.

The following examples demonstrate possible values for the attributes parameter:

"*"	Read all basic-file-attributes.
"size,lastModifiedTime,lastAccessTime"	Reads the file size, last modified time, and last access time attributes.
"posix:*"	Read all POSIX-file-attributes..
"posix:permissions,owner,size"	Reads the POSX file permissions, owner, and file size.

The options array may be used to indicate how symbolic links are handled for the case that the file is a symbolic link. By default, symbolic links are followed and the file attribute of the final target of the link is read. If the option NOFOLLOW_LINKS is present then symbolic links are not followed and so the method returns the file attribute of the symbolic link.

Parameters:

attributes - The attributes to read

options - Options indicating how symbolic links are handled

Returns:

A map of the attributes returned; may be empty. The map's keys are the attribute names, its values are the attribute values

Throws:

IOException - If an I/O error occurs

SecurityException - In the case of the default provider, and a security manager is installed, its checkRead method denies read access to the file. If this method is invoked to read security sensitive attributes then the security manager may be invoke to check for additional permissions.