Introduction to the Java NIO2 File API

1. Overview

In this article, we’re going to focus on the new I/O APIs in the Java Platform – NIO2 – to do basic file manipulation.

File APIs in NIO2 constitute one of the major new functional areas of the Java Platform that shipped with Java 7, specifically a subset of the new file system API alongside Path APIs .

2. Setup

Setting up your project to use File APIs is just a matter of making this import:

import java.nio.file.*;

Since the code samples in this article will probably be running in different environments, let’s get a handle on the home directory of the user, which will be valid across all operating systems:

private static String HOME = System.getProperty("user.home");

The Files class is one of the primary entry points of the java.nio.file package. This class offers a rich set of APIs for reading, writing, and manipulating files and directories. The Files class methods work on instances of Path objects.

3. Checking a File or Directory

We can have a Path instance representing a file or a directory on the file system. Whether that file or directory it’s pointing to exists or not, is accessible or not can be confirmed by a file operation.

For the sake of simplicity, whenever we use the term file, we will be referring to both files and directories unless stated explicitly otherwise.

To check if a file exists, we use the exists API:

@Test
public void givenExistentPath_whenConfirmsFileExists_thenCorrect() {
    Path p = Paths.get(HOME);

    assertTrue(Files.exists(p));
}

To check that a file does not exist, we use the notExists API:

@Test
public void givenNonexistentPath_whenConfirmsFileNotExists_thenCorrect() {
    Path p = Paths.get(HOME + "/inexistent_file.txt");

    assertTrue(Files.notExists(p));
}

We can also check if a file is a regular file like myfile.txt or is just a directory, we use the isRegularFile API:

@Test
public void givenDirPath_whenConfirmsNotRegularFile_thenCorrect() {
    Path p = Paths.get(HOME);

    assertFalse(Files.isRegularFile(p));
}

There are also static methods to check for file permissions. To check if a file is readable, we use the isReadable API:

@Test
public void givenExistentDirPath_whenConfirmsReadable_thenCorrect() {
    Path p = Paths.get(HOME);

    assertTrue(Files.isReadable(p));
}

To check if it is writable, we use the isWritable API:

@Test
public void givenExistentDirPath_whenConfirmsWritable_thenCorrect() {
    Path p = Paths.get(HOME);

    assertTrue(Files.isWritable(p));
}

Similarly, to check if it is executable:

@Test
public void givenExistentDirPath_whenConfirmsExecutable_thenCorrect() {
    Path p = Paths.get(HOME);
    assertTrue(Files.isExecutable(p));
}

When we have two paths, we can check if they both point to the same file on the underlying file system:

@Test
public void givenSameFilePaths_whenConfirmsIsSame_thenCorrect() {
    Path p1 = Paths.get(HOME);
    Path p2 = Paths.get(HOME);

    assertTrue(Files.isSameFile(p1, p2));
}

4. Creating Files

The file system API provides single line operations for creating files. To create a regular file, we use the createFile API and pass to it a Path object representing the file we want to create.

All the name elements in the path must exist, apart from the file name, otherwise, we will get an IOException:

@Test
public void givenFilePath_whenCreatesNewFile_thenCorrect() {
    String fileName = "myfile_" + UUID.randomUUID().toString() + ".txt";
    Path p = Paths.get(HOME + "/" + fileName);
    assertFalse(Files.exists(p));

    Files.createFile(p);

    assertTrue(Files.exists(p));
}

In the above test, when we first check the path, it is inexistent, then after the createFile operation, it is found to be existent.

To create a directory, we use the createDirectory API:

@Test
public void givenDirPath_whenCreatesNewDir_thenCorrect() {
    String dirName = "myDir_" + UUID.randomUUID().toString();
    Path p = Paths.get(HOME + "/" + dirName);
    assertFalse(Files.exists(p));

    Files.createDirectory(p);

    assertTrue(Files.exists(p));
    assertFalse(Files.isRegularFile(p));
    assertTrue(Files.isDirectory(p));
}

This operation requires that all name elements in the path exist, if not, we also get an IOException:

@Test(expected = NoSuchFileException.class)
public void givenDirPath_whenFailsToCreateRecursively_thenCorrect() {
    String dirName = "myDir_" + UUID.randomUUID().toString() + "/subdir";
    Path p = Paths.get(HOME + "/" + dirName);
    assertFalse(Files.exists(p));

    Files.createDirectory(p);
}

