|
NIO2 API | |||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | |||||||||
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |
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.
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(Object ob)
Tests this object for equality with another object. |
|
|
getFileAttributeView(Class<V> type,
LinkOption... options)
Returns a file attribute view of a given type. |
|
FileAttributeView |
getFileAttributeView(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 |
---|
SeekableByteChannel newByteChannel(OpenOption... options) throws IOException
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.
options
- Options specifying how the file is opened
IllegalArgumentException
- If an invalid combination of options is specified
UnsupportedOperationException
- If an unsupported open 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 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.FileStore getFileStore() throws IOException
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.
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.void checkAccess(AccessMode... modes) throws IOException
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.
modes
- The access modes to check; may have zero elements
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)
IOException
- If an I/O error occurs
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.<V extends FileAttributeView> V getFileAttributeView(Class<V> type, LinkOption... options)
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.
type
- The Class
object corresponding to the file attribute viewoptions
- Options indicating how symbolic links are handled
null
if
the attribute view type is not available
UnsupportedOperationException
- If options contains an unsupported option. This exception is
specified to allow the LinkOption
enum be extended
in future releases.Attributes#readBasicFileAttributes
FileAttributeView getFileAttributeView(String name, LinkOption... options)
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.
name
- The name of the file attribute viewoptions
- Options indicating how symbolic links are handled
null
if
the attribute view is not available
UnsupportedOperationException
- If options contains an unsupported option. This exception is
specified to allow the LinkOption
enum be extended
in future releases.boolean isSameFile(FileRef other) throws IOException
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
.
FileRef
f
,
f.isSameFile(f)
should return true
.
FileRefs
f
and g
, f.isSameFile(g)
will equal
g.isSameFile(f)
.
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
.
other
- The other file reference
true
if, and only if, this object and the given object
locate the same file
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 both files.file.attribute.BasicFileAttributes
void delete() throws IOException
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.
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)
IOException
- If an I/O error occurs
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 fileboolean equals(Object ob)
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.
equals
in class Object
ob
- The object to which this object is to be compared
true
if, and only if, the given object is a FileRef
that is identical to this FileRef
isSameFile(org.classpath.icedtea.java.nio.file.FileRef)
int hashCode()
This method satisfies the general contract of the
Object.hashCode
method.
hashCode
in class Object
|
NIO2 API | |||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | |||||||||
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |
Copyright © 2007, 2011, Oracle and/or its affiliates. All rights reserved.