java.nio.file.WatchEvent Example

WatchEvent<T> is an interface defined in the java.nio.file package. The type parameter T is the type of the context object associated with the event.

This interface has been in Java since Java SE 7 as part of NIO 2 File APIs. This is part of file change notification API, called the Watch Service API. Watch event in general represents an event or a repeated event for an object that is registered with a WatchService. A watch service watches registered objects for changes and events.

In a file system, the watch service is used to register a directory (or directories) with the watch service. At the registration, the types of events of interest are specified, i.e., file creation, deletion, or modification. When the service detects an event of interest, it is forwarded to a process – a thread (or a pool of threads) – for watching any registered events. The event is handled as needed when it occurs.

Want to be a Java NIO Master ?
Subscribe to our newsletter and download the JDBC Ultimate Guide right now!
In order to help you master Java NIO Library, we have compiled a kick-ass guide with all the major Java NIO features and use cases! Besides studying them online you may download the eBook in PDF format!

Thank you!

We will contact you soon.

1. Introduction

A watch event is classified by its kind. The kind() method returns the event kind (an identifier), defined by WatchEvent.Kind<T> interface. The StandardWatchEventKinds class defines the standard event kinds.

The StandardWatchEventKinds class has four fields (constants) that identify the event kinds: ENTRY_CREATE, ENTRY_DELETE, ENTRY_MODIFY and OVERFLOW. These identify the type of operation on a directory – an entry is created, deleted or modified in the directory. The overflow is a special event for lost or discarded events.

The events are of type WatchEvent.Kind<Path>, except OVERFLOW which is of type WatchEvent.Kind<Object>.

This example shows how the watch events are used in a watch service application.

2. Watch Events

The example application watches a directory for changes by using watch service. The kind of events monitored are modify and delete; that the directory is modified (like adding a file to the directory) or a file is deleted from the directory.

The program is explained in the following steps:

2.1. Create a new watch service for the file system

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

Note the method throws IOException.

2.2. Register for events to be monitored

Register one or more objects with the watch service. Any object that implements the Watchable interface can be registered. The Path extends the Watchable, so the directory to be monitored is registered as a Path object. Specify the type of events to monitor – in this case file modify and delete.

Path path = Paths.get("WatchedDir");
WatchKey watchKey = path.register(watchService, StandardWatchEventKinds.ENTRY_MODIFY, StandardWatchEventKinds.ENTRY_DELETE);

A WatchKey instance is returned for each directory registered. This is a token representing the registration of a Path object with a watch service.

Note the directory being watched is an existing directory. The method throws IOException.

2.3. Process the events

This is implemented as an infinite loop that waits for incoming events. When an event occurs, the watch key is signaled and placed into the watch service’s queue.

2.3.1. Wait for key to be signaled

The watch service’s take() method returns a queued key. If no queued key is available, this method waits. The method throws InterruptedException. This method’s usage is shown in the following code snippet.