However, if we desire to create a hierarchy of directories with a single call, we use the createDirectories method. Unlike the previous operation, when it encounters any missing name elements in the path, it does not throw an IOException, it creates them recursively leading up to the last element:

@Test
public void givenDirPath_whenCreatesRecursively_thenCorrect() {
    Path dir = Paths.get(
      HOME + "/myDir_" + UUID.randomUUID().toString());
    Path subdir = dir.resolve("subdir");
    assertFalse(Files.exists(dir));
    assertFalse(Files.exists(subdir));

    Files.createDirectories(subdir);

    assertTrue(Files.exists(dir));
    assertTrue(Files.exists(subdir));
}

5. Creating Temporary Files

Many applications create a trail of temporary files in the file system as they run. As a result, most file systems have a dedicated directory to store temporary files generated by such applications.

The new file system API provides specific operations for this purpose. The createTempFile API performs this operation. It takes a path object, a file prefix, and a file suffix:

@Test
public void givenFilePath_whenCreatesTempFile_thenCorrect() {
    String prefix = "log_";
    String suffix = ".txt";
    Path p = Paths.get(HOME + "/");

    Files.createTempFile(p, prefix, suffix);
        
    assertTrue(Files.exists(p));
}

These parameters are sufficient for requirements that need this operation. However, if you need to specify specific attributes of the file, there is a fourth variable arguments parameter.

The above test creates a temporary file in the HOME directory, pre-pending and appending the provided prefix and suffix strings respectively. We will end up with a file name like log_8821081429012075286.txt. The long numeric string is system generated.

However, if we don’t provide a prefix and a suffix, then the file name will only include the long numeric string and a default .tmp extension:

@Test
public void givenPath_whenCreatesTempFileWithDefaults_thenCorrect() {
    Path p = Paths.get(HOME + "/");

    Files.createTempFile(p, null, null);
        
    assertTrue(Files.exists(p));
}

The above operation creates a file with a name like 8600179353689423985.tmp.

Finally, if we provide neither path, prefix nor suffix, then the operation will use defaults throughout. The default location of the created file will be the file system provided temporary-file directory:

@Test
public void givenNoFilePath_whenCreatesTempFileInTempDir_thenCorrect() {
    Path p = Files.createTempFile(null, null);

    assertTrue(Files.exists(p));
}

On windows, this will default to something like C:\Users\user\AppData\Local\Temp\6100927974988978748.tmp.

All the above operations can be adapted to create directories rather than regular files by using createTempDirectory instead of createTempFile.

6. Deleting a File

To delete a file, we use the delete API. For clarity purpose, the following test first ensures that the file does not already exist, then creates it and confirms that it now exists and finally deletes it and confirms that it’s no longer existent:

@Test
public void givenPath_whenDeletes_thenCorrect() {
    Path p = Paths.get(HOME + "/fileToDelete.txt");
    assertFalse(Files.exists(p));
    Files.createFile(p);
    assertTrue(Files.exists(p));

    Files.delete(p);

    assertFalse(Files.exists(p));
}

However, if a file is not existent in the file system, the delete operation will fail with an IOException:

@Test(expected = NoSuchFileException.class)
public void givenInexistentFile_whenDeleteFails_thenCorrect() {
    Path p = Paths.get(HOME + "/inexistentFile.txt");
    assertFalse(Files.exists(p));

    Files.delete(p);
}

We can avoid this scenario by using deleteIfExists which fail silently in case the file does not exist. This is important when multiple threads are performing this operation and we don’t want a failure message simply because a thread performed the operation earlier than the current thread which has failed:

@Test
public void givenInexistentFile_whenDeleteIfExistsWorks_thenCorrect() {
    Path p = Paths.get(HOME + "/inexistentFile.txt");
    assertFalse(Files.exists(p));

    Files.deleteIfExists(p);
}

When dealing with directories and not regular files, we should remember that the delete operation does not work recursively by default. So if a directory is not empty it will fail with an IOException:

