Differences Between the Java WatchService API and the Apache Commons IO Monitor Library – Java WatchService API和Apache Commons IO监控库之间的区别

最后修改: 2016年 12月 24日


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.

早在Java WatchService API在Java 7中发布之前,Apache Commons IO Monitoring库已经在处理相同的用例,即监测文件系统位置或目录的变化。

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:

为了使用Apache Commons IO,需要在pom中添加以下依赖。


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.

WatchService API由操作系统触发的文件系统变化事件驱动。这种方法使应用程序无需反复轮询文件系统的变化。

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.

另一方面,Apache Commons IO Monitor库通过调用File类的listFiles()方法,在可配置的睡眠间隔内轮询文件系统位置。这种方法浪费了CPU周期,尤其是在没有发生变化的情况下。

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:

WatchService API不提供回调方法。相反,它提供了两种类型的轮询方法来检查是否有新的变化事件可供处理。

  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.

相比之下,Apache Commons IO库在FileAlterationListener接口上提供了回调方法,当检测到文件系统位置或目录发生变化时就会调用这些方法。

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

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

    public void onFileChange(File file) {
        // code for processing change event

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.

WatchService API是由操作系统事件驱动的。因此,如果应用程序不能足够快地处理这些事件,就有可能出现持有事件的操作系统缓冲区溢出的情况。在这种情况下,事件StandardWatchEventKinds.OVERFLOW被触发,表明一些事件在应用程序可以读取之前就被丢失或丢弃了。

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.

另一方面,Commons IO库不以操作系统事件为基础,因此不存在溢出的问题。

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.


And, as always, the full source code for the examples used in this article is available in our GitHub project.