Java NIO Files – Part I

Introduction

The java.nio package defines interfaces and classes for operating with files and file systems. The Java NIO Files class has static utility methods that operate on files, directories and other types of files. In this post, we will learn about the Java NIO Files API. It is under the java.nio.file package.

This post will cover the NIO Files class regarding operations on Files. A separate post will be put up for operating on folders. This post is structured in the following flow.

Note that all the Files methods throw an IOException which is common if we are working on a file. Hence, we have to either catch the IOException or make the method (that calls the Files method) throw it back since it is a checked exception. This post explains the differences between a checked and an unchecked exception.

Java NIO Path

The java.nio.file’s Path class represents an object that locates a file in the file system. The APIs in the NIO Files class work using this class.

Constructing a Path

In Java 8

Use the Paths.get() static method to build a path instance.

Path path = Paths.get("/Users/JavaDeveloperCentral/data/files/file.txt");

This will create a Path object that locates the file provided as arguments. 

To avoid hard-coding the path separator (the path separator is OS/platform specific), we can pass the individual path parts to the of() method. The last argument is a var-args.

Path path = Paths.get("/Users", "JavaDeveloperCentral", "data", "files", "file.txt");

Another way to create a path is from a URI.

Path path = Paths.get(URI.create("file:///Users/JavaDeveloperCentral/data/files/file.txt"));

From Java 11 onwards

From Java 11 onwards, Paths.get is not recommended to be used. Instead, the recommendation is to use the static of() methods in the Path interface. It has the same contract as the Paths.get methods.

Path path = Path.of("/Users/JavaDeveloperCentral/data/files/file.txt");
Path path = Path.of("/Users", "JavaDeveloperCentral", "data", "files", "file.txt");
Path path = Path.of(URI.create("file:///Users/JavaDeveloperCentral/data/files/file.txt"));

java.nio.file.Path Methods

We will not go in depth to see all the methods in the Path class. I will show just a few. Refer to the Javadoc of the Path class to know more if needed.

toFile()

We can get a File instance from a Path by calling the toFile() method.

Path path = Paths.get("/Users", "JavaDeveloperCentral", "data", "files", "file.txt")
File file = path.toFile();

getFileName()

The getFileName method returns the name of the file, i.e., the last part of the path.

System.out.println(path.getFileName()); //file.txt

toUri()

Returns a URI that represents the path.

System.out.println(path.toUri()); //file:///Users/JavaDeveloperCentral/data/files/file.txt

getParent()

This method is opposite of getFileName() method. The getParent() returns the parent path (or null if the parent path is not present).

System.out.println(path.getParent());///Users/JavaDeveloperCentral/data/files

Creating a file using NIO Files

The NIO Files.createFile method creates a new and an empty file pointed to by a Path. It will fail with a FileAlreadyExistsException if the file already exists.

Path newFilePath = Paths.get("/Users/JavaDeveloperCentral/data/new-file.txt");
Files.createFile(newFilePath);

The above code will create an empty file called new-file.txt in the Path specified. 

FileAttribute<Set<PosixFilePermission>> fileAttributes = PosixFilePermissions
        .asFileAttribute(Set.of(PosixFilePermission.OWNER_WRITE));
Files.createFile(newFilePath, fileAttributes);

Reading a file #1 – Files.readAllLines

The Files.readAllLines method reads all the lines from a file. This means it loads the entire file’s data into the memory.
Example: Say we have a file called sample-file.txt with the below data.

123 456
abc def

Path filePath = Paths.get("/Users/JavaDeveloperCentral/data/sample-file.txt");
System.out.println(filePath);

Files.readAllLines(filePath)
        .forEach(System.out::println);

This code segments prints the file content as it is,

123 456
abc def

There is another overloaded readAllLines method that accepts a Charset parameter. The above method uses UTF_8 as the default charset. We can pass a Charset as.

Files.readAllLines(filePath, StandardCharsets.UTF_8) //or anything else
        .forEach(System.out::println);

Reading a file #2 – Files.readAllBytes

As the name indicates, this method reads the file as a byte array.

byte[] bytes = Files.readAllBytes(filePath);
System.out.println(new String(bytes));

Reading a file #3 – Files.readString

This method reads the file as a String (simple, isn’t it?). There is an overloaded readString() method that takes the Charset.

String data = Files.readString(filePath);
System.out.println(data);

data = Files.readString(filePath, StandardCharsets.UTF_8);
System.out.println(data);

