Java NIO Files Directory

Introduction

In the last post, we looked at the Java NIO Files API where we learnt the Files methods that deal with creating, reading, writing, and deleting files.  In this post, we will learn about the NIO Files Directory operations i.e., directory manipulations.

I have structured this post as

• Testing if an object pointed to by a path is a directory
• Creating a directory and creating multiple directories
• Creating a temp directory
• Obtaining a Directory Stream
• Recursively traversing a directory
• Moving a directory

Note: All the Files methods throw an IOException which is common if we are working on a file or a directory. Hence, we have to either catch the IOException or make our method (that calls the Files method) throw it back since it is a checked exception (by adding a throws clause).

A Path is an object that locates a file in the file system. Look at the section on Java NIO Path as the methods in the Files class operate using a Path. 

How to check if a file is a directory

We can use the isDirectory() method of the Files class to check if the file pointed to by a Path is a directory. It returns true if the file is a directory and false otherwise.

Path directoryPath = Paths.get("/Users/JavaDeveloperCentral/data/files");
System.out.println(Files.isDirectory(directoryPath));//true

Path filePath = Paths.get("/Users/JavaDeveloperCentral/data/files/file.txt");
System.out.println(Files.isDirectory(filePath));//false

The isDirectory method accepts a var-args parameter of type LinkOption. A LinkOption has an enum instance called NOFOLLOW_LINKS. By default, if the file is symbolic link, it is followed. We can pass the LinkOption as an argument to not follow symbolic links.

System.out.println(Files.isDirectory(directoryPath, 
        LinkOption.NOFOLLOW_LINKS));

Creating a directory using NIO Files

Use Files.createDirectory() method to create a directory. The method returns the path of the newly created directory.

Path newDirectoryPath = Paths.get("/Users/JavaDeveloperCentral/data/newDirectory");

System.out.println(Files.createDirectory(newDirectoryPath));

The above will create a new folder or directory named ’newDirectory’ inside the ‘data’ directory. If the directory already exists (even if it is a file), the createDirectory() method will throw a FileAlreadyExistsException.

But we can use it to create only one new folder or directory. What do I mean by this?

Path newDirectoryPath = Paths.get("/Users/JavaDeveloperCentral/data/newDir1/newDir2");
Files.createDirectory(newDirectoryPath); //throws a NoSuchFileException

Creating all missing directories

It would be painful if we have to create the entire directory path (all non-existent parent directories) ourselves. There is a method that does this for us – the createDirectories method.
The createDirectories method will create all non-existent parent directories first.

Path newDirectoryPath = Paths.get("/Users/JavaDeveloperCentral/data/newDir1/newDir2");
Files.createDirectories(newDirectoryPath);

The above code will create a directory structure like 

..
|-- data
    |-- newDir1*
        |-- newDir2*
                
* - newly created

Note: The createDirectories method will not throw a FileAlreadyExistsException if the directory with that name already exists.

The createDirectory and the createDirectories method takes an optional FileAttribute (var-args). They are used to set the file attributes. The usage of FileAttribute is shown on the section for creating files.

Creating a temp directory

The createTempDirectory method accepts a path to a directory and a prefix, and it creates a new temp directory in the specified directory using the provided prefix to generate the name of the temp directory. It returns the Path instance of the newly created directory.

The name of the created temp directory will be of the format <prefix><some_name> where the name format of the <some_name> is implementation dependent and cannot be specified. The current implementation is to generate a random long as the directory name with the provided prefix separated by a colon i.e., like <prefix>-<some_long>. If the prefix is empty the directory name will only be the randomly generated Long (as a String).

Path directoryPath = Paths.get("/Users/JavaDeveloperCentral/data");
//Note: data directory has to exit
Path tmpDirPath = Files.createTempDirectory(directoryPath, "prefix-");
System.out.println(tmpDirPath);

This will create a temp directory inside the data directory. The returned directory’s path is like /Users/JavaDeveloperCentral/data/prefix-17664530745782273920 where the last long String is randomly generated. 

A temp directory inside the temporary-file directory

In the above createTempFile method we passed a Path directory in which we want to create a temp directory. There is another overloaded createTempFile method where we can skip providing the Path directory. In that case, it will create the temp directory inside the temporary-file directory.
The temporary-file directory path is OS specific.

System.out.println(System.getProperty("java.io.tmpdir"));

