Getting Started

To start using jpathwatch, download the library’s JAR file first via the download page and add it to your project.

In the class where you want to do file watching, import jpatchwatch’s package, like so:

import name.pachler.nio.file.*;

The first thing we’ll need to do is to create a WatchService. This object manages all operating system resources required for monitoring files. You’ll create it like this:

WatchService watchService = FileSystems.getDefault().newWatchService();

Now we need something we can watch. Assume we watch a directory called “/tmp” (or “c:\temp” on Windows). Before trying this, make sure it exists on your local hard drive.

jpathwatch needs a special object to be able to monitor a directory, called a Path. We’ll create one now for “/tmp”:

Path watchedPath = Paths.get("/tmp");

The path is only a representative for the directory, it doesn’t actually create a directory or change any files. To monitor this path for changes, we need to register it with the WatchService that we created above, like this:

WatchKey key = null;
try {
    key = path.register(watchService, StandardWatchEventKind.ENTRY_CREATE, StandardWatchEventKind.ENTRY_DELETE);
} catch (UnsupportedOperationException uox){
    System.err.println("file watching not supported!");
    // handle this error here
}catch (IOException iox){
    System.err.println("I/O errors");
    // handle this error here
}

This will associate the Path with the WatchService. Such a registration is represented by a WatchKey that register() creates for us. The ENTRY_CREATE and ENTRY_DELETE constants specify what we want to watch for – in this case files being created and deleted. These constants are called event kinds.

You surely have noticed the try/catch block. This is because registration can fail for a number of reasons, mainly because the platform you’re running on doesn’t support the event kinds you requested.

Now all we have to do now is to wait for changes. In this simple example, we’ll wait for changes in an infinite loop, like this:

for(;;){
    // take() will block until a file has been created/deleted
    WatchKey signalledKey;
    try {
        signalledKey = watchService.take();
    } catch (InterruptedException ix){
        // we'll ignore being interrupted
        continue;
    } catch (ClosedWatchServiceException cwse){
        // other thread closed watch service
        System.out.println("watch service closed, terminating.");
        break;
    }

    // get list of events from key
    List<WatchEvent<?>> list = signalledKey.pollEvents();

    // VERY IMPORTANT! call reset() AFTER pollEvents() to allow the
    // key to be reported again by the watch service
    signalledKey.reset();

    // we'll simply print what has happened; real applications
    // will do something more sensible here
    for(WatchEvent e : list){
        String message = "";
        if(e.kind() == StandardWatchEventKind.ENTRY_CREATE){
            Path context = (Path)e.context();
            message = context.toString() + " created";
        } else if(e.kind() == StandardWatchEventKind.ENTRY_DELETE){
            Path context = (Path)e.context();
            message = context.toString() + " deleted";
        } else if(e.kind() == StandardWatchEventKind.OVERFLOW){
            message = "OVERFLOW: more changes happened than we could retreive";
        }
        System.out.println(message);
    }
}

A couple of things happen here: The call to WatchService.take() is what actually waits for events. take() will not return until a file has been created or deleted (as we requested), or until the WatchService is closed.

When an event has occurred, the WatchKey returned by take is in the ready state (it is signalled), which means that the current thread received it for processing. Note that in our example, the returned key will be the same object that we received previously from register().

To find out what happened, we call WatchKey.pollEvents(), which returns a list of events. After we have that list, we call WatchKey.reset(), which resets the key’s signalled state and allows the key to be reported again by the WatchService.

The example then simply iterates over the list and examines each WatchEvent instance to find out what has happened.