Invalid Java 7 API: Attributes.readAttributes()

Update: It appears JDK 7 API has drasctially changed over several iterations. The current javadoc doesn’t contain the mentioned method.

In my over a decade of Java experience, I have never found a fully documented API in Java docs which doesn’t exist even in the latest builds!

Attributes.readAttributes() is a very well documented API:

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.

With such level of detail, I was looking forward to use the API. After trying for a long time to get it to work, I finally realized it was time to peek into Java source code, specifically code for JDK 7. Astonishingly the code to implement it was absent; it was deprecated, it was just not there. In frustration, I upgraded to the latest beta version 120 of JDK 7 and yet the code is still not there! I am still scratching my head in disbelief. Is this signs of things to come with Oracle acquisition?

In case you too are looking forward to use this method, you have been warned.