Reading (Streaming a file) – Files.lines

With Java 8, Streams are everywhere. The methods we have seen so far to read the file loads the full data into memory in some format (List of string, byte [] or String). This approach will not work when we want to read a big file. The Java NIO Files class provides a method that allows us to stream the file’s content line by line (each line being a String).

It is the Files.lines method that does this. It reads all the lines from a file identified by a Path as a Stream.  The stream has the reference to the open file. Hence the file will only be closed when the stream is closed. Thus, it is our responsibility to close the stream. Using the Files.lines in a try-with-resource statement is a common way to do it, as it will take care of closing the resource (Stream here).

try (Stream<String> fileStream = Files.lines(filePath)) {
    fileStream.forEach(System.out::println);
}

This will produce the same output as the other read methods seen so far. 

Example: We can filter only the lines of even length as,

fileStream
        .filter(line -> line.length() %2 == 0)
        .forEach(System.out::println);

Like other read methods, there is a Files.lines() method that accepts the Charset as a second argument.

Writing to a file #1 – Files.writeString

The writeString() method writes a String to a file. It returns the Path of the file written.
Note: This method was added in Java 11.

String data = "some-data";
Path filePath = Paths.get("/Users/JavaDeveloperCentral/data/files/output-file.txt");
Path resultPath = Files.writeString(filePath, data);
System.out.println(resultPath);

The above will write the string some-data to the file named output-file.txt in the path specified. We also print the path to verify the same.

Writing to a file #2 – Files.write

To write a List of Strings, use the write() method. It has two varieties – one which defaults to UTF_8 charset encoding and one which receives the Charset as an argument.

List<String> list = List.of("a", "b", "c");
Files.write(filePath, list);

//Passing a charset
Files.write(filePath, list, StandardCharsets.UTF_8); //or something else

The file written will have the strings one in each line as

a
b
c

Note: If you are using Java < 9, then you can use Arrays.asList(“a”, “b”, “c”) in the above code snippet.

Passing an OpenOption when writing to a file

Both the writeString() and the write() method takes OpenOption. It is a var-args parameter which means we can pass multiple OpenOptions.

OpenOption is a marker interface (it has no methods) and is used to configure how to open or create a file. There are enums which implement the OpenOption interface. I will not cover all the available OpenOptions and will focus on the important ones. 

The StandardOpenOption

A StandardOpenOption is an enum which implements OpenOption. Let us look at a few enum instances from it.

StandardOpenOption.CREATE

OpenOption – Opening a file for writing

Files.writeString(filePath, data, StandardOpenOption.WRITE);

The above will open a file for writing. It is necessary for the file to exist. If the file does not exist, it will throw a NoSuchFileException.

Use CREATE_NEW to create a new file and write the data.

Files.writeString(filePath, data, StandardOpenOption.CREATE_NEW);

Note that if the file exists, it will throw FileAlreadyExistsException.

Files.writeString(filePath, data, StandardOpenOption.CREATE);

OpenOption – Writing

Now that we have opened a file successfully for writing, we can specify how to write the data. Using APPEND, we write to the end of the file. But by using TRUNCATE_EXSITING we clear the current file data (if not empty) and start writing from the beginning.

Putting it all together, here are some combinations of the OptionOptions.

//File exists - Append to it
Files.writeString(filePath, data, StandardOpenOption.WRITE, StandardOpenOption.APPEND);

//File exists - Truncate existing data
Files.writeString(filePath, data, StandardOpenOption.WRITE, StandardOpenOption.TRUNCATE_EXISTING);

//File does not exist, create a new one and write
Files.writeString(filePath, data, StandardOpenOption.CREATE_NEW);

//Create file if it does not exist and Append to it
Files.writeString(filePath, data, StandardOpenOption.CREATE, StandardOpenOption.APPEND);

//Create file if it does not exist - Truncate existing data
Files.writeString(filePath, data, StandardOpenOption.CREATE, StandardOpenOption.TRUNCATE_EXISTING);

In our initial write examples, we did not pass any OpenOptions. In that case, it would behave as if StandardOpenOption.CREATE, StandardOpenOption.TRUNCATE_EXSITING and StandardOpenOption.WRITE options were passed. In other words, it will open the file for writing if it exists, else it will create a new file. It will truncate the file contents if it was not empty.

Specifying only WRITE/CREATE OpenOption

