NIO2 API

org.classpath.icedtea.java.nio.file.attribute
Class Attributes

java.lang.Object
  extended by org.classpath.icedtea.java.nio.file.attribute.Attributes

public final class Attributes
extends Object

This class consists exclusively of static methods that operate on or return the attributes of files or file stores. These methods provide for convenient use of the attribute-views defined in this package.

Since:
1.7

Method Summary
static List<AclEntry> getAcl(FileRef file)
          Reads a file's Access Control List (ACL).
static Object getAttribute(FileRef file, String attribute, LinkOption... options)
          Reads the value of a file attribute.
static UserPrincipal getOwner(FileRef file)
          Returns the owner of a file.
static Map<String,?> readAttributes(FileRef file, String attributes, LinkOption... options)
          Reads a set of file attributes as a bulk operation.
static BasicFileAttributes readBasicFileAttributes(FileRef file, LinkOption... options)
          Reads the basic file attributes of a file.
static DosFileAttributes readDosFileAttributes(FileRef file, LinkOption... options)
          Reads the DOS file attributes of a file.
static FileStoreSpaceAttributes readFileStoreSpaceAttributes(FileStore store)
          Reads the space attributes of a file store.
static PosixFileAttributes readPosixFileAttributes(FileRef file, LinkOption... options)
          Reads the POSIX file attributes of a file.
static void setAcl(FileRef file, List<AclEntry> acl)
          Updates a file's Access Control List (ACL).
static void setAttribute(FileRef file, String attribute, Object value)
          Sets the value of a file attribute.
static void setLastAccessTime(FileRef file, long lastAccessTime, TimeUnit unit)
          Updates the value of a file's last access time attribute.
static void setLastModifiedTime(FileRef file, long lastModifiedTime, TimeUnit unit)
          Updates the value of a file's last modified time attribute.
static void setOwner(FileRef file, UserPrincipal owner)
          Updates the file owner.
static void setPosixFilePermissions(FileRef file, Set<PosixFilePermission> perms)
          Sets a file's POSIX permissions.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Method Detail

setAttribute

public static void setAttribute(FileRef file,
                                String attribute,
                                Object value)
                         throws IOException
Sets the value of a file attribute.

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

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

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

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

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

Parameters:
file - A file reference that locates the file
attribute - The attribute to set
value - The attribute value
Throws:
UnsupportedOperationException - If the attribute view is not available or it does not support updating the attribute
IllegalArgumentException - If the attribute value is of the correct type but has an inappropriate value
ClassCastException - If the attribute value is not of the expected type or is a collection containing elements that are not of the expected type
IOException - If an I/O error occurs
SecurityException - In the case of the default provider, and a security manager is installed, its checkWrite method denies write access to the file. If this method is invoked to set security sensitive attributes then the security manager may be invoked to check for additional permissions.

getAttribute

public static Object getAttribute(FileRef file,
                                  String attribute,
                                  LinkOption... options)
                           throws IOException
Reads the value of a file attribute.

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

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

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

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

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

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

Parameters:
file - A file reference that locates the file
attribute - The attribute to read
options - Options indicating how symbolic links are handled
Returns:
The attribute value, or null if the attribute view is not available or it does not support reading the attribute
Throws:
IOException - If an I/O error occurs
SecurityException - In the case of the default provider, and a security manager is installed, its checkRead method denies read access to the file. If this method is invoked to read security sensitive attributes then the security manager may be invoked to check for additional permissions.

readAttributes

public static Map<String,?> readAttributes(FileRef file,
                                           String attributes,
                                           LinkOption... options)
                                    throws IOException
Reads a set of file attributes as a bulk operation.

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

[view-name:]attribute-list
where square brackets [...] delineate an optional component and the character ':' stands for itself.

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

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

The following examples demonstrate possible values for the attributes parameter:

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

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

Parameters:
file - A file reference that locates the file
attributes - The attributes to read
options - Options indicating how symbolic links are handled
Returns:
A map of the attributes returned; may be empty. The map's keys are the attribute names, its values are the attribute values
Throws:
IOException - If an I/O error occurs
SecurityException - In the case of the default provider, and a security manager is installed, its checkRead method denies read access to the file. If this method is invoked to read security sensitive attributes then the security manager may be invoke to check for additional permissions.

readBasicFileAttributes

public static BasicFileAttributes readBasicFileAttributes(FileRef file,
                                                          LinkOption... options)
                                                   throws IOException
