Checked exception thrown when a file system operation is denied, typically due to a file permission or other access check.
This exception is not related to the AccessControlException or SecurityException thrown by access controllers or security managers when access to a file is denied.
Checked exception thrown when a file system operation is denied, typically due to a file permission or other access check. This exception is not related to the AccessControlException or SecurityException thrown by access controllers or security managers when access to a file is denied.
Checked exception thrown when a file cannot be moved as an atomic file system operation.
Checked exception thrown when a file cannot be moved as an atomic file system operation.
An entry in an access control list (ACL).
The ACL entry represented by this class is based on the ACL model specified in RFC 3530: Network File System (NFS) version 4 Protocol. Each entry has four components as follows:
The type component determines if the entry
grants or denies access.
The principal component, sometimes called the
"who" component, is a UserPrincipal corresponding to the identity that the entry grants or denies access
The permissions component is a set of
permissions
The flags component is a set of flags to indicate how entries are inherited and propagated
ACL entries are created using an associated AclEntry.Builder object by invoking its build method.
ACL entries are immutable and are safe for use by multiple concurrent threads.
An entry in an access control list (ACL). The ACL entry represented by this class is based on the ACL model specified in RFC 3530: Network File System (NFS) version 4 Protocol. Each entry has four components as follows: The type component determines if the entry grants or denies access. The principal component, sometimes called the "who" component, is a UserPrincipal corresponding to the identity that the entry grants or denies access The permissions component is a set of permissions The flags component is a set of flags to indicate how entries are inherited and propagated ACL entries are created using an associated AclEntry.Builder object by invoking its build method. ACL entries are immutable and are safe for use by multiple concurrent threads.
A builder of AclEntry objects.
A Builder object is obtained by invoking one of the newBuilder methods defined by the AclEntry class.
Builder objects are mutable and are not safe for use by multiple concurrent threads without appropriate synchronization.
A builder of AclEntry objects. A Builder object is obtained by invoking one of the newBuilder methods defined by the AclEntry class. Builder objects are mutable and are not safe for use by multiple concurrent threads without appropriate synchronization.
A file attribute view that supports reading or updating a file's Access Control Lists (ACL) or file owner attributes.
ACLs are used to specify access rights to file system objects. An ACL is an ordered list of access-control-entries, each specifying a UserPrincipal and the level of access for that user principal. This file attribute view defines the getAcl, and setAcl methods to read and write ACLs based on the ACL model specified in RFC 3530: Network File System (NFS) version 4 Protocol. This file attribute view is intended for file system implementations that support the NFSv4 ACL model or have a well-defined mapping between the NFSv4 ACL model and the ACL model used by the file system. The details of such mapping are implementation dependent and are therefore unspecified.
This class also extends FileOwnerAttributeView so as to define methods to get and set the file owner.
When a file system provides access to a set of file-systems that are not homogeneous then only some of the file systems may support ACLs. The supportsFileAttributeView method can be used to test if a file system supports ACLs.
Interoperability
RFC 3530 allows for special user identities to be used on platforms that support the POSIX defined access permissions. The special user identities are "OWNER@", "GROUP@", and "EVERYONE@". When both the AclFileAttributeView and the PosixFileAttributeView are supported then these special user identities may be included in ACL entries that are read or written. The file system's UserPrincipalLookupService may be used to obtain a UserPrincipal to represent these special identities by invoking the lookupPrincipalByName method.
Usage Example: Suppose we wish to add an entry to an existing ACL to grant "joe" access:
// lookup "joe"
UserPrincipal joe = file.getFileSystem().getUserPrincipalLookupService()
.lookupPrincipalByName("joe");
// get view
AclFileAttributeView view = Files.getFileAttributeView(file, AclFileAttributeView.class);
// create ACE to give "joe" read access
AclEntry entry = AclEntry.newBuilder()
.setType(AclEntryType.ALLOW)
.setPrincipal(joe)
.setPermissions(AclEntryPermission.READ_DATA, AclEntryPermission.READ_ATTRIBUTES)
.build();
// read ACL, insert ACE, re-write ACL
List<AclEntry> acl = view.getAcl();
acl.add(0, entry); // insert before any DENY entries
view.setAcl(acl);
Dynamic Access Where dynamic access to file attributes is required, the attributes supported by this attribute view are as follows:
Name
Type
"acl"
List<AclEntry>
"owner"
UserPrincipal
The getAttribute method may be used to read the ACL or owner attributes as if by invoking the getAcl or getOwner methods.
The setAttribute method may be used to update the ACL or owner attributes as if by invoking the setAcl or setOwner methods.
Setting the ACL when creating a file
Implementations supporting this attribute view may also support setting the initial ACL when creating a file or directory. The initial ACL may be provided to methods such as createFile or createDirectory as an FileAttribute with name "acl:acl" and a value that is the list of AclEntry objects.
Where an implementation supports an ACL model that differs from the NFSv4 defined ACL model then setting the initial ACL when creating the file must translate the ACL to the model supported by the file system. Methods that create a file should reject (by throwing IOException) any attempt to create a file that would be less secure as a result of the translation.
A file attribute view that supports reading or updating a file's Access Control Lists (ACL) or file owner attributes. ACLs are used to specify access rights to file system objects. An ACL is an ordered list of access-control-entries, each specifying a UserPrincipal and the level of access for that user principal. This file attribute view defines the getAcl, and setAcl methods to read and write ACLs based on the ACL model specified in RFC 3530: Network File System (NFS) version 4 Protocol. This file attribute view is intended for file system implementations that support the NFSv4 ACL model or have a well-defined mapping between the NFSv4 ACL model and the ACL model used by the file system. The details of such mapping are implementation dependent and are therefore unspecified. This class also extends FileOwnerAttributeView so as to define methods to get and set the file owner. When a file system provides access to a set of file-systems that are not homogeneous then only some of the file systems may support ACLs. The supportsFileAttributeView method can be used to test if a file system supports ACLs. Interoperability RFC 3530 allows for special user identities to be used on platforms that support the POSIX defined access permissions. The special user identities are "OWNER@", "GROUP@", and "EVERYONE@". When both the AclFileAttributeView and the PosixFileAttributeView are supported then these special user identities may be included in ACL entries that are read or written. The file system's UserPrincipalLookupService may be used to obtain a UserPrincipal to represent these special identities by invoking the lookupPrincipalByName method. Usage Example: Suppose we wish to add an entry to an existing ACL to grant "joe" access: // lookup "joe" UserPrincipal joe = file.getFileSystem().getUserPrincipalLookupService() .lookupPrincipalByName("joe"); // get view AclFileAttributeView view = Files.getFileAttributeView(file, AclFileAttributeView.class); // create ACE to give "joe" read access AclEntry entry = AclEntry.newBuilder() .setType(AclEntryType.ALLOW) .setPrincipal(joe) .setPermissions(AclEntryPermission.READ_DATA, AclEntryPermission.READ_ATTRIBUTES) .build(); // read ACL, insert ACE, re-write ACL List<AclEntry> acl = view.getAcl(); acl.add(0, entry); // insert before any DENY entries view.setAcl(acl); Dynamic Access Where dynamic access to file attributes is required, the attributes supported by this attribute view are as follows: Name Type "acl" List<AclEntry> "owner" UserPrincipal The getAttribute method may be used to read the ACL or owner attributes as if by invoking the getAcl or getOwner methods. The setAttribute method may be used to update the ACL or owner attributes as if by invoking the setAcl or setOwner methods. Setting the ACL when creating a file Implementations supporting this attribute view may also support setting the initial ACL when creating a file or directory. The initial ACL may be provided to methods such as createFile or createDirectory as an FileAttribute with name "acl:acl" and a value that is the list of AclEntry objects. Where an implementation supports an ACL model that differs from the NFSv4 defined ACL model then setting the initial ACL when creating the file must translate the ACL to the model supported by the file system. Methods that create a file should reject (by throwing IOException) any attempt to create a file that would be less secure as a result of the translation.
An object that provides a read-only or updatable view of non-opaque values associated with an object in a filesystem. This interface is extended or implemented by specific attribute views that define the attributes supported by the view. A specific attribute view will typically define type-safe methods to read or update the attributes that it supports.
An object that provides a read-only or updatable view of non-opaque values associated with an object in a filesystem. This interface is extended or implemented by specific attribute views that define the attributes supported by the view. A specific attribute view will typically define type-safe methods to read or update the attributes that it supports.
Basic attributes associated with a file in a file system.
Basic file attributes are attributes that are common to many file systems and consist of mandatory and optional file attributes as defined by this interface.
Usage Example:
Path file = ... BasicFileAttributes attrs = Files.readAttributes(file, BasicFileAttributes.class);
Basic attributes associated with a file in a file system. Basic file attributes are attributes that are common to many file systems and consist of mandatory and optional file attributes as defined by this interface. Usage Example: Path file = ... BasicFileAttributes attrs = Files.readAttributes(file, BasicFileAttributes.class);
A file attribute view that provides a view of a basic set of file attributes common to many file systems. The basic set of file attributes consist of mandatory and optional file attributes as defined by the BasicFileAttributes interface.
The file attributes are retrieved from the file system as a bulk operation by invoking the readAttributes method. This class also defines the setTimes method to update the file's time attributes.
Where dynamic access to file attributes is required, the attributes supported by this attribute view have the following names and types:
Name
Type
"lastModifiedTime"
FileTime
"lastAccessTime"
FileTime
"creationTime"
FileTime
"size"
Long
"isRegularFile"
Boolean
"isDirectory"
Boolean
"isSymbolicLink"
Boolean
"isOther"
Boolean
"fileKey"
Object
The getAttribute method may be used to read any of these attributes as if by invoking the readAttributes() method.
The setAttribute method may be used to update the file's last modified time, last access time or create time attributes as if by invoking the setTimes method.
A file attribute view that provides a view of a basic set of file attributes common to many file systems. The basic set of file attributes consist of mandatory and optional file attributes as defined by the BasicFileAttributes interface. The file attributes are retrieved from the file system as a bulk operation by invoking the readAttributes method. This class also defines the setTimes method to update the file's time attributes. Where dynamic access to file attributes is required, the attributes supported by this attribute view have the following names and types: Name Type "lastModifiedTime" FileTime "lastAccessTime" FileTime "creationTime" FileTime "size" Long "isRegularFile" Boolean "isDirectory" Boolean "isSymbolicLink" Boolean "isOther" Boolean "fileKey" Object The getAttribute method may be used to read any of these attributes as if by invoking the readAttributes() method. The setAttribute method may be used to update the file's last modified time, last access time or create time attributes as if by invoking the setTimes method.
No vars found in this namespace.
File attributes associated with a file in a file system that supports legacy "DOS" attributes.
Usage Example:
Path file = ... DosFileAttributes attrs = Files.readAttributes(file, DosFileAttributes.class);
File attributes associated with a file in a file system that supports legacy "DOS" attributes. Usage Example: Path file = ... DosFileAttributes attrs = Files.readAttributes(file, DosFileAttributes.class);
A file attribute view that provides a view of the legacy "DOS" file attributes. These attributes are supported by file systems such as the File Allocation Table (FAT) format commonly used in consumer devices.
A DosFileAttributeView is a BasicFileAttributeView that additionally supports access to the set of DOS attribute flags that are used to indicate if the file is read-only, hidden, a system file, or archived.
Where dynamic access to file attributes is required, the attributes supported by this attribute view are as defined by BasicFileAttributeView, and in addition, the following attributes are supported:
Name
Type
readonly
Boolean
hidden
Boolean
system
Boolean
archive
Boolean
The getAttribute method may be used to read any of these attributes, or any of the attributes defined by BasicFileAttributeView as if by invoking the readAttributes() method.
The setAttribute method may be used to update the file's last modified time, last access time or create time attributes as defined by BasicFileAttributeView. It may also be used to update the DOS attributes as if by invoking the setReadOnly, setHidden, setSystem, and setArchive methods respectively.
A file attribute view that provides a view of the legacy "DOS" file attributes. These attributes are supported by file systems such as the File Allocation Table (FAT) format commonly used in consumer devices. A DosFileAttributeView is a BasicFileAttributeView that additionally supports access to the set of DOS attribute flags that are used to indicate if the file is read-only, hidden, a system file, or archived. Where dynamic access to file attributes is required, the attributes supported by this attribute view are as defined by BasicFileAttributeView, and in addition, the following attributes are supported: Name Type readonly Boolean hidden Boolean system Boolean archive Boolean The getAttribute method may be used to read any of these attributes, or any of the attributes defined by BasicFileAttributeView as if by invoking the readAttributes() method. The setAttribute method may be used to update the file's last modified time, last access time or create time attributes as defined by BasicFileAttributeView. It may also be used to update the DOS attributes as if by invoking the setReadOnly, setHidden, setSystem, and setArchive methods respectively.
An object that encapsulates the value of a file attribute that can be set atomically when creating a new file or directory by invoking the createFile or createDirectory methods.
An object that encapsulates the value of a file attribute that can be set atomically when creating a new file or directory by invoking the createFile or createDirectory methods.
An attribute view that is a read-only or updatable view of non-opaque values associated with a file in a filesystem. This interface is extended or implemented by specific file attribute views that define methods to read and/or update the attributes of a file.
An attribute view that is a read-only or updatable view of non-opaque values associated with a file in a filesystem. This interface is extended or implemented by specific file attribute views that define methods to read and/or update the attributes of a file.
No vars found in this namespace.
A file attribute view that supports reading or updating the owner of a file. This file attribute view is intended for file system implementations that support a file attribute that represents an identity that is the owner of the file. Often the owner of a file is the identity of the entity that created the file.
The getOwner or setOwner methods may be used to read or update the owner of the file.
The getAttribute and setAttribute methods may also be used to read or update the owner. In that case, the owner attribute is identified by the name "owner", and the value of the attribute is a UserPrincipal.
A file attribute view that supports reading or updating the owner of a file. This file attribute view is intended for file system implementations that support a file attribute that represents an identity that is the owner of the file. Often the owner of a file is the identity of the entity that created the file. The getOwner or setOwner methods may be used to read or update the owner of the file. The getAttribute and setAttribute methods may also be used to read or update the owner. In that case, the owner attribute is identified by the name "owner", and the value of the attribute is a UserPrincipal.
An attribute view that is a read-only or updatable view of the attributes of a FileStore.
An attribute view that is a read-only or updatable view of the attributes of a FileStore.
No vars found in this namespace.
Represents the value of a file's time stamp attribute. For example, it may represent the time that the file was last modified, accessed, or created.
Instances of this class are immutable.
Represents the value of a file's time stamp attribute. For example, it may represent the time that the file was last modified, accessed, or created. Instances of this class are immutable.
A UserPrincipal representing a group identity, used to determine access rights to objects in a file system. The exact definition of a group is implementation specific, but typically, it represents an identity created for administrative purposes so as to determine the access rights for the members of the group. Whether an entity can be a member of multiple groups, and whether groups can be nested, are implementation specified and therefore not specified.
A UserPrincipal representing a group identity, used to determine access rights to objects in a file system. The exact definition of a group is implementation specific, but typically, it represents an identity created for administrative purposes so as to determine the access rights for the members of the group. Whether an entity can be a member of multiple groups, and whether groups can be nested, are implementation specified and therefore not specified.
No vars found in this namespace.
File attributes associated with files on file systems used by operating systems that implement the Portable Operating System Interface (POSIX) family of standards.
The POSIX attributes of a file are retrieved using a PosixFileAttributeView by invoking its readAttributes method.
File attributes associated with files on file systems used by operating systems that implement the Portable Operating System Interface (POSIX) family of standards. The POSIX attributes of a file are retrieved using a PosixFileAttributeView by invoking its readAttributes method.
A file attribute view that provides a view of the file attributes commonly associated with files on file systems used by operating systems that implement the Portable Operating System Interface (POSIX) family of standards.
Operating systems that implement the POSIX family of standards commonly use file systems that have a file owner, group-owner, and related access permissions. This file attribute view provides read and write access to these attributes.
The readAttributes method is used to read the file's attributes. The file owner is represented by a UserPrincipal that is the identity of the file owner for the purposes of access control. The group-owner, represented by a GroupPrincipal, is the identity of the group owner, where a group is an identity created for administrative purposes so as to determine the access rights for the members of the group.
The permissions attribute is a set of access permissions. This file attribute view provides access to the nine permission defined by the PosixFilePermission class. These nine permission bits determine the read, write, and execute access for the file owner, group, and others (others meaning identities other than the owner and members of the group). Some operating systems and file systems may provide additional permission bits but access to these other bits is not defined by this class in this release.
Usage Example: Suppose we need to print out the owner and access permissions of a file:
Path file = ...
PosixFileAttributes attrs = Files.getFileAttributeView(file, PosixFileAttributeView.class)
.readAttributes();
System.out.format("%s %s%n",
attrs.owner().getName(),
PosixFilePermissions.toString(attrs.permissions()));
Dynamic Access Where dynamic access to file attributes is required, the attributes supported by this attribute view are as defined by BasicFileAttributeView and FileOwnerAttributeView, and in addition, the following attributes are supported:
Name
Type
"permissions"
Set<PosixFilePermission>
"group"
GroupPrincipal
The getAttribute method may be used to read any of these attributes, or any of the attributes defined by BasicFileAttributeView as if by invoking the readAttributes() method.
The setAttribute method may be used to update the file's last modified time, last access time or create time attributes as defined by BasicFileAttributeView. It may also be used to update the permissions, owner, or group-owner as if by invoking the setPermissions, setOwner, and setGroup methods respectively.
Setting Initial Permissions Implementations supporting this attribute view may also support setting the initial permissions when creating a file or directory. The initial permissions are provided to the createFile or createDirectory methods as a FileAttribute with name "posix:permissions" and a value that is the set of permissions. The following example uses the asFileAttribute method to construct a FileAttribute when creating a file:
Path path = ...
Set<PosixFilePermission> perms =
EnumSet.of(OWNER_READ, OWNER_WRITE, OWNER_EXECUTE, GROUP_READ);
Files.createFile(path, PosixFilePermissions.asFileAttribute(perms));
When the access permissions are set at file creation time then the actual value of the permissions may differ that the value of the attribute object. The reasons for this are implementation specific. On UNIX systems, for example, a process has a umask that impacts the permission bits of newly created files. Where an implementation supports the setting of the access permissions, and the underlying file system supports access permissions, then it is required that the value of the actual access permissions will be equal or less than the value of the attribute provided to the createFile or createDirectory methods. In other words, the file may be more secure than requested.
A file attribute view that provides a view of the file attributes commonly associated with files on file systems used by operating systems that implement the Portable Operating System Interface (POSIX) family of standards. Operating systems that implement the POSIX family of standards commonly use file systems that have a file owner, group-owner, and related access permissions. This file attribute view provides read and write access to these attributes. The readAttributes method is used to read the file's attributes. The file owner is represented by a UserPrincipal that is the identity of the file owner for the purposes of access control. The group-owner, represented by a GroupPrincipal, is the identity of the group owner, where a group is an identity created for administrative purposes so as to determine the access rights for the members of the group. The permissions attribute is a set of access permissions. This file attribute view provides access to the nine permission defined by the PosixFilePermission class. These nine permission bits determine the read, write, and execute access for the file owner, group, and others (others meaning identities other than the owner and members of the group). Some operating systems and file systems may provide additional permission bits but access to these other bits is not defined by this class in this release. Usage Example: Suppose we need to print out the owner and access permissions of a file: Path file = ... PosixFileAttributes attrs = Files.getFileAttributeView(file, PosixFileAttributeView.class) .readAttributes(); System.out.format("%s %s%n", attrs.owner().getName(), PosixFilePermissions.toString(attrs.permissions())); Dynamic Access Where dynamic access to file attributes is required, the attributes supported by this attribute view are as defined by BasicFileAttributeView and FileOwnerAttributeView, and in addition, the following attributes are supported: Name Type "permissions" Set<PosixFilePermission> "group" GroupPrincipal The getAttribute method may be used to read any of these attributes, or any of the attributes defined by BasicFileAttributeView as if by invoking the readAttributes() method. The setAttribute method may be used to update the file's last modified time, last access time or create time attributes as defined by BasicFileAttributeView. It may also be used to update the permissions, owner, or group-owner as if by invoking the setPermissions, setOwner, and setGroup methods respectively. Setting Initial Permissions Implementations supporting this attribute view may also support setting the initial permissions when creating a file or directory. The initial permissions are provided to the createFile or createDirectory methods as a FileAttribute with name "posix:permissions" and a value that is the set of permissions. The following example uses the asFileAttribute method to construct a FileAttribute when creating a file: Path path = ... Set<PosixFilePermission> perms = EnumSet.of(OWNER_READ, OWNER_WRITE, OWNER_EXECUTE, GROUP_READ); Files.createFile(path, PosixFilePermissions.asFileAttribute(perms)); When the access permissions are set at file creation time then the actual value of the permissions may differ that the value of the attribute object. The reasons for this are implementation specific. On UNIX systems, for example, a process has a umask that impacts the permission bits of newly created files. Where an implementation supports the setting of the access permissions, and the underlying file system supports access permissions, then it is required that the value of the actual access permissions will be equal or less than the value of the attribute provided to the createFile or createDirectory methods. In other words, the file may be more secure than requested.
This class consists exclusively of static methods that operate on sets of PosixFilePermission objects.
This class consists exclusively of static methods that operate on sets of PosixFilePermission objects.
A file attribute view that provides a view of a file's user-defined attributes, sometimes known as extended attributes. User-defined file attributes are used to store metadata with a file that is not meaningful to the file system. It is primarily intended for file system implementations that support such a capability directly but may be emulated. The details of such emulation are highly implementation specific and therefore not specified.
This FileAttributeView provides a view of a file's user-defined attributes as a set of name/value pairs, where the attribute name is represented by a String. An implementation may require to encode and decode from the platform or file system representation when accessing the attribute. The value has opaque content. This attribute view defines the read and write methods to read the value into or write from a ByteBuffer. This FileAttributeView is not intended for use where the size of an attribute value is larger than Integer.MAX_VALUE.
User-defined attributes may be used in some implementations to store security related attributes so consequently, in the case of the default provider at least, all methods that access user-defined attributes require the RuntimePermission("accessUserDefinedAttributes") permission when a security manager is installed.
The supportsFileAttributeView method may be used to test if a specific FileStore supports the storage of user-defined attributes.
Where dynamic access to file attributes is required, the getAttribute method may be used to read the attribute value. The attribute value is returned as a byte array (byte[]). The setAttribute method may be used to write the value of a user-defined attribute from a buffer (as if by invoking the write method), or byte array (byte[]).
A file attribute view that provides a view of a file's user-defined attributes, sometimes known as extended attributes. User-defined file attributes are used to store metadata with a file that is not meaningful to the file system. It is primarily intended for file system implementations that support such a capability directly but may be emulated. The details of such emulation are highly implementation specific and therefore not specified. This FileAttributeView provides a view of a file's user-defined attributes as a set of name/value pairs, where the attribute name is represented by a String. An implementation may require to encode and decode from the platform or file system representation when accessing the attribute. The value has opaque content. This attribute view defines the read and write methods to read the value into or write from a ByteBuffer. This FileAttributeView is not intended for use where the size of an attribute value is larger than Integer.MAX_VALUE. User-defined attributes may be used in some implementations to store security related attributes so consequently, in the case of the default provider at least, all methods that access user-defined attributes require the RuntimePermission("accessUserDefinedAttributes") permission when a security manager is installed. The supportsFileAttributeView method may be used to test if a specific FileStore supports the storage of user-defined attributes. Where dynamic access to file attributes is required, the getAttribute method may be used to read the attribute value. The attribute value is returned as a byte array (byte[]). The setAttribute method may be used to write the value of a user-defined attribute from a buffer (as if by invoking the write method), or byte array (byte[]).
A Principal representing an identity used to determine access rights to objects in a file system.
On many platforms and file systems an entity requires appropriate access rights or permissions in order to access objects in a file system. The access rights are generally performed by checking the identity of the entity. For example, on implementations that use Access Control Lists (ACLs) to enforce privilege separation then a file in the file system may have an associated ACL that determines the access rights of identities specified in the ACL.
A UserPrincipal object is an abstract representation of an identity. It has a name that is typically the username or account name that it represents. User principal objects may be obtained using a UserPrincipalLookupService, or returned by FileAttributeView implementations that provide access to identity related attributes. For example, the AclFileAttributeView and PosixFileAttributeView provide access to a file's owner.
A Principal representing an identity used to determine access rights to objects in a file system. On many platforms and file systems an entity requires appropriate access rights or permissions in order to access objects in a file system. The access rights are generally performed by checking the identity of the entity. For example, on implementations that use Access Control Lists (ACLs) to enforce privilege separation then a file in the file system may have an associated ACL that determines the access rights of identities specified in the ACL. A UserPrincipal object is an abstract representation of an identity. It has a name that is typically the username or account name that it represents. User principal objects may be obtained using a UserPrincipalLookupService, or returned by FileAttributeView implementations that provide access to identity related attributes. For example, the AclFileAttributeView and PosixFileAttributeView provide access to a file's owner.
No vars found in this namespace.
An object to lookup user and group principals by name. A UserPrincipal represents an identity that may be used to determine access rights to objects in a file system. A GroupPrincipal represents a group identity. A UserPrincipalLookupService defines methods to lookup identities by name or group name (which are typically user or account names). Whether names and group names are case sensitive or not depends on the implementation. The exact definition of a group is implementation specific but typically a group represents an identity created for administrative purposes so as to determine the access rights for the members of the group. In particular it is implementation specific if the namespace for names and groups is the same or is distinct. To ensure consistent and correct behavior across platforms it is recommended that this API be used as if the namespaces are distinct. In other words, the lookupPrincipalByName should be used to lookup users, and lookupPrincipalByGroupName should be used to lookup groups.
An object to lookup user and group principals by name. A UserPrincipal represents an identity that may be used to determine access rights to objects in a file system. A GroupPrincipal represents a group identity. A UserPrincipalLookupService defines methods to lookup identities by name or group name (which are typically user or account names). Whether names and group names are case sensitive or not depends on the implementation. The exact definition of a group is implementation specific but typically a group represents an identity created for administrative purposes so as to determine the access rights for the members of the group. In particular it is implementation specific if the namespace for names and groups is the same or is distinct. To ensure consistent and correct behavior across platforms it is recommended that this API be used as if the namespaces are distinct. In other words, the lookupPrincipalByName should be used to lookup users, and lookupPrincipalByGroupName should be used to lookup groups.
Checked exception thrown when a lookup of UserPrincipal fails because the principal does not exist.
Checked exception thrown when a lookup of UserPrincipal fails because the principal does not exist.
Unchecked exception thrown when an attempt is made to invoke an operation on a directory stream that is closed.
Unchecked exception thrown when an attempt is made to invoke an operation on a directory stream that is closed.
Unchecked exception thrown when an attempt is made to invoke an operation on a file and the file system is closed.
Unchecked exception thrown when an attempt is made to invoke an operation on a file and the file system is closed.
Unchecked exception thrown when an attempt is made to invoke an operation on a watch service that is closed.
Unchecked exception thrown when an attempt is made to invoke an operation on a watch service that is closed.
An object that configures how to copy or move a file.
Objects of this type may be used with the Files.copy(Path,Path,CopyOption...), Files.copy(InputStream,Path,CopyOption...) and Files.move(Path,Path,CopyOption...) methods to configure how a file is copied or moved.
The StandardCopyOption enumeration type defines the standard options.
An object that configures how to copy or move a file. Objects of this type may be used with the Files.copy(Path,Path,CopyOption...), Files.copy(InputStream,Path,CopyOption...) and Files.move(Path,Path,CopyOption...) methods to configure how a file is copied or moved. The StandardCopyOption enumeration type defines the standard options.
No vars found in this namespace.
No vars found in this namespace.
Runtime exception thrown if an I/O error is encountered when iterating over the entries in a directory. The I/O error is retrieved as an IOException using the getCause() method.
Runtime exception thrown if an I/O error is encountered when iterating over the entries in a directory. The I/O error is retrieved as an IOException using the getCause() method.
Checked exception thrown when a file system operation fails because a directory is not empty.
Checked exception thrown when a file system operation fails because a directory is not empty.
An object to iterate over the entries in a directory. A directory stream allows for the convenient use of the for-each construct to iterate over a directory.
While DirectoryStream extends Iterable, it is not a general-purpose Iterable as it supports only a single Iterator; invoking the iterator method to obtain a second or subsequent iterator throws IllegalStateException.
An important property of the directory stream's Iterator is that its hasNext method is guaranteed to read-ahead by at least one element. If hasNext method returns true, and is followed by a call to the next method, it is guaranteed that the next method will not throw an exception due to an I/O error, or because the stream has been closed. The Iterator does not support the remove operation.
A DirectoryStream is opened upon creation and is closed by invoking the close method. Closing a directory stream releases any resources associated with the stream. Failure to close the stream may result in a resource leak. The try-with-resources statement provides a useful construct to ensure that the stream is closed:
Path dir = ... try (DirectoryStream<Path> stream = Files.newDirectoryStream(dir)) { for (Path entry: stream) { ... } }
Once a directory stream is closed, then further access to the directory, using the Iterator, behaves as if the end of stream has been reached. Due to read-ahead, the Iterator may return one or more elements after the directory stream has been closed. Once these buffered elements have been read, then subsequent calls to the hasNext method returns false, and subsequent calls to the next method will throw NoSuchElementException.
A directory stream is not required to be asynchronously closeable. If a thread is blocked on the directory stream's iterator reading from the directory, and another thread invokes the close method, then the second thread may block until the read operation is complete.
If an I/O error is encountered when accessing the directory then it causes the Iterator's hasNext or next methods to throw DirectoryIteratorException with the IOException as the cause. As stated above, the hasNext method is guaranteed to read-ahead by at least one element. This means that if hasNext method returns true, and is followed by a call to the next method, then it is guaranteed that the next method will not fail with a DirectoryIteratorException.
The elements returned by the iterator are in no specific order. Some file systems maintain special links to the directory itself and the directory's parent directory. Entries representing these links are not returned by the iterator.
The iterator is weakly consistent. It is thread safe but does not freeze the directory while iterating, so it may (or may not) reflect updates to the directory that occur after the DirectoryStream is created.
Usage Examples: Suppose we want a list of the source files in a directory. This example uses both the for-each and try-with-resources constructs.
List<Path> listSourceFiles(Path dir) throws IOException { List<Path> result = new ArrayList<>(); try (DirectoryStream<Path> stream = Files.newDirectoryStream(dir, "*.{c,h,cpp,hpp,java}")) { for (Path entry: stream) { result.add(entry); } } catch (DirectoryIteratorException ex) { // I/O error encounted during the iteration, the cause is an IOException throw ex.getCause(); } return result; }
An object to iterate over the entries in a directory. A directory stream allows for the convenient use of the for-each construct to iterate over a directory. While DirectoryStream extends Iterable, it is not a general-purpose Iterable as it supports only a single Iterator; invoking the iterator method to obtain a second or subsequent iterator throws IllegalStateException. An important property of the directory stream's Iterator is that its hasNext method is guaranteed to read-ahead by at least one element. If hasNext method returns true, and is followed by a call to the next method, it is guaranteed that the next method will not throw an exception due to an I/O error, or because the stream has been closed. The Iterator does not support the remove operation. A DirectoryStream is opened upon creation and is closed by invoking the close method. Closing a directory stream releases any resources associated with the stream. Failure to close the stream may result in a resource leak. The try-with-resources statement provides a useful construct to ensure that the stream is closed: Path dir = ... try (DirectoryStream<Path> stream = Files.newDirectoryStream(dir)) { for (Path entry: stream) { ... } } Once a directory stream is closed, then further access to the directory, using the Iterator, behaves as if the end of stream has been reached. Due to read-ahead, the Iterator may return one or more elements after the directory stream has been closed. Once these buffered elements have been read, then subsequent calls to the hasNext method returns false, and subsequent calls to the next method will throw NoSuchElementException. A directory stream is not required to be asynchronously closeable. If a thread is blocked on the directory stream's iterator reading from the directory, and another thread invokes the close method, then the second thread may block until the read operation is complete. If an I/O error is encountered when accessing the directory then it causes the Iterator's hasNext or next methods to throw DirectoryIteratorException with the IOException as the cause. As stated above, the hasNext method is guaranteed to read-ahead by at least one element. This means that if hasNext method returns true, and is followed by a call to the next method, then it is guaranteed that the next method will not fail with a DirectoryIteratorException. The elements returned by the iterator are in no specific order. Some file systems maintain special links to the directory itself and the directory's parent directory. Entries representing these links are not returned by the iterator. The iterator is weakly consistent. It is thread safe but does not freeze the directory while iterating, so it may (or may not) reflect updates to the directory that occur after the DirectoryStream is created. Usage Examples: Suppose we want a list of the source files in a directory. This example uses both the for-each and try-with-resources constructs. List<Path> listSourceFiles(Path dir) throws IOException { List<Path> result = new ArrayList<>(); try (DirectoryStream<Path> stream = Files.newDirectoryStream(dir, "*.{c,h,cpp,hpp,java}")) { for (Path entry: stream) { result.add(entry); } } catch (DirectoryIteratorException ex) { // I/O error encounted during the iteration, the cause is an IOException throw ex.getCause(); } return result; }
An interface that is implemented by objects that decide if a directory entry should be accepted or filtered. A Filter is passed as the parameter to the Files.newDirectoryStream(Path,DirectoryStream.Filter) method when opening a directory to iterate over the entries in the directory.
An interface that is implemented by objects that decide if a directory entry should be accepted or filtered. A Filter is passed as the parameter to the Files.newDirectoryStream(Path,DirectoryStream.Filter) method when opening a directory to iterate over the entries in the directory.
Checked exception thrown when an attempt is made to create a file or directory and a file of that name already exists.
Checked exception thrown when an attempt is made to create a file or directory and a file of that name already exists.
This class consists exclusively of static methods that operate on files, directories, or other types of files.
In most cases, the methods defined here will delegate to the associated file system provider to perform the file operations.
This class consists exclusively of static methods that operate on files, directories, or other types of files. In most cases, the methods defined here will delegate to the associated file system provider to perform the file operations.
Storage for files. A FileStore represents a storage pool, device, partition, volume, concrete file system or other implementation specific means of file storage. The FileStore for where a file is stored is obtained by invoking the getFileStore method, or all file stores can be enumerated by invoking the getFileStores method.
In addition to the methods defined by this class, a file store may support one or more FileStoreAttributeView classes that provide a read-only or updatable view of a set of file store attributes.
Storage for files. A FileStore represents a storage pool, device, partition, volume, concrete file system or other implementation specific means of file storage. The FileStore for where a file is stored is obtained by invoking the getFileStore method, or all file stores can be enumerated by invoking the getFileStores method. In addition to the methods defined by this class, a file store may support one or more FileStoreAttributeView classes that provide a read-only or updatable view of a set of file store attributes.
Provides an interface to a file system and is the factory for objects to access files and other objects in the file system.
The default file system, obtained by invoking the FileSystems.getDefault method, provides access to the file system that is accessible to the Java virtual machine. The FileSystems class defines methods to create file systems that provide access to other types of (custom) file systems.
A file system is the factory for several types of objects:
The getPath method converts a system dependent path string, returning a Path object that may be used to locate and access a file. The getPathMatcher method is used to create a PathMatcher that performs match operations on paths. The getFileStores method returns an iterator over the underlying file-stores. The getUserPrincipalLookupService method returns the UserPrincipalLookupService to lookup users or groups by name. The newWatchService method creates a WatchService that may be used to watch objects for changes and events.
File systems vary greatly. In some cases the file system is a single hierarchy of files with one top-level root directory. In other cases it may have several distinct file hierarchies, each with its own top-level root directory. The getRootDirectories method may be used to iterate over the root directories in the file system. A file system is typically composed of one or more underlying file-stores that provide the storage for the files. Theses file stores can also vary in the features they support, and the file attributes or meta-data that they associate with files.
A file system is open upon creation and can be closed by invoking its close method. Once closed, any further attempt to access objects in the file system cause ClosedFileSystemException to be thrown. File systems created by the default provider cannot be closed.
A FileSystem can provide read-only or read-write access to the file system. Whether or not a file system provides read-only access is established when the FileSystem is created and can be tested by invoking its isReadOnly method. Attempts to write to file stores by means of an object associated with a read-only file system throws ReadOnlyFileSystemException.
File systems are safe for use by multiple concurrent threads. The close method may be invoked at any time to close a file system but whether a file system is asynchronously closeable is provider specific and therefore unspecified. In other words, if a thread is accessing an object in a file system, and another thread invokes the close method then it may require to block until the first operation is complete. Closing a file system causes all open channels, watch services, and other closeable objects associated with the file system to be closed.
Provides an interface to a file system and is the factory for objects to access files and other objects in the file system. The default file system, obtained by invoking the FileSystems.getDefault method, provides access to the file system that is accessible to the Java virtual machine. The FileSystems class defines methods to create file systems that provide access to other types of (custom) file systems. A file system is the factory for several types of objects: The getPath method converts a system dependent path string, returning a Path object that may be used to locate and access a file. The getPathMatcher method is used to create a PathMatcher that performs match operations on paths. The getFileStores method returns an iterator over the underlying file-stores. The getUserPrincipalLookupService method returns the UserPrincipalLookupService to lookup users or groups by name. The newWatchService method creates a WatchService that may be used to watch objects for changes and events. File systems vary greatly. In some cases the file system is a single hierarchy of files with one top-level root directory. In other cases it may have several distinct file hierarchies, each with its own top-level root directory. The getRootDirectories method may be used to iterate over the root directories in the file system. A file system is typically composed of one or more underlying file-stores that provide the storage for the files. Theses file stores can also vary in the features they support, and the file attributes or meta-data that they associate with files. A file system is open upon creation and can be closed by invoking its close method. Once closed, any further attempt to access objects in the file system cause ClosedFileSystemException to be thrown. File systems created by the default provider cannot be closed. A FileSystem can provide read-only or read-write access to the file system. Whether or not a file system provides read-only access is established when the FileSystem is created and can be tested by invoking its isReadOnly method. Attempts to write to file stores by means of an object associated with a read-only file system throws ReadOnlyFileSystemException. File systems are safe for use by multiple concurrent threads. The close method may be invoked at any time to close a file system but whether a file system is asynchronously closeable is provider specific and therefore unspecified. In other words, if a thread is accessing an object in a file system, and another thread invokes the close method then it may require to block until the first operation is complete. Closing a file system causes all open channels, watch services, and other closeable objects associated with the file system to be closed.
Runtime exception thrown when an attempt is made to create a file system that already exists.
Runtime exception thrown when an attempt is made to create a file system that already exists.
Thrown when a file system operation fails on one or two files. This class is the general class for file system exceptions.
Thrown when a file system operation fails on one or two files. This class is the general class for file system exceptions.
Checked exception thrown when a file system loop, or cycle, is encountered.
Checked exception thrown when a file system loop, or cycle, is encountered.
Runtime exception thrown when a file system cannot be found.
Runtime exception thrown when a file system cannot be found.
Factory methods for file systems. This class defines the getDefault method to get the default file system and factory methods to construct other types of file systems.
The first invocation of any of the methods defined by this class causes the default provider to be loaded. The default provider, identified by the URI scheme "file", creates the FileSystem that provides access to the file systems accessible to the Java virtual machine. If the process of loading or initializing the default provider fails then an unspecified error is thrown.
The first invocation of the installedProviders method, by way of invoking any of the newFileSystem methods defined by this class, locates and loads all installed file system providers. Installed providers are loaded using the service-provider loading facility defined by the ServiceLoader class. Installed providers are loaded using the system class loader. If the system class loader cannot be found then the extension class loader is used; if there is no extension class loader then the bootstrap class loader is used. Providers are typically installed by placing them in a JAR file on the application class path or in the extension directory, the JAR file contains a provider-configuration file named java.nio.file.spi.FileSystemProvider in the resource directory META-INF/services, and the file lists one or more fully-qualified names of concrete subclass of FileSystemProvider that have a zero argument constructor. The ordering that installed providers are located is implementation specific. If a provider is instantiated and its getScheme returns the same URI scheme of a provider that was previously instantiated then the most recently instantiated duplicate is discarded. URI schemes are compared without regard to case. During construction a provider may safely access files associated with the default provider but care needs to be taken to avoid circular loading of other installed providers. If circular loading of installed providers is detected then an unspecified error is thrown.
This class also defines factory methods that allow a ClassLoader to be specified when locating a provider. As with installed providers, the provider classes are identified by placing the provider configuration file in the resource directory META-INF/services.
If a thread initiates the loading of the installed file system providers and another thread invokes a method that also attempts to load the providers then the method will block until the loading completes.
Factory methods for file systems. This class defines the getDefault method to get the default file system and factory methods to construct other types of file systems. The first invocation of any of the methods defined by this class causes the default provider to be loaded. The default provider, identified by the URI scheme "file", creates the FileSystem that provides access to the file systems accessible to the Java virtual machine. If the process of loading or initializing the default provider fails then an unspecified error is thrown. The first invocation of the installedProviders method, by way of invoking any of the newFileSystem methods defined by this class, locates and loads all installed file system providers. Installed providers are loaded using the service-provider loading facility defined by the ServiceLoader class. Installed providers are loaded using the system class loader. If the system class loader cannot be found then the extension class loader is used; if there is no extension class loader then the bootstrap class loader is used. Providers are typically installed by placing them in a JAR file on the application class path or in the extension directory, the JAR file contains a provider-configuration file named java.nio.file.spi.FileSystemProvider in the resource directory META-INF/services, and the file lists one or more fully-qualified names of concrete subclass of FileSystemProvider that have a zero argument constructor. The ordering that installed providers are located is implementation specific. If a provider is instantiated and its getScheme returns the same URI scheme of a provider that was previously instantiated then the most recently instantiated duplicate is discarded. URI schemes are compared without regard to case. During construction a provider may safely access files associated with the default provider but care needs to be taken to avoid circular loading of other installed providers. If circular loading of installed providers is detected then an unspecified error is thrown. This class also defines factory methods that allow a ClassLoader to be specified when locating a provider. As with installed providers, the provider classes are identified by placing the provider configuration file in the resource directory META-INF/services. If a thread initiates the loading of the installed file system providers and another thread invokes a method that also attempts to load the providers then the method will block until the loading completes.
A visitor of files. An implementation of this interface is provided to the Files.walkFileTree methods to visit each file in a file tree.
Usage Examples: Suppose we want to delete a file tree. In that case, each directory should be deleted after the entries in the directory are deleted.
Path start = ...
Files.walkFileTree(start, new SimpleFileVisitor<Path>() {
@Override
public FileVisitResult visitFile(Path file, BasicFileAttributes attrs)
throws IOException
{
Files.delete(file);
return FileVisitResult.CONTINUE;
}
@Override
public FileVisitResult postVisitDirectory(Path dir, IOException e)
throws IOException
{
if (e == null) {
Files.delete(dir);
return FileVisitResult.CONTINUE;
} else {
// directory iteration failed
throw e;
}
}
});
Furthermore, suppose we want to copy a file tree to a target location. In that case, symbolic links should be followed and the target directory should be created before the entries in the directory are copied.
final Path source = ...
final Path target = ...
Files.walkFileTree(source, EnumSet.of(FileVisitOption.FOLLOW_LINKS), Integer.MAX_VALUE,
new SimpleFileVisitor<Path>() {
@Override
public FileVisitResult preVisitDirectory(Path dir, BasicFileAttributes attrs)
throws IOException
{
Path targetdir = target.resolve(source.relativize(dir));
try {
Files.copy(dir, targetdir);
} catch (FileAlreadyExistsException e) {
if (!Files.isDirectory(targetdir))
throw e;
}
return CONTINUE;
}
@Override
public FileVisitResult visitFile(Path file, BasicFileAttributes attrs)
throws IOException
{
Files.copy(file, target.resolve(source.relativize(file)));
return CONTINUE;
}
});
A visitor of files. An implementation of this interface is provided to the Files.walkFileTree methods to visit each file in a file tree. Usage Examples: Suppose we want to delete a file tree. In that case, each directory should be deleted after the entries in the directory are deleted. Path start = ... Files.walkFileTree(start, new SimpleFileVisitor<Path>() { @Override public FileVisitResult visitFile(Path file, BasicFileAttributes attrs) throws IOException { Files.delete(file); return FileVisitResult.CONTINUE; } @Override public FileVisitResult postVisitDirectory(Path dir, IOException e) throws IOException { if (e == null) { Files.delete(dir); return FileVisitResult.CONTINUE; } else { // directory iteration failed throw e; } } }); Furthermore, suppose we want to copy a file tree to a target location. In that case, symbolic links should be followed and the target directory should be created before the entries in the directory are copied. final Path source = ... final Path target = ... Files.walkFileTree(source, EnumSet.of(FileVisitOption.FOLLOW_LINKS), Integer.MAX_VALUE, new SimpleFileVisitor<Path>() { @Override public FileVisitResult preVisitDirectory(Path dir, BasicFileAttributes attrs) throws IOException { Path targetdir = target.resolve(source.relativize(dir)); try { Files.copy(dir, targetdir); } catch (FileAlreadyExistsException e) { if (!Files.isDirectory(targetdir)) throw e; } return CONTINUE; } @Override public FileVisitResult visitFile(Path file, BasicFileAttributes attrs) throws IOException { Files.copy(file, target.resolve(source.relativize(file))); return CONTINUE; } });
Unchecked exception thrown when path string cannot be converted into a Path because the path string contains invalid characters, or the path string is invalid for other file system specific reasons.
Unchecked exception thrown when path string cannot be converted into a Path because the path string contains invalid characters, or the path string is invalid for other file system specific reasons.
The Permission class for link creation operations.
The following table provides a summary description of what the permission allows, and discusses the risks of granting code the permission.
Permission Target Name What the Permission Allows Risks of Allowing this Permission
hard Ability to add an existing file to a directory. This is sometimes known as creating a link, or hard link. Extreme care should be taken when granting this permission. It allows linking to any file or directory in the file system thus allowing the attacker access to all files.
symbolic Ability to create symbolic links. Extreme care should be taken when granting this permission. It allows linking to any file or directory in the file system thus allowing the attacker to access to all files.
The Permission class for link creation operations. The following table provides a summary description of what the permission allows, and discusses the risks of granting code the permission. Permission Target Name What the Permission Allows Risks of Allowing this Permission hard Ability to add an existing file to a directory. This is sometimes known as creating a link, or hard link. Extreme care should be taken when granting this permission. It allows linking to any file or directory in the file system thus allowing the attacker access to all files. symbolic Ability to create symbolic links. Extreme care should be taken when granting this permission. It allows linking to any file or directory in the file system thus allowing the attacker to access to all files.
Checked exception thrown when an attempt is made to access a file that does not exist.
Checked exception thrown when an attempt is made to access a file that does not exist.
Checked exception thrown when a file system operation, intended for a directory, fails because the file is not a directory.
Checked exception thrown when a file system operation, intended for a directory, fails because the file is not a directory.
Checked exception thrown when a file system operation fails because a file is not a symbolic link.
Checked exception thrown when a file system operation fails because a file is not a symbolic link.
An object that configures how to open or create a file.
Objects of this type are used by methods such as newOutputStream, newByteChannel, FileChannel.open, and AsynchronousFileChannel.open when opening or creating a file.
The StandardOpenOption enumeration type defines the standard options.
An object that configures how to open or create a file. Objects of this type are used by methods such as newOutputStream, newByteChannel, FileChannel.open, and AsynchronousFileChannel.open when opening or creating a file. The StandardOpenOption enumeration type defines the standard options.
No vars found in this namespace.
An object that may be used to locate a file in a file system. It will typically represent a system dependent file path.
A Path represents a path that is hierarchical and composed of a sequence of directory and file name elements separated by a special separator or delimiter. A root component, that identifies a file system hierarchy, may also be present. The name element that is farthest from the root of the directory hierarchy is the name of a file or directory. The other name elements are directory names. A Path can represent a root, a root and a sequence of names, or simply one or more name elements. A Path is considered to be an empty path if it consists solely of one name element that is empty. Accessing a file using an empty path is equivalent to accessing the default directory of the file system. Path defines the getFileName, getParent, getRoot, and subpath methods to access the path components or a subsequence of its name elements.
In addition to accessing the components of a path, a Path also defines the resolve and resolveSibling methods to combine paths. The relativize method that can be used to construct a relative path between two paths. Paths can be compared, and tested against each other using the startsWith and endsWith methods.
This interface extends Watchable interface so that a directory located by a path can be registered with a WatchService and entries in the directory watched.
WARNING: This interface is only intended to be implemented by those developing custom file system implementations. Methods may be added to this interface in future releases.
Accessing Files Paths may be used with the Files class to operate on files, directories, and other types of files. For example, suppose we want a BufferedReader to read text from a file "access.log". The file is located in a directory "logs" relative to the current working directory and is UTF-8 encoded.
Path path = FileSystems.getDefault().getPath("logs", "access.log");
BufferedReader reader = Files.newBufferedReader(path, StandardCharsets.UTF_8);
Interoperability Paths associated with the default provider are generally interoperable with the java.io.File class. Paths created by other providers are unlikely to be interoperable with the abstract path names represented by java.io.File. The toPath method may be used to obtain a Path from the abstract path name represented by a java.io.File object. The resulting Path can be used to operate on the same file as the java.io.File object. In addition, the toFile method is useful to construct a File from the String representation of a Path.
Concurrency Implementations of this interface are immutable and safe for use by multiple concurrent threads.
An object that may be used to locate a file in a file system. It will typically represent a system dependent file path. A Path represents a path that is hierarchical and composed of a sequence of directory and file name elements separated by a special separator or delimiter. A root component, that identifies a file system hierarchy, may also be present. The name element that is farthest from the root of the directory hierarchy is the name of a file or directory. The other name elements are directory names. A Path can represent a root, a root and a sequence of names, or simply one or more name elements. A Path is considered to be an empty path if it consists solely of one name element that is empty. Accessing a file using an empty path is equivalent to accessing the default directory of the file system. Path defines the getFileName, getParent, getRoot, and subpath methods to access the path components or a subsequence of its name elements. In addition to accessing the components of a path, a Path also defines the resolve and resolveSibling methods to combine paths. The relativize method that can be used to construct a relative path between two paths. Paths can be compared, and tested against each other using the startsWith and endsWith methods. This interface extends Watchable interface so that a directory located by a path can be registered with a WatchService and entries in the directory watched. WARNING: This interface is only intended to be implemented by those developing custom file system implementations. Methods may be added to this interface in future releases. Accessing Files Paths may be used with the Files class to operate on files, directories, and other types of files. For example, suppose we want a BufferedReader to read text from a file "access.log". The file is located in a directory "logs" relative to the current working directory and is UTF-8 encoded. Path path = FileSystems.getDefault().getPath("logs", "access.log"); BufferedReader reader = Files.newBufferedReader(path, StandardCharsets.UTF_8); Interoperability Paths associated with the default provider are generally interoperable with the java.io.File class. Paths created by other providers are unlikely to be interoperable with the abstract path names represented by java.io.File. The toPath method may be used to obtain a Path from the abstract path name represented by a java.io.File object. The resulting Path can be used to operate on the same file as the java.io.File object. In addition, the toFile method is useful to construct a File from the String representation of a Path. Concurrency Implementations of this interface are immutable and safe for use by multiple concurrent threads.
An interface that is implemented by objects that perform match operations on paths.
An interface that is implemented by objects that perform match operations on paths.
This class consists exclusively of static methods that return a Path by converting a path string or URI.
This class consists exclusively of static methods that return a Path by converting a path string or URI.
Unchecked exception thrown when an attempt is made to invoke a method on an object created by one file system provider with a parameter created by a different file system provider.
Unchecked exception thrown when an attempt is made to invoke a method on an object created by one file system provider with a parameter created by a different file system provider.
Runtime exception thrown when a provider of the required type cannot be found.
Runtime exception thrown when a provider of the required type cannot be found.
Unchecked exception thrown when an attempt is made to update an object associated with a read-only FileSystem.
Unchecked exception thrown when an attempt is made to update an object associated with a read-only FileSystem.
A DirectoryStream that defines operations on files that are located relative to an open directory. A SecureDirectoryStream is intended for use by sophisticated or security sensitive applications requiring to traverse file trees or otherwise operate on directories in a race-free manner. Race conditions can arise when a sequence of file operations cannot be carried out in isolation. Each of the file operations defined by this interface specify a relative path. All access to the file is relative to the open directory irrespective of if the directory is moved or replaced by an attacker while the directory is open. A SecureDirectoryStream may also be used as a virtual working directory.
A SecureDirectoryStream requires corresponding support from the underlying operating system. Where an implementation supports this features then the DirectoryStream returned by the newDirectoryStream method will be a SecureDirectoryStream and must be cast to that type in order to invoke the methods defined by this interface.
In the case of the default provider, and a security manager is set, then the permission checks are performed using the path obtained by resolving the given relative path against the original path of the directory (irrespective of if the directory is moved since it was opened).
A DirectoryStream that defines operations on files that are located relative to an open directory. A SecureDirectoryStream is intended for use by sophisticated or security sensitive applications requiring to traverse file trees or otherwise operate on directories in a race-free manner. Race conditions can arise when a sequence of file operations cannot be carried out in isolation. Each of the file operations defined by this interface specify a relative path. All access to the file is relative to the open directory irrespective of if the directory is moved or replaced by an attacker while the directory is open. A SecureDirectoryStream may also be used as a virtual working directory. A SecureDirectoryStream requires corresponding support from the underlying operating system. Where an implementation supports this features then the DirectoryStream returned by the newDirectoryStream method will be a SecureDirectoryStream and must be cast to that type in order to invoke the methods defined by this interface. In the case of the default provider, and a security manager is set, then the permission checks are performed using the path obtained by resolving the given relative path against the original path of the directory (irrespective of if the directory is moved since it was opened).
A simple visitor of files with default behavior to visit all files and to re-throw I/O errors.
Methods in this class may be overridden subject to their general contract.
A simple visitor of files with default behavior to visit all files and to re-throw I/O errors. Methods in this class may be overridden subject to their general contract.
No vars found in this namespace.
Service-provider class for file systems. The methods defined by the Files class will typically delegate to an instance of this class.
A file system provider is a concrete implementation of this class that implements the abstract methods defined by this class. A provider is identified by a URI scheme. The default provider is identified by the URI scheme "file". It creates the FileSystem that provides access to the file systems accessible to the Java virtual machine. The FileSystems class defines how file system providers are located and loaded. The default provider is typically a system-default provider but may be overridden if the system property java.nio.file.spi.DefaultFileSystemProvider is set. In that case, the provider has a one argument constructor whose formal parameter type is FileSystemProvider. All other providers have a zero argument constructor that initializes the provider.
A provider is a factory for one or more FileSystem instances. Each file system is identified by a URI where the URI's scheme matches the provider's scheme. The default file system, for example, is identified by the URI "file:///". A memory-based file system, for example, may be identified by a URI such as "memory:///?name=logfs". The newFileSystem method may be used to create a file system, and the getFileSystem method may be used to obtain a reference to an existing file system created by the provider. Where a provider is the factory for a single file system then it is provider dependent if the file system is created when the provider is initialized, or later when the newFileSystem method is invoked. In the case of the default provider, the FileSystem is created when the provider is initialized.
All of the methods in this class are safe for use by multiple concurrent threads.
Service-provider class for file systems. The methods defined by the Files class will typically delegate to an instance of this class. A file system provider is a concrete implementation of this class that implements the abstract methods defined by this class. A provider is identified by a URI scheme. The default provider is identified by the URI scheme "file". It creates the FileSystem that provides access to the file systems accessible to the Java virtual machine. The FileSystems class defines how file system providers are located and loaded. The default provider is typically a system-default provider but may be overridden if the system property java.nio.file.spi.DefaultFileSystemProvider is set. In that case, the provider has a one argument constructor whose formal parameter type is FileSystemProvider. All other providers have a zero argument constructor that initializes the provider. A provider is a factory for one or more FileSystem instances. Each file system is identified by a URI where the URI's scheme matches the provider's scheme. The default file system, for example, is identified by the URI "file:///". A memory-based file system, for example, may be identified by a URI such as "memory:///?name=logfs". The newFileSystem method may be used to create a file system, and the getFileSystem method may be used to obtain a reference to an existing file system created by the provider. Where a provider is the factory for a single file system then it is provider dependent if the file system is created when the provider is initialized, or later when the newFileSystem method is invoked. In the case of the default provider, the FileSystem is created when the provider is initialized. All of the methods in this class are safe for use by multiple concurrent threads.
A file type detector for probing a file to guess its file type.
A file type detector is a concrete implementation of this class, has a zero-argument constructor, and implements the abstract methods specified below.
The means by which a file type detector determines the file type is highly implementation specific. A simple implementation might examine the file extension (a convention used in some platforms) and map it to a file type. In other cases, the file type may be stored as a file attribute or the bytes in a file may be examined to guess its file type.
A file type detector for probing a file to guess its file type. A file type detector is a concrete implementation of this class, has a zero-argument constructor, and implements the abstract methods specified below. The means by which a file type detector determines the file type is highly implementation specific. A simple implementation might examine the file extension (a convention used in some platforms) and map it to a file type. In other cases, the file type may be stored as a file attribute or the bytes in a file may be examined to guess its file type.
Defines the standard event kinds.
Defines the standard event kinds.
An object that may be registered with a watch service so that it can be watched for changes and events.
This interface defines the register method to register the object with a WatchService returning a WatchKey to represent the registration. An object may be registered with more than one watch service. Registration with a watch service is cancelled by invoking the key's cancel method.
An object that may be registered with a watch service so that it can be watched for changes and events. This interface defines the register method to register the object with a WatchService returning a WatchKey to represent the registration. An object may be registered with more than one watch service. Registration with a watch service is cancelled by invoking the key's cancel method.
An event or a repeated event for an object that is registered with a WatchService.
An event is classified by its kind and has a count to indicate the number of times that the event has been observed. This allows for efficient representation of repeated events. The context method returns any context associated with the event. In the case of a repeated event then the context is the same for all events.
Watch events are immutable and safe for use by multiple concurrent threads.
An event or a repeated event for an object that is registered with a WatchService. An event is classified by its kind and has a count to indicate the number of times that the event has been observed. This allows for efficient representation of repeated events. The context method returns any context associated with the event. In the case of a repeated event then the context is the same for all events. Watch events are immutable and safe for use by multiple concurrent threads.
An event kind, for the purposes of identification.
An event kind, for the purposes of identification.
An event modifier that qualifies how a Watchable is registered with a WatchService.
This release does not define any standard modifiers.
An event modifier that qualifies how a Watchable is registered with a WatchService. This release does not define any standard modifiers.
A token representing the registration of a watchable object with a WatchService.
A watch key is created when a watchable object is registered with a watch service. The key remains valid until:
It is cancelled, explicitly, by invoking its cancel method, or Cancelled implicitly, because the object is no longer accessible, or By closing the watch service.
A watch key has a state. When initially created the key is said to be ready. When an event is detected then the key is signalled and queued so that it can be retrieved by invoking the watch service's poll or take methods. Once signalled, a key remains in this state until its reset method is invoked to return the key to the ready state. Events detected while the key is in the signalled state are queued but do not cause the key to be re-queued for retrieval from the watch service. Events are retrieved by invoking the key's pollEvents method. This method retrieves and removes all events accumulated for the object. When initially created, a watch key has no pending events. Typically events are retrieved when the key is in the signalled state leading to the following idiom:
for (;;) {
// retrieve key
WatchKey key = watcher.take();
// process events
for (WatchEvent<?> event: key.pollEvents()) {
:
}
// reset the key
boolean valid = key.reset();
if (!valid) {
// object no longer registered
}
}
Watch keys are safe for use by multiple concurrent threads. Where there are several threads retrieving signalled keys from a watch service then care should be taken to ensure that the reset method is only invoked after the events for the object have been processed. This ensures that one thread is processing the events for an object at any time.
A token representing the registration of a watchable object with a WatchService. A watch key is created when a watchable object is registered with a watch service. The key remains valid until: It is cancelled, explicitly, by invoking its cancel method, or Cancelled implicitly, because the object is no longer accessible, or By closing the watch service. A watch key has a state. When initially created the key is said to be ready. When an event is detected then the key is signalled and queued so that it can be retrieved by invoking the watch service's poll or take methods. Once signalled, a key remains in this state until its reset method is invoked to return the key to the ready state. Events detected while the key is in the signalled state are queued but do not cause the key to be re-queued for retrieval from the watch service. Events are retrieved by invoking the key's pollEvents method. This method retrieves and removes all events accumulated for the object. When initially created, a watch key has no pending events. Typically events are retrieved when the key is in the signalled state leading to the following idiom: for (;;) { // retrieve key WatchKey key = watcher.take(); // process events for (WatchEvent<?> event: key.pollEvents()) { : } // reset the key boolean valid = key.reset(); if (!valid) { // object no longer registered } } Watch keys are safe for use by multiple concurrent threads. Where there are several threads retrieving signalled keys from a watch service then care should be taken to ensure that the reset method is only invoked after the events for the object have been processed. This ensures that one thread is processing the events for an object at any time.
A watch service that watches registered objects for changes and events. For example a file manager may use a watch service to monitor a directory for changes so that it can update its display of the list of files when files are created or deleted.
A Watchable object is registered with a watch service by invoking its register method, returning a WatchKey to represent the registration. When an event for an object is detected the key is signalled, and if not currently signalled, it is queued to the watch service so that it can be retrieved by consumers that invoke the poll or take methods to retrieve keys and process events. Once the events have been processed the consumer invokes the key's reset method to reset the key which allows the key to be signalled and re-queued with further events.
Registration with a watch service is cancelled by invoking the key's cancel method. A key that is queued at the time that it is cancelled remains in the queue until it is retrieved. Depending on the object, a key may be cancelled automatically. For example, suppose a directory is watched and the watch service detects that it has been deleted or its file system is no longer accessible. When a key is cancelled in this manner it is signalled and queued, if not currently signalled. To ensure that the consumer is notified the return value from the reset method indicates if the key is valid.
A watch service is safe for use by multiple concurrent consumers. To ensure that only one consumer processes the events for a particular object at any time then care should be taken to ensure that the key's reset method is only invoked after its events have been processed. The close method may be invoked at any time to close the service causing any threads waiting to retrieve keys, to throw ClosedWatchServiceException.
File systems may report events faster than they can be retrieved or processed and an implementation may impose an unspecified limit on the number of events that it may accumulate. Where an implementation knowingly discards events then it arranges for the key's pollEvents method to return an element with an event type of OVERFLOW. This event can be used by the consumer as a trigger to re-examine the state of the object.
When an event is reported to indicate that a file in a watched directory has been modified then there is no guarantee that the program (or programs) that have modified the file have completed. Care should be taken to coordinate access with other programs that may be updating the file. The FileChannel class defines methods to lock regions of a file against access by other programs.
Platform dependencies
The implementation that observes events from the file system is intended to map directly on to the native file event notification facility where available, or to use a primitive mechanism, such as polling, when a native facility is not available. Consequently, many of the details on how events are detected, their timeliness, and whether their ordering is preserved are highly implementation specific. For example, when a file in a watched directory is modified then it may result in a single ENTRY_MODIFY event in some implementations but several events in other implementations. Short-lived files (meaning files that are deleted very quickly after they are created) may not be detected by primitive implementations that periodically poll the file system to detect changes.
If a watched file is not located on a local storage device then it is implementation specific if changes to the file can be detected. In particular, it is not required that changes to files carried out on remote systems be detected.
A watch service that watches registered objects for changes and events. For example a file manager may use a watch service to monitor a directory for changes so that it can update its display of the list of files when files are created or deleted. A Watchable object is registered with a watch service by invoking its register method, returning a WatchKey to represent the registration. When an event for an object is detected the key is signalled, and if not currently signalled, it is queued to the watch service so that it can be retrieved by consumers that invoke the poll or take methods to retrieve keys and process events. Once the events have been processed the consumer invokes the key's reset method to reset the key which allows the key to be signalled and re-queued with further events. Registration with a watch service is cancelled by invoking the key's cancel method. A key that is queued at the time that it is cancelled remains in the queue until it is retrieved. Depending on the object, a key may be cancelled automatically. For example, suppose a directory is watched and the watch service detects that it has been deleted or its file system is no longer accessible. When a key is cancelled in this manner it is signalled and queued, if not currently signalled. To ensure that the consumer is notified the return value from the reset method indicates if the key is valid. A watch service is safe for use by multiple concurrent consumers. To ensure that only one consumer processes the events for a particular object at any time then care should be taken to ensure that the key's reset method is only invoked after its events have been processed. The close method may be invoked at any time to close the service causing any threads waiting to retrieve keys, to throw ClosedWatchServiceException. File systems may report events faster than they can be retrieved or processed and an implementation may impose an unspecified limit on the number of events that it may accumulate. Where an implementation knowingly discards events then it arranges for the key's pollEvents method to return an element with an event type of OVERFLOW. This event can be used by the consumer as a trigger to re-examine the state of the object. When an event is reported to indicate that a file in a watched directory has been modified then there is no guarantee that the program (or programs) that have modified the file have completed. Care should be taken to coordinate access with other programs that may be updating the file. The FileChannel class defines methods to lock regions of a file against access by other programs. Platform dependencies The implementation that observes events from the file system is intended to map directly on to the native file event notification facility where available, or to use a primitive mechanism, such as polling, when a native facility is not available. Consequently, many of the details on how events are detected, their timeliness, and whether their ordering is preserved are highly implementation specific. For example, when a file in a watched directory is modified then it may result in a single ENTRY_MODIFY event in some implementations but several events in other implementations. Short-lived files (meaning files that are deleted very quickly after they are created) may not be detected by primitive implementations that periodically poll the file system to detect changes. If a watched file is not located on a local storage device then it is implementation specific if changes to the file can be detected. In particular, it is not required that changes to files carried out on remote systems be detected.
cljdoc is a website building & hosting documentation for Clojure/Script libraries
× close