Apache Commons IO

1. Overview

The Apache Commons project was created to provide developers with a set of common libraries that they can use in their day-to-day code.

In this tutorial, we’ll explore some of the key utility classes of the Commons IO module and their most well-known functions.

2. Maven Dependency

To use the library, let’s include the following Maven dependency in the pom.xml:

<dependency>
    <groupId>commons-io</groupId>
    <artifactId>commons-io</artifactId>
    <version>2.5</version>
</dependency>

The latest versions of the library can be found in Maven Central.

3. Utility Classes

Simply put, utility classes provide sets of static methods that can be used to perform common tasks on files.

3.1. FileUtils

This class provides different operations on files, such as opening, reading, copying, and moving.

Let’s look at how to read or copy files using FileUtils:

File file = FileUtils.getFile(getClass().getClassLoader()
  .getResource("fileTest.txt")
  .getPath());
File tempDir = FileUtils.getTempDirectory();
FileUtils.copyFileToDirectory(file, tempDir);
File newTempFile = FileUtils.getFile(tempDir, file.getName());
String data = FileUtils.readFileToString(newTempFile,
  Charset.defaultCharset());

3.2. FilenameUtils

This utility provides an operating-system-agnostic way of executing common functions on file names. Let’s see some of the different methods we can utilize:

String fullPath = FilenameUtils.getFullPath(path);
String extension = FilenameUtils.getExtension(path);
String baseName = FilenameUtils.getBaseName(path);

3.3. FileSystemUtils

We can use FileSystemUtils to check the free space on a given volume or drive:

long freeSpace = FileSystemUtils.freeSpaceKb("/");

4. Input and Output

This package provides several implementations for working with input and output streams.

We’ll focus on TeeInputStream and TeeOutputSteam. The word “Tee” (derived from letter “T“) is normally used to describe that a single input is to be split into two different outputs.

Let’s look at an example that demonstrates how we can write a single input stream to two different output streams:

String str = "Hello World.";
ByteArrayInputStream inputStream = new ByteArrayInputStream(str.getBytes());
ByteArrayOutputStream outputStream1 = new ByteArrayOutputStream();
ByteArrayOutputStream outputStream2 = new ByteArrayOutputStream();

FilterOutputStream teeOutputStream
  = new TeeOutputStream(outputStream1, outputStream2);
new TeeInputStream(inputStream, teeOutputStream, true)
  .read(new byte[str.length()]);

assertEquals(str, String.valueOf(outputStream1));
assertEquals(str, String.valueOf(outputStream2));

5. Filters

Commons IO includes a list of useful file filters. These can come in handy when a developer wants to narrow down to a specific desired list of files from a heterogeneous list of files.

The library also supports AND and OR logic operations on a given file list. Therefore, we can mix and match these filters to get the desired outcome.

Let’s see an example that makes use of WildcardFileFilter and SuffixFileFilter to retrieve files which have “ple” in their names with a “txt” suffix. Note that we wrap above filters using ANDFileFilter: 

@Test
public void whenGetFilewith_ANDFileFilter_thenFind_sample_txt()
  throws IOException {

    String path = getClass().getClassLoader()
      .getResource("fileTest.txt")
      .getPath();
    File dir = FileUtils.getFile(FilenameUtils.getFullPath(path));

    assertEquals("sample.txt",
      dir.list(new AndFileFilter(
        new WildcardFileFilter("*ple*", IOCase.INSENSITIVE),
        new SuffixFileFilter("txt")))[0]);
}

6. Comparators

The Comparator package provides different types of comparisons on files. We’ll explore two different comparators here.

6.1. PathFileComparator

The PathFileComparator class can be used to sort lists or arrays of files by their path either in a case-sensitive, case-insensitive, or system-dependent case-sensitive way. Let’s see how to sort file paths in the resources directory using this utility:

@Test
public void whenSortDirWithPathFileComparator_thenFirstFile_aaatxt() 
  throws IOException {
    
    PathFileComparator pathFileComparator = new PathFileComparator(
      IOCase.INSENSITIVE);
    String path = FilenameUtils.getFullPath(getClass()
      .getClassLoader()
      .getResource("fileTest.txt")
      .getPath());
    File dir = new File(path);
    File[] files = dir.listFiles();

    pathFileComparator.sort(files);

    assertEquals("aaa.txt", files[0].getName());
}

Note that we have used the IOCase.INSENSITIVE configuration. PathFileComparator also provides a number of singleton instances that have different case-sensitivity and reverse-sorting options.

These static fields include PATH_COMPARATOR, PATH_INSENSITIVE_COMPARATOR, PATH_INSENSITIVE_REVERSE, PATH_SYSTEM_COMPARATOR, to name few.

6.2. SizeFileComparator

SizeFileComparator is, as its name suggests, used to compare the sizes (lengths) of two files. It returns a negative integer value if the first file’s size is less than that of the second file. It returns zero if the file sizes are equal and a positive value if the first file’s size is greater than the second file’s size.

Let’s write a unit test demonstrating a comparison of file sizes:

@Test
public void whenSizeFileComparator_thenLargerFile_large()
  throws IOException {

    SizeFileComparator sizeFileComparator = new SizeFileComparator();
    File largerFile = FileUtils.getFile(getClass().getClassLoader()
      .getResource("fileTest.txt")
      .getPath());
    File smallerFile = FileUtils.getFile(getClass().getClassLoader()
      .getResource("sample.txt")
      .getPath());

    int i = sizeFileComparator.compare(largerFile, smallerFile);

    Assert.assertTrue(i > 0);
}

7. File Monitor

The Commons IO monitor package provides the capability to track changes to a file or directory. Let’s see a quick example of how FileAlterationMonitor can be used together with FileAlterationObserver and FileAlterationListener to monitor a file or folder.

When FileAlterationMonitor starts, we’ll start receiving notifications for file changes on the directory that is being monitored:

FileAlterationObserver observer = new FileAlterationObserver(folder);
FileAlterationMonitor monitor = new FileAlterationMonitor(5000);

FileAlterationListener fal = new FileAlterationListenerAdaptor() {

    @Override
    public void onFileCreate(File file) {
        // on create action
    }

    @Override
    public void onFileDelete(File file) {
        // on delete action
    }
};

observer.addListener(fal);
monitor.addObserver(observer);
monitor.start();

8. Conclusion

This article covered some of the commonly used components of Commons IO package. However, the package does come with many other capabilities as well. Please refer to API documentation for more details.

The code used in this example can be found in the GitHub project.