On windows, it might be `C:\temp` and in Mac it might be /var/folders/qx/045nmsxx55575_gqycvvs1480000gp/T. The exact path can change.

/*
 Creates the temp dir inside the temporary-file directory (location is OS specific).
*/
System.out.println(Files.createTempDirectory("prefix-"));

When to use createTempDirectory

The need for creating a temporary directory is when you want to write some data within a directory and you want to clean up (delete) the directory after the completing the processing. Hence, you do not care what the directory is called.

Example: A report processing application might generate multiple report files. It writes the report data to the local file system. After it is has completed generating the reports, it will upload the directory containing report files to an external store (like AWS S3). Then, it wants to delete all the report files (including the directory). The application, if it uses a temp directory created as explained above, need not worry about naming the directory. In such applications, we can use the second variation of creating a temporary directory (create a temp directory in the temporary-file directory)

But still a temporary directory removes the need for the application to provide a name. It would not be deleted automatically. 

A temporary directory is usually used along with a shutdown-hook or File.deleteOnExit() to delete the directory automatically. The deleteOnExit() will delete the file after the Virtual Machine terminates.

tmpDirPath.toFile().deleteOnExit();

For the directory to be deleted when the VM exits, the directory must be empty. This means that all the files (and folders) created inside the temp directory must also have to be deleted on exit. 

Path directoryPath = Paths.get("/Users/JavaDeveloperCentral/data");
Path tmpDirPath = Files.createTempDirectory(directoryPath, "");
System.out.println(tmpDirPath);

tmpDirPath.toFile().deleteOnExit();

Path filePath1 = Paths.get(tmpDirPath.toString() + "/file1");
filePath1.toFile().deleteOnExit();
Files.write(filePath1, List.of("something"));

Path filePath2 = Paths.get(tmpDirPath.toString() + "/file2");
filePath2.toFile().deleteOnExit();
Files.write(filePath2, List.of("something"));

Directory Stream

The newDirectory stream method opens a directory and returns a DirectoryStream. A DirectoryStream can be used to iterate over all the entries in the directory. Each entry in a DirectoryStream is a NIO Path.
Some Related posts to the Iterator

• Iterator Design Pattern
• Enumeration vs Iterator

The stream must be closed to free any resources held for the open directory. We can use a try-with-resources statement to ensure the directory stream is closed.

Let us say we have a directory structure as

..
|-- data
    |-- file1.txt
    |-- file2.txt
    |-- SomeClass.java
    |-- dir1
        |-- dir2
            |-- file1InDir2.txt
    |-- file3.txt

Path directoryPath = Paths.get("/Users/JavaDeveloperCental/data");
 
try (DirectoryStream<Path> directoryStream = Files.newDirectoryStream(directoryPath)) {
    directoryStream
            .forEach(System.out::println);
}

The above code creates a Directory Stream and iterates over them and prints each path. 

/Users/JavaDeveloperCental/data/file1.txt
/Users/JavaDeveloperCental/data/file2.txt
/Users/JavaDeveloperCental/data/SomeClass.java
/Users/JavaDeveloperCental/data/dir1
/Users/JavaDeveloperCental/data/file3.txt

Iterable<Path> directoryStream = Files.newDirectoryStream(directoryPath);
Iterator<Path> pathIterator = directoryStream.iterator();
while (pathIterator.hasNext()) {
    System.out.println(pathIterator.next());
}

Filtering with a Directory Stream

There is an overloaded newDirectoryStream method that takes a globbing pattern. Hence, it returns only the Path entries that match the String representation of the file name against the passed pattern.
The globbing pattern is specified by the getPathMatcher method. Read the javadoc of the getPathMatcher to understand the syntax of the glob pattern.

Path directoryPath = Paths.get("/Users/JavaDeveloperCental/data");
 
try (DirectoryStream<Path> directoryStream = Files.newDirectoryStream(directoryPath, "*.txt")) {
    directoryStream
            .forEach(System.out::println);
}

By specifying a glob pattern of *.txt, we filter only the text files. Running the above code for the directory structure shown above will print,

/Users/JavaDeveloperCental/data/file1.txt
/Users/JavaDeveloperCental/data/file2.txt
/Users/JavaDeveloperCental/data/file3.txt

This will not print the folder dir1 and SomeClass.java as they don’t match the glob pattern.