Reads the basic file attributes of a file.

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

    boolean isSymbolicLink = Attributes.readBasicFileAttributes(file, NOFOLLOW_LINKS).isSymbolicLink();
 

It is implementation specific if all file attributes are read as an atomic operation with respect to other file system operations.

Parameters:
file - A file reference that locates the file
options - Options indicating how symbolic links are handled
Returns:
The basic file attributes
Throws:
IOException - If an I/O error occurs
SecurityException - In the case of the default provider, the security manager's checkRead method is invoked to check read access to file
See Also:
BasicFileAttributeView.readAttributes()

readPosixFileAttributes

public static PosixFileAttributes readPosixFileAttributes(FileRef file,
                                                          LinkOption... options)
                                                   throws IOException
Reads the POSIX file attributes of a file.

The file parameter locates a file that supports the PosixFileAttributeView. This file attribute view provides access to a subset 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. It is implementation specific if all file attributes are read as an atomic operation with respect to other file system operations.

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

Parameters:
file - A file reference that locates the file
options - Options indicating how symbolic links are handled
Returns:
The POSIX file attributes
Throws:
UnsupportedOperationException - If the PosixFileAttributeView is not available
IOException - If an I/O error occurs
SecurityException - In the case of the default provider, and a security manager is installed, it denies RuntimePermission("accessUserInformation") or its checkRead method denies read access to the file.
See Also:
PosixFileAttributeView.readAttributes()

readDosFileAttributes

public static DosFileAttributes readDosFileAttributes(FileRef file,
                                                      LinkOption... options)
                                               throws IOException
Reads the DOS file attributes of a file.

The file parameter locates a file that supports the DosFileAttributeView. This file attribute view provides access to legacy "DOS" attributes supported by the file systems such as File Allocation Table (FAT), commonly used in consumer devices. It is implementation specific if all file attributes are read as an atomic operation with respect to other file system operations.

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

Parameters:
file - A file reference that locates the file
options - Options indicating how symbolic links are handled
Returns:
The DOS file attributes
Throws:
UnsupportedOperationException - If the DosFileAttributeView is not available
IOException - If an I/O error occurs
SecurityException - In the case of the default provider, the security manager's checkRead method is invoked to check read access to file
See Also:
DosFileAttributeView.readAttributes()

getOwner

public static UserPrincipal getOwner(FileRef file)
                              throws IOException
Returns the owner of a file.

The file parameter locates a file that supports the FileOwnerAttributeView. This file attribute view provides access to a file attribute that is the owner of the file.

Parameters:
file - A file reference that locates the file
Returns:
A user principal representing the owner of the file
Throws:
UnsupportedOperationException - If the FileOwnerAttributeView is not available
IOException - If an I/O error occurs
SecurityException - In the case of the default provider, and a security manager is installed, it denies RuntimePermission("accessUserInformation") or its checkRead method denies read access to the file.
See Also:
FileOwnerAttributeView.getOwner()

setOwner

public static void setOwner(FileRef file,
                            UserPrincipal owner)
                     throws IOException
Updates the file owner.

The file parameter locates a file that supports the FileOwnerAttributeView. This file attribute view provides access to a file attribute that is the owner of the file.

Parameters:
file - A file reference that locates the file
owner - The new file owner
Throws:
UnsupportedOperationException - If the FileOwnerAttributeView is not available
IOException - If an I/O error occurs
SecurityException - In the case of the default provider, and a security manager is installed, it denies RuntimePermission("accessUserInformation") or its checkWrite method denies write access to the file.
See Also:
FileOwnerAttributeView.setOwner(org.classpath.icedtea.java.nio.file.attribute.UserPrincipal)

getAcl

public static List<AclEntry> getAcl(FileRef file)
                             throws IOException
Reads a file's Access Control List (ACL).

The file parameter locates a file that supports the AclFileAttributeView. This file attribute view provides access to ACLs based on the ACL model specified in RFC 3530.

Parameters:
file - A file reference that locates the file
Returns:
An ordered list of entries representing the ACL. The returned list is modifiable.
Throws:
UnsupportedOperationException - If the AclAttributeView is not available
IOException - If an I/O error occurs
SecurityException - In the case of the default provider, and a security manager is installed, it denies RuntimePermission("accessUserInformation") or its checkRead method denies read access to the file.
See Also:
AclFileAttributeView.getAcl()

setAcl