@Test(expected = DirectoryNotEmptyException.class)
public void givenPath_whenFailsToDeleteNonEmptyDir_thenCorrect() {
    Path dir = Paths.get(
      HOME + "/emptyDir" + UUID.randomUUID().toString());
    Files.createDirectory(dir);
    assertTrue(Files.exists(dir));

    Path file = dir.resolve("file.txt");
    Files.createFile(file);

    Files.delete(dir);

    assertTrue(Files.exists(dir));
}

7. Copying Files

You can copy a file or directory by using the copy API:

@Test
public void givenFilePath_whenCopiesToNewLocation_thenCorrect() {
    Path dir1 = Paths.get(
      HOME + "/firstdir_" + UUID.randomUUID().toString());
    Path dir2 = Paths.get(
      HOME + "/otherdir_" + UUID.randomUUID().toString());

    Files.createDirectory(dir1);
    Files.createDirectory(dir2);

    Path file1 = dir1.resolve("filetocopy.txt");
    Path file2 = dir2.resolve("filetocopy.txt");

    Files.createFile(file1);

    assertTrue(Files.exists(file1));
    assertFalse(Files.exists(file2));

    Files.copy(file1, file2);

    assertTrue(Files.exists(file2));
}

The copy fails if the target file exists unless the REPLACE_EXISTING option is specified:

@Test(expected = FileAlreadyExistsException.class)
public void givenPath_whenCopyFailsDueToExistingFile_thenCorrect() {
    Path dir1 = Paths.get(
      HOME + "/firstdir_" + UUID.randomUUID().toString());
    Path dir2 = Paths.get(
      HOME + "/otherdir_" + UUID.randomUUID().toString());

    Files.createDirectory(dir1);
    Files.createDirectory(dir2);

    Path file1 = dir1.resolve("filetocopy.txt");
    Path file2 = dir2.resolve("filetocopy.txt");

    Files.createFile(file1);
    Files.createFile(file2);

    assertTrue(Files.exists(file1));
    assertTrue(Files.exists(file2));

    Files.copy(file1, file2);

    Files.copy(file1, file2, StandardCopyOption.REPLACE_EXISTING);
}

However, when copying directories, the contents are not copied recursively. This means that if /baeldung contains /articles.db and /authors.db files, copying /baeldung to a new location will create an empty directory.

8. Moving Files

You can move a file or directory by using the move API. It is in most ways similar to the copy operation. If the copy operation is analogous to a copy and paste operation in GUI based systems, then move is analogous to a cut and paste operation:

@Test
public void givenFilePath_whenMovesToNewLocation_thenCorrect() {
    Path dir1 = Paths.get(
      HOME + "/firstdir_" + UUID.randomUUID().toString());
    Path dir2 = Paths.get(
      HOME + "/otherdir_" + UUID.randomUUID().toString());

    Files.createDirectory(dir1);
    Files.createDirectory(dir2);

    Path file1 = dir1.resolve("filetocopy.txt");
    Path file2 = dir2.resolve("filetocopy.txt");
    Files.createFile(file1);

    assertTrue(Files.exists(file1));
    assertFalse(Files.exists(file2));

    Files.move(file1, file2);

    assertTrue(Files.exists(file2));
    assertFalse(Files.exists(file1));
}

The move operation fails if the target file exists unless the REPLACE_EXISTING option is specified just like we did with the copy operation:

@Test(expected = FileAlreadyExistsException.class)
public void givenFilePath_whenMoveFailsDueToExistingFile_thenCorrect() {
    Path dir1 = Paths.get(
      HOME + "/firstdir_" + UUID.randomUUID().toString());
    Path dir2 = Paths.get(
      HOME + "/otherdir_" + UUID.randomUUID().toString());

    Files.createDirectory(dir1);
    Files.createDirectory(dir2);

    Path file1 = dir1.resolve("filetocopy.txt");
    Path file2 = dir2.resolve("filetocopy.txt");

    Files.createFile(file1);
    Files.createFile(file2);

    assertTrue(Files.exists(file1));
    assertTrue(Files.exists(file2));

    Files.move(file1, file2);

    Files.move(file1, file2, StandardCopyOption.REPLACE_EXISTING);

    assertTrue(Files.exists(file2));
    assertFalse(Files.exists(file1));
}

9. Conclusion

In this article, we learned about file APIs in the new file system API (NIO2) that was shipped as a part of Java 7 and saw most of the important file operations in action.

The code samples used in this article can be found in the article’s Github project.