Filtering based on the Path instance

If we want to have a filtering condition based on the Path object, we can pass a Predicate using DirectoryStream.Filter. It has the same signature as a Java Predicate but throws an IOException.

Example: To iterate over a directory but filter only the files, we can do like

try (DirectoryStream<Path> directoryStream = Files.newDirectoryStream(directoryPath,
        path -> path.toFile().isFile())) {
    directoryStream
            .forEach(System.out::println);
}

Prints,

/Users/JavaDeveloperCental/data/file1.txt
/Users/JavaDeveloperCental/data/file2.txt
/Users/JavaDeveloperCental/data/SomeClass.java
/Users/JavaDeveloperCental/data/file3.txt

 path -> path.toFile().isFile() is a lambda of target type DirectoryStream.Filter. The entries in the iterator that match this predicate alone will be returned.

Files.Walk

The walk method returns a Stream that is lazily populated with Path by walking the file tree starting from a given Path. The file tree is traversed depth-first and hence this method can be used to traverse the directory structure recursively by visiting all the nodes (files and folders).
During the traversal, if it encounters a directory, it opens it and visits all the files in the directory. When all the entries inside a directory have been visited, the directory is closed. The file tree walk continues at the next sibling of the directory.

To ensure proper cleanup of file system resources, this must be used from with a try-with-resources construct.

It accepts a FileVisitOption argument. By default, the symbolic links are not followed. To follow symbolic links, we can pass FileVisitOption.FOLLOW_LINKS.

Path directoryPath = Paths.get("/Users/JavaDeveloperCental/data");

try(Stream<Path> pathStream = Files.walk(directoryPath)) {
    pathStream
            .forEach(System.out::println);
}

The above code starts the traversal starting at the path /Users/JavaDeveloperCental/data/ (refer to the earlier provided directory structure) and prints each path. 

/Users/JavaDeveloperCental/data/file1.txt
/Users/JavaDeveloperCental/data/file2.txt
/Users/JavaDeveloperCental/data/SomeClass.java
/Users/JavaDeveloperCental/data/dir1
/Users/JavaDeveloperCental/data/dir1/dir2
/Users/JavaDeveloperCental/data/dir1/dir2/file1InDir2.txt
/Users/JavaDeveloperCental/data/file3.txt

Path directoryPath = Paths.get("/Users/JavaDeveloperCental/data");

try(Stream<Path> pathStream = Files.walk(directoryPath, 1)) {
    pathStream
            .forEach(System.out::println);
}

/Users/JavaDeveloperCental/data/file1.txt
/Users/JavaDeveloperCental/data/file2.txt
/Users/JavaDeveloperCental/data/SomeClass.java
/Users/JavaDeveloperCental/data/dir1
/Users/JavaDeveloperCental/data/file3.txt

Moving or renaming a directory

The Files.move() method will also work for moving a directory. But it shouldn’t require moving the entries in the directory. This is true if we are moving/renaming the directory on the same FileStore.

Quoting from the javadoc of Files.move

When invoked to move a directory that is not empty then the directory is moved if it does not require moving the entries in the directory. For example, renaming a directory on the same FileStore will usually not require moving the entries in the directory. When moving a directory requires that its entries be moved then this method fails (by throwing an IOException). To move a file tree may involve copying rather than moving directories and this can be done using the copy method in conjunction with the Files.walkFileTree utility method.

Path path1 = Path.of("/Users/JavaDeveloperCental/data");
Path path2 = Path.of("/Users/JavaDeveloperCental/newData");

//Works only if on the same filestore - else use walkFileTree
Files.move(path1, path2);

Directory deletion and copying

We cannot use Files.delete() method to delete a directory. It would work only if the directory is empty. If the directory is not empty, it will throw a DirectoryNotEmptyException.

Similarly, Files.copy() method does not recursively copy all the files and folders inside a directory. It only copies and creates an empty directory at the destination.

To achieve these two functionalities, we have to use the walkFileTree method. We will learn about this in a separate post which I will put up soon.

Conclusion

This post covered the basic directory operations and manipulations using the static utility methods in the Files class.

Stay tuned for the post on walkFileTree method.

Helpful resources

• Codejava Files article
• Jenkov Java NIO Files
• https://stackoverflow.com/questions/16352326/when-does-system-getpropertyjava-io-tmpdir-return-c-temp