public static void setAcl(FileRef file,
                          List<AclEntry> acl)
                   throws IOException
Updates a file's Access Control List (ACL).

The file parameter locates a file that supports the AclFileAttributeView. This file attribute view provides access to ACLs based on the ACL model specified in RFC 3530.

Parameters:
file - A file reference that locates the file
acl - The new file ACL
Throws:
UnsupportedOperationException - If the AclFileAttributeView is not available
IOException - If an I/O error occurs
SecurityException - In the case of the default provider, and a security manager is installed, it denies RuntimePermission("accessUserInformation") or its checkWrite method denies write access to the file.
See Also:
AclFileAttributeView.setAcl(java.util.List)

setLastModifiedTime

public static void setLastModifiedTime(FileRef file,
                                       long lastModifiedTime,
                                       TimeUnit unit)
                                throws IOException
Updates the value of a file's last modified time attribute.

The time value is measured since the epoch (00:00:00 GMT, January 1, 1970) and is converted to the precision supported by the file system. Converting from finer to coarser granularities result in precision loss.

If the file system does not support a last modified time attribute then this method has no effect.

Parameters:
file - A file reference that locates the file
lastModifiedTime - The new last modified time, or -1L to update it to the current time
unit - A TimeUnit determining how to interpret the lastModifiedTime parameter
Throws:
IllegalArgumentException - If the lastModifiedime parameter is a negative value other than -1L
IOException - If an I/O error occurs
SecurityException - In the case of the default provider, the security manager's checkWrite method is invoked to check write access to file
See Also:
BasicFileAttributeView.setTimes(java.lang.Long, java.lang.Long, java.lang.Long, java.util.concurrent.TimeUnit)

setLastAccessTime

public static void setLastAccessTime(FileRef file,
                                     long lastAccessTime,
                                     TimeUnit unit)
                              throws IOException
Updates the value of a file's last access time attribute.

The time value is measured since the epoch (00:00:00 GMT, January 1, 1970) and is converted to the precision supported by the file system. Converting from finer to coarser granularities result in precision loss.

If the file system does not support a last access time attribute then this method has no effect.

Parameters:
lastAccessTime - The new last access time, or -1L to update it to the current time
unit - A TimeUnit determining how to interpret the lastModifiedTime parameter
Throws:
IllegalArgumentException - If the lastAccessTime parameter is a negative value other than -1L
IOException - If an I/O error occurs
SecurityException - In the case of the default provider, the security manager's checkWrite method is invoked to check write access to file
See Also:
BasicFileAttributeView.setTimes(java.lang.Long, java.lang.Long, java.lang.Long, java.util.concurrent.TimeUnit)

setPosixFilePermissions

public static void setPosixFilePermissions(FileRef file,
                                           Set<PosixFilePermission> perms)
                                    throws IOException
Sets a file's POSIX permissions.

The file parameter is a reference to an existing file. It supports the PosixFileAttributeView that provides access to file attributes commonly associated with files on file systems used by operating systems that implement the Portable Operating System Interface (POSIX) family of standards.

Parameters:
file - A file reference that locates the file
perms - The new set of permissions
Throws:
UnsupportedOperationException - If PosixFileAttributeView is not available
ClassCastException - If the sets contains elements that are not of type PosixFilePermission
IOException - If an I/O error occurs
SecurityException - In the case of the default provider, and a security manager is installed, it denies RuntimePermission("accessUserInformation") or its checkWrite method denies write access to the file.
See Also:
PosixFileAttributeView.setPermissions(java.util.Set)

readFileStoreSpaceAttributes

public static FileStoreSpaceAttributes readFileStoreSpaceAttributes(FileStore store)
                                                             throws IOException
Reads the space attributes of a file store.

The store parameter is a file store that supports the FileStoreSpaceAttributeView providing access to the space related attributes of the file store. It is implementation specific if all attributes are read as an atomic operation with respect to other file system operations.

Parameters:
store - The file store
Returns:
The file store space attributes
Throws:
UnsupportedOperationException - If the file store space attribute view is not supported
IOException - If an I/O error occurs
SecurityException - In the case of the default provider, and a security manager is installed, its checkRead method is invoked to check read access to the file used to obtain access to the file store, and in addition it checks RuntimePermission ("getFileStoreAttributes")
See Also:
FileStoreSpaceAttributeView.readAttributes()

NIO2 API

Copyright © 2007, 2011, Oracle and/or its affiliates. All rights reserved.