A Guide To NIO2 File Attribute APIs

1. Overview

In this article, we are going to explore one of the advanced features of the Java 7 NIO.2 filesystem APIs – specifically file attribute APIs.

We have previously covered the File and Path APIs if you want to dig deeper into these foundational pieces first.

All the files required to handle filesystem operations are bundled up in the java.nio.file package:

import java.nio.file.*;

2. Basic File Attributes

Let’s start with a high-level view of the basic attributes common to all file systems – provided by the BasicFileAttributeView – which stores all mandatory and optional visible file attributes.

We can explore the basic attributes of the user home location on the current machine, by creating a path to HOME and getting it’s basic attribute view:

String HOME = System.getProperty("user.home");
Path home = Paths.get(HOME);
BasicFileAttributeView basicView = 
  Files.getFileAttributeView(home, BasicFileAttributeView.class);

After the above step, we can now read all the attributes of the path pointed to in one bulk operation:

BasicFileAttributes basicAttribs = basicView.readAttributes();

We are now in a position to explore different common attributes which we can actually use in our applications especially in conditional statements.

We can query for the size of the file from its basic attributes container:

@Test
public void givenPath_whenGetsFileSize_thenCorrect() {
    long size = basicAttribs.size();
    assertTrue(size > 0);
}

We can also check if it’s a directory:

@Test
public void givenPath_whenChecksIfDirectory_thenCorrect() {
    boolean isDir = basicAttribs.isDirectory();
    assertTrue(isDir);
}

Or a regular file:

@Test
public void givenPath_whenChecksIfFile_thenCorrect() {
    boolean isFile = basicAttribs.isRegularFile();
    assertFalse(isFile);
}

With Java NIO.2 we are now able to deal with symbolic links or soft links in the file system. These are files or directories which we normally call shortcuts.

To check if a file is a symbolic link:

@Test
public void givenPath_whenChecksIfSymLink_thenCorrect() {
    boolean isSymLink = basicAttribs.isSymbolicLink();
    assertFalse(isSymLink);
}

In rare cases, we can call the isOther API to check if the file belongs to none of the common categories of regular file, directory or symbolic link:

@Test
public void givenPath_whenChecksIfOther_thenCorrect() {
    boolean isOther = basicAttribs.isOther();
    assertFalse(isOther);
}

To get the time the file was created:

FileTime created = basicAttribs.creationTime();

To get the last modified time:

FileTime modified = basicAttribs.lastModifiedTime();

And to get the last access time:

FileTime accessed = basicAttribs.lastAccessTime();

All the above examples return a FileTime object. This is a more usable abstraction than a mere timestamp.

For example, we can easily compare two file times to know which event occurred before or after the other:

@Test
public void givenFileTimes_whenComparesThem_ThenCorrect() {
    FileTime created = basicAttribs.creationTime();
    FileTime modified = basicAttribs.lastModifiedTime();
    FileTime accessed = basicAttribs.lastAccessTime();

    assertTrue(0 >= created.compareTo(accessed));
    assertTrue(0 <= modified.compareTo(created));
    assertTrue(0 == created.compareTo(created));
}

The compareTo API works the same way as for other comparables in Java. It returns a negative value in case the object it’s being called on is less than the argument; in our case, creation time definitely comes before access time as in the first assertion.

In the second assertion, we get a positive integer value because a modification can only be made after a creation event. And finally, it returns 0 when the times being compared are equal.

When we have a FileTime object, we can then convert it to most other units depending on our needs; days, hours, minutes, seconds, milliseconds and so on. We do this by calling the appropriate API:

accessed.to(TimeUnit.SECONDS);
accessed.to(TimeUnit.HOURS);
accessed.toMillis();

We can as well print a human readable form of the file time by calling its toString API:

accessed.toString();

Which prints something useful in ISO time format:

2016-11-24T07:52:53.376Z

We can also change the time attributes on the view by calling its setTimes(modified, accessed, created) API. We pass in the new FileTime objects where we want to change or null where we don’t want to change.

