Differences Between the Java WatchService API and the Apache Commons IO Monitor Library

1. Overview

Long before the Java WatchService API was released in Java 7, Apache Commons IO Monitoring library was already addressing the same use-case of monitoring a file system location or directory for changes.

In this article, we are going to explore the differences between the two APIs.

2. Maven Dependencies

To use Apache Commons IO, the following dependency needs to be added in the pom:

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

Make sure to get the latest version of the commons-io.

And of course the watch service is part of the JDK, so it needs no external dependency.

3. Feature Comparison

3.1. Event Driven Processing

WatchService API is driven by the file system change events triggered by the operating system. This approach saves the application from polling the file system repeatedly for changes.

Apache Commons IO Monitor library on the other hand, polls the file system location at a configurable sleep interval by calling the listFiles() method of File class. This approach wastes CPU cycles, especially if no change occurs.

3.2. Callback Method

WatchService API does not provide callback methods. Instead it provides two types of polling methods to check if new change events are available for processing:

1. Blocking methods like poll() (with a timeout parameter) and take()
2. Non-blocking method like poll() (without a timeout parameter)

With the blocking methods, the application thread starts processing only when new change events are available. Therefore, it needs not keep on polling for new events.

The details and usage of these methods can be found in our article here.

In contrast, Apache Commons IO library provides callback methods on the FileAlterationListener interface which are invoked when a change in the file system location or directory is detected.

FileAlterationObserver observer = new FileAlterationObserver("pathToDir");
FileAlterationMonitor monitor = new FileAlterationMonitor(POLL_INTERVAL);
FileAlterationListener listener = new FileAlterationListenerAdaptor() {
    @Override
    public void onFileCreate(File file) {
        // code for processing creation event
    }

    @Override
    public void onFileDelete(File file) {
        // code for processing deletion event
    }

    @Override
    public void onFileChange(File file) {
        // code for processing change event
    }
};
observer.addListener(listener);
monitor.addObserver(observer);
monitor.start();

3.3. Event Overflow

WatchService API is driven by the operating system events. Hence, there is a possibility that the operating system buffer that holds the events overflows, if the application cannot process the events quickly enough. In this scenario, the event StandardWatchEventKinds.OVERFLOW is triggered indicating that some of the events are lost or discarded before the application could read them.

This requires proper handling of the OVERFLOW event in the application to ensure that the application can handle any sudden burst of change events that may trigger the OVERFLOW event.

The Commons IO library on the other hand, is not based on the operating system events and hence there is no question of overflow.

In every poll, the observer gets the list of files in the directory and compares it with the list obtained from the previous poll.

1. If a new file name is found in the last poll, onFileCreate() is invoked on the listener
2. If a file name found in the previous poll is missing in the file list obtained from the last poll, onFileDelete() is invoked on the listener
3. If a match is found, the file is checked for any change in attributes like last modified date, length etc. If a change is detected, onFileChange() is invoked on the listener

4. Conclusion

In this article we have managed to highlight the key differences in the two APIs.