Be careful if you specify only CREATE (when the file already exists) or when you specify only WRITE. Since we haven’t passed neither APPEND and nor TRUNCATE_EXISTING, it will start writing from the beginning. This will corrupt the data in the file (and presumably which is not what you intend for).

Example: Say the file has some-data as the content and,

Files.writeString(filePath, data, StandardOpenOption.WRITE);

The resultant file content will be test-data.

Copying a file with NIO Files

Let us look at what APIs Java NIO Files has for copying files. A copy operation has a source and a destination. In addition to this, the copy method takes a CopyOption. A CopyOption is a marker interface (like a OpenOption). This object configures how to copy or move a file.

The StandardCopyOption

StandardCopyOption is one of the enums that implement the CopyOption.

StandardCopyOption.REPLACE_EXISTING

Path sourceFilePath = Paths.get("/Users/JavaDeveloperCentral/data/files/source.txt");
Path destinationFilePath = Paths.get("/Users/JavaDeveloperCentral/data/files/destination.txt");

Files.copy(sourceFilePath, destinationFilePath, StandardCopyOption.REPLACE_EXISTING);

Copying a file – Other variations

Other than specifying the source and destinations as a Path, we can use an InputStream for a source or an OutputStream for the destination.

Let us create a BufferedInputStream from the source file and pass it to Files.copy. The result will be the same – source file data will be copied into the destination file.

InputStream is = new BufferedInputStream(new FileInputStream(sourceFilePath.toFile()));
Files.copy(is, destinationFilePath, StandardCopyOption.REPLACE_EXISTING);

Using an OutputStream as the target destination looks like.

OutputStream os = new BufferedOutputStream(new FileOutputStream(destinationFilePath.toFile()));
Files.copy(sourceFilePath, os);//no CopyOption when using a OutputStream
os.flush();//have to close/flush when using a BufferedOutputStream

Note that the outputStream has to be closed/flushed to have the data written properly. Alternatively, we can use a try-with-resources to automatically close the output stream.

try( OutputStream outputStream = new BufferedOutputStream(new FileOutputStream(destinationFilePath.toFile()))) {
    Files.copy(sourceFilePath, outputStream);
}

Moving a file

We use the Files.move method to move or rename a file. It fails with a FileAlreadyExistsException, if the target already exists. If we wish to overwrite the target if it exists, we can use the REPLACE_EXISTING as the CopyOption.

Path sourceFilePath = Paths.get("/Users/JavaDeveloperCentral/data/files/source.txt");
Path destinationFilePath = Paths.get("/Users/JavaDeveloperCentral/data/files/new_source.txt");

Files.move(sourceFilePath, destinationFilePath, StandardCopyOption.REPLACE_EXISTING);

The NIO Files.move method supports ATOMIC_MOVE CopyOption. But, the implementation can throw an AtomicMoveNotSupportedException if the move cannot be done atomically.

Deleting a file

This is a simple method that deletes the file pointed to by the path passed.

Path filePathToDelete = Paths.get("/Users/JavaDeveloperCentral/data/files/file.txt");
Files.delete(filePathToDelete);

If the file does not exist, it throws a NoSuchFileException. 

Files.delete(filePathToDelete); //deletes only if it exists

Checking if a file exists

The File.exits methods returns a boolean if the file exits.

Path sourceFilePath = Paths.get("/Users/JavaDeveloperCentral/data/files/source.txt");
System.out.println(Files.exists(sourceFilePath));

Apart from the Path parameter, it accepts a var-args parameter of type LinkOption. A LinkOption is an enum with one enum instance NOFOLLOW_LINKS. It says not to follow symbolic links. We can pass this if we want to follow symbolic links when checking if a file exists. By default, symbolic links are followed.

Path sourceFilePath = Paths.get("/Users/JavaDeveloperCentral/data/files/source.txt");
System.out.println(Files.exists(sourceFilePath, LinkOption.NOFOLLOW_LINKS));

Conclusion

We covered the common methods from the Java NIO Files class for operating on a file. First, we looked at the Path class since all the static methods in the Files class operate using a Path instance to point to a file. Then we looked at the most common operations performed on a file viz., creating, reading, writing, copying, moving, and deleting a file. 
I hope this would have been a detailed explanation of the NIO Files methods. I would like to hear your comments on this.

References

• Java NIO Files – Jenkov
• Baeldung Java NIO API
• Stackoverflow – Do terminal operations close the stream
• Javadoc of Java NIO Files – Java 8
• Javadoc of NIO Files – Java 11