To change the last access time one minute into the future, we would follow these steps:

FileTime newAccessTime = FileTime.fromMillis(
  basicAttribs.lastAccessTime().toMillis() + 60000);
basicView.setTimes(null, newAccessTime , null);

This change will persist in the actual file as seen from any other application running on the machine and using the file system.

3. File Space Attributes

When you open my computer on Windows, Linux or Mac, you can usually see a graphic analysis of space information about you storage drives.

Java NIO.2 makes this kind of high level functionality very easy. It interacts with the underlying file system to retrieve this information while we only have to call simple APIs.

We can use the FileStore class to inspect storage drives and obtain important information such as it’s size, how much space is used and how much is still unused.

To get a FileStore instance for the location of an arbitrary file in the file system, we use the getFileStore API of Files class:

Path file = Paths.get("file");
FileStore store = Files.getFileStore(file);

This FileStore instance specifically represents the file store where the specified file is located, not the file itself. To get total space:

long total = store.getTotalSpace();

To get used space:

long used = store.getTotalSpace() - store.getUnallocatedSpace();

We are less likely to follow this approach than the next.

More commonly, we are likely to get information about storage information about all file stores. To emulate my computer’s graphic drive space information in a program we can use FileSystem class to enumerate the file stores:

Iterable<FileStore> fileStores = FileSystems.getDefault().getFileStores();

We can then loop over the returned values and do whatever we need to do with the information, such as updating a graphical user interface:

for (FileStore fileStore : fileStores) {
    long totalSpace = fileStore.getTotalSpace();
    long unAllocated = fileStore.getUnallocatedSpace();
    long usable = fileStore.getUsableSpace();
}

Note that all the returned values are in bytes. We can convert to suitable units as well as calculating other information such as used space using basic arithmetic.

The difference between unallocated space and usable space is in accessibility to the JVM.

Usable space is the space available to the JVM while unallocated space is the available space as seen by the underlying file system. Therefore, usable space may sometimes be smaller than unallocated space.

4. File Owner Attributes

To inspect file ownership information, we use the FileOwnerAttributeView interface. It gives us a high-level view of the ownership information.

We can create a FileOwnerAttributeView object like this:

Path path = Paths.get(HOME);
FileOwnerAttributeView ownerView = Files.getFileAttributeView(
  attribPath, FileOwnerAttributeView.class);

To get the owner of the file from the above view:

UserPrincipal owner = ownerView.getOwner();

There is really nothing much we can do programmatically with the above object, apart from getting the name of the owner for some other arbitrary purpose:

String ownerName = owner.toString();

5. User Defined File Attributes

There are scenarios where the file attributes defined in the file system are not sufficient for your needs. Should you come across such a case and require to set your own attributes on a file, then the UserDefinedFileAttributeView interface will come in handy:

Path path = Paths.get("somefile");
UserDefinedFileAttributeView userDefView = Files.getFileAttributeView(
  attribPath, UserDefinedFileAttributeView.class);

To retrieve the list of user defined attributes already defined for the file represented by the above view:

List<String> attribList = userDefView.list();

To set a user-defined attribute on the file, we use the following idiom:

String name = "attrName";
String value = "attrValue";
userDefView.write(name, Charset.defaultCharset().encode(value));

When you need to access the user defined attributes, you can loop over the attribute list returned by the view and inspect them using this idiom:

ByteBuffer attrValue = ByteBuffer.allocate(userView.size(attrName));
userDefView.read(attribName, attribValue);
attrValue.flip();
String attrValue = Charset.defaultCharset().decode(attrValue).toString();

To remove a user-defined attribute from the file, we simply call the delete API of the view:

userDefView.delete(attrName);

6. Conclusion

In this article, we have explored some of the less commonly used features available in the Java 7 NIO.2 filesystem APIs, specifically file attribute APIs.

The full source code for the examples used in this article is available in the Github project.