for (;;) { // infinite loop
    WatchKey key;
    try {
        System.out.println("Waiting for key to be signalled...");
        key = watchService.take();
    } 
    catch (InterruptedException ex) {
    }

NOTE: There is also a poll() method which returns a queued key, if available. This method returns immediately with a null value, if key is unavailable.

2.3.2. Process the pending events for the key

The watch key’s pollEvents() method retrieves and removes all pending events for this watch key. The method returns a List collection of the events that are retrieved.

List<WatchEvent<?>> eventList = key.pollEvents();
System.out.println("Process the pending events for the key: " + eventList.size());
for (WatchEvent<?> genericEvent : key.pollEvents()) {

The List collection is iterated to process the events.

2.3.3. Retrieve the type of event

For each event the watch event’s kind() method returns the type of event. If the event is an OVERFLOW, the event is discarded and the program continues processing the next event.

NOTE: No matter what events the key has registered for, it is possible to receive an overflow event.

WatchEvent.Kind<?> eventKind = genericEvent.kind();
if (eventKind == OVERFLOW) {
    continue; // pending events for loop
}

2.3.4. Retrieve the file path associated with the event

The watch event’s context() method returns the Path object associated with the event. The path is the relative path between the directory registered with the watch service, and the entry that is created, deleted, or modified.The file’s path information can be used to do something – for example print the file name.

WatchEvent pathEvent = (WatchEvent) genericEvent;
Path file = pathEvent.context();
System.out.println(" File name: " + file.toString());

2.3.5. Reset the key

The events for the key have been processed, and it is required to put the key back into a ready state by invoking watch key’s reset() method. If this method returns false, the key is no longer valid and the infinite loop exits.

boolean validKey = key.reset();
if (! validKey) {
    break; // infinite for loop
}

2.4. Close the service

The watch service exits when either the thread exits or when it is closed by invoking its close() method. The method throws IOException.

watchService.close();

3. The Example

The following is the complete code for the watch event example.

WatchEventExample.java

import java.nio.file.Path;
import java.nio.file.Paths;
import java.nio.file.FileSystems;
import java.nio.file.WatchService;
import java.nio.file.WatchKey;
import java.nio.file.WatchEvent;
import java.nio.file.WatchEvent.Kind;
import java.io.IOException;
import static java.nio.file.StandardWatchEventKinds.*;
import java.util.List;
public class WatchEventExample {
    public static void main(String [] args)
            throws Exception {
	
        new WatchEventExample().doWatch();
    }
    @SuppressWarnings("unchecked")	
    private void doWatch()
            throws IOException, InterruptedException {
	
        WatchService watchService = FileSystems.getDefault().newWatchService();
		
        Path path = Paths.get("WatchedDir");
        WatchKey watchKey = path.register(watchService, ENTRY_DELETE, ENTRY_MODIFY);
									
        System.out.println("Watch service registered dir: " + path.toString());
									
        for (;;) {
		
            WatchKey key; 
            try {
                System.out.println("Waiting for key to be signalled...");
                key = watchService.take();
            }
            catch (InterruptedException ex) {
                System.out.println("Interrupted Exception");
                return;
            }
			
            List<WatchEvent<?>> eventList = key.pollEvents();
            System.out.println("Process the pending events for the key: " + eventList.size());
            for (WatchEvent<?> genericEvent: eventList) {
                WatchEvent.Kind<?> eventKind = genericEvent.kind();
                System.out.println("Event kind: " + eventKind);
                if (eventKind == OVERFLOW) {
                    continue; // pending events for loop
                }
                WatchEvent pathEvent = (WatchEvent) genericEvent;
                Path file = pathEvent.context();
                System.out.println("File name: " + file.toString());
            } 
            boolean validKey = key.reset();
            System.out.println("Key reset");
            System.out.println("");
            if (! validKey) {
                System.out.println("Invalid key");
                break; // infinite for loop
            }
        } // end infinite for loop
		
        watchService.close();
        System.out.println("Watch service closed.");
    }	
}

4. Run the Example

This program is tested on Windows 7 operating system. Note that Java 7 is required. Follow the below steps to run the example program and observe the results.

4.1. Create a directory:

Create a new directory in the same directory as the program: WatchedDir. Initially the directory can be empty.

4.2. Run the program:

Run the program from OS command prompt:

> java WatchEventExample

The following output is displayed on the terminal:

Watch service registered dir: WatchedDir
Waiting for key to be signaled...

From the output:

4.3. Modify events:

From the Windows file manager copy (drag and drop) a file (for example, notes.txt) into the WatchedDir. Note the following output is displayed on the terminal immediately:

Process the pending events for the key: 1
Event kind: ENTRY_MODIFY
File name: notes.txt
Key reset
Waiting for key to be signaled...

From the output:

4.4. Delete events:

From the Windows file manager navigate into the WatchedDir directory. Delete a file from the directory contents (for example, notes.txt). Note the following output is displayed on the terminal immediately:

Process the pending events for the key: 1
Event kind: ENTRY_DELETE
File name: notes.txt
Key reset
Waiting for key to be signaled....

The output is similar to that of the modify event. From the output note the number of events, the delete event type and the file name.

4.5. Close the program:

The program waits infinitely. Terminate the program with CTRL + C.

NOTES

5. Download Java Source Code

This was an example of java.nio.file.WatchEvent.

Download
You can download the full source code of this example here: WatchEventExample.zip
Exit mobile version