Package org.apache.commons.io.monitor

Class FileAlterationObserver

java.lang.Object

org.apache.commons.io.monitor.FileAlterationObserver

All Implemented Interfaces:

java.io.Serializable

public class FileAlterationObserver
extends java.lang.Object
implements java.io.Serializable

FileAlterationObserver represents the state of files below a root directory, checking the file system and notifying listeners of create, change or delete events.

To use this implementation:

• Create FileAlterationListener implementation(s) that process the file/directory create, change and delete events
• Register the listener(s) with a FileAlterationObserver for the appropriate directory.
• Either register the observer(s) with a FileAlterationMonitor or run manually.

Basic Usage

Create a FileAlterationObserver for the directory and register the listeners:

      File directory = new File(new File("."), "src");
      FileAlterationObserver observer = new FileAlterationObserver(directory);
      observer.addListener(...);
      observer.addListener(...);
 

To manually observe a directory, initialize the observer and invoked the checkAndNotify() method as required:

      // initialize
      observer.init();
      ...
      // invoke as required
      observer.checkAndNotify();
      ...
      observer.checkAndNotify();
      ...
      // finished
      observer.finish();
 

Alternatively, register the observer(s) with a FileAlterationMonitor, which creates a new thread, invoking the observer at the specified interval:

      long interval = ...
      FileAlterationMonitor monitor = new FileAlterationMonitor(interval);
      monitor.addObserver(observer);
      monitor.start();
      ...
      monitor.stop();
 

File Filters

This implementation can monitor portions of the file system by using FileFilters to observe only the files and/or directories that are of interest. This makes it more efficient and reduces the noise from unwanted file system events.

Commons IO has a good range of useful, ready made File Filter implementations for this purpose.

For example, to only observe 1) visible directories and 2) files with a ".java" suffix in a root directory called "src" you could set up a FileAlterationObserver in the following way:

      // Create a FileFilter
      IOFileFilter directories = FileFilterUtils.and(
                                      FileFilterUtils.directoryFileFilter(),
                                      HiddenFileFilter.VISIBLE);
      IOFileFilter files       = FileFilterUtils.and(
                                      FileFilterUtils.fileFileFilter(),
                                      FileFilterUtils.suffixFileFilter(".java"));
      IOFileFilter filter = FileFilterUtils.or(directories, files);

      // Create the File system observer and register File Listeners
      FileAlterationObserver observer = new FileAlterationObserver(new File("src"), filter);
      observer.addListener(...);
      observer.addListener(...);
 

FileEntry

FileEntry represents the state of a file or directory, capturing File attributes at a point in time. Custom implementations of FileEntry can be used to capture additional properties that the basic implementation does not support. The FileEntry.refresh(File) method is used to determine if a file or directory has changed since the last check and stores the current state of the File's properties.

Since:

2.0

See Also:

FileAlterationListener, FileAlterationMonitor, Serialized Form

Field Summary

Fields

Modifier and Type	Field	Description
private java.util.Comparator<java.io.File>	comparator
private java.io.FileFilter	fileFilter
private java.util.List<FileAlterationListener>	listeners
private FileEntry	rootEntry
private static long	serialVersionUID

Constructor Summary

Constructors

Modifier	Constructor	Description
	FileAlterationObserver(java.io.File directory)	Constructs an observer for the specified directory.
	FileAlterationObserver(java.io.File directory, java.io.FileFilter fileFilter)	Constructs an observer for the specified directory and file filter.
	FileAlterationObserver(java.io.File directory, java.io.FileFilter fileFilter, IOCase caseSensitivity)	Constructs an observer for the specified directory, file filter and file comparator.
	FileAlterationObserver(java.lang.String directoryName)	Constructs an observer for the specified directory.
	FileAlterationObserver(java.lang.String directoryName, java.io.FileFilter fileFilter)	Constructs an observer for the specified directory and file filter.
	FileAlterationObserver(java.lang.String directoryName, java.io.FileFilter fileFilter, IOCase caseSensitivity)	Construct an observer for the specified directory, file filter and file comparator.
protected	FileAlterationObserver(FileEntry rootEntry, java.io.FileFilter fileFilter, IOCase caseSensitivity)	Constructs an observer for the specified directory, file filter and file comparator.

Method Summary

Modifier and Type	Method	Description
void	addListener(FileAlterationListener listener)	Adds a file system listener.
void	checkAndNotify()	Checks whether the file and its children have been created, modified or deleted.
private void	checkAndNotify(FileEntry parent, FileEntry[] previous, java.io.File[] files)	Compares two file lists for files which have been created, modified or deleted.
private FileEntry	createFileEntry(FileEntry parent, java.io.File file)	Creates a new file entry for the specified file.
void	destroy()	Final processing.
private void	doCreate(FileEntry entry)	Fires directory/file created events to the registered listeners.
private void	doDelete(FileEntry entry)	Fires directory/file delete events to the registered listeners.
private FileEntry[]	doListFiles(java.io.File file, FileEntry entry)	Lists the files
private void	doMatch(FileEntry entry, java.io.File file)	Fires directory/file change events to the registered listeners.
java.io.File	getDirectory()	Returns the directory being observed.
java.io.FileFilter	getFileFilter()	Returns the fileFilter.
java.lang.Iterable<FileAlterationListener>	getListeners()	Returns the set of registered file system listeners.
void	initialize()	Initializes the observer.
private java.io.File[]	listFiles(java.io.File file)	Lists the contents of a directory
void	removeListener(FileAlterationListener listener)	Removes a file system listener.
java.lang.String	toString()	Returns a String representation of this observer.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Field Detail

serialVersionUID

private static final long serialVersionUID

See Also:

Constant Field Values

listeners

private final java.util.List<FileAlterationListener> listeners

rootEntry

private final FileEntry rootEntry

fileFilter

private final java.io.FileFilter fileFilter

comparator

private final java.util.Comparator<java.io.File> comparator

Constructor Detail

FileAlterationObserver

public FileAlterationObserver(java.lang.String directoryName)

Constructs an observer for the specified directory.

Parameters:

directoryName - the name of the directory to observe

FileAlterationObserver

public FileAlterationObserver(java.lang.String directoryName,
                              java.io.FileFilter fileFilter)

Constructs an observer for the specified directory and file filter.

Parameters:

directoryName - the name of the directory to observe

fileFilter - The file filter or null if none

FileAlterationObserver

public FileAlterationObserver(java.lang.String directoryName,
                              java.io.FileFilter fileFilter,
                              IOCase caseSensitivity)

Construct an observer for the specified directory, file filter and file comparator.

Parameters:

directoryName - the name of the directory to observe

fileFilter - The file filter or null if none

caseSensitivity - what case sensitivity to use comparing file names, null means system sensitive

FileAlterationObserver

public FileAlterationObserver(java.io.File directory)

Constructs an observer for the specified directory.

Parameters:

directory - the directory to observe

FileAlterationObserver

public FileAlterationObserver(java.io.File directory,
                              java.io.FileFilter fileFilter)

Constructs an observer for the specified directory and file filter.

Parameters:

directory - the directory to observe

fileFilter - The file filter or null if none

FileAlterationObserver

public FileAlterationObserver(java.io.File directory,
                              java.io.FileFilter fileFilter,
                              IOCase caseSensitivity)

Constructs an observer for the specified directory, file filter and file comparator.

Parameters:

directory - the directory to observe

fileFilter - The file filter or null if none

caseSensitivity - what case sensitivity to use comparing file names, null means system sensitive

FileAlterationObserver

protected FileAlterationObserver(FileEntry rootEntry,
                                 java.io.FileFilter fileFilter,
                                 IOCase caseSensitivity)

Constructs an observer for the specified directory, file filter and file comparator.

Parameters:

rootEntry - the root directory to observe

fileFilter - The file filter or null if none

caseSensitivity - what case sensitivity to use comparing file names, null means system sensitive

Method Detail

getDirectory

public java.io.File getDirectory()

Returns the directory being observed.

Returns:

the directory being observed

getFileFilter

public java.io.FileFilter getFileFilter()

Returns the fileFilter.

Returns:

the fileFilter

Since:

2.1

addListener

public void addListener(FileAlterationListener listener)

Adds a file system listener.

Parameters:

listener - The file system listener

removeListener

public void removeListener(FileAlterationListener listener)

Removes a file system listener.

Parameters:

listener - The file system listener

getListeners

public java.lang.Iterable<FileAlterationListener> getListeners()

Returns the set of registered file system listeners.

Returns:

The file system listeners

initialize

public void initialize()
                throws java.lang.Exception

Initializes the observer.

Throws:

java.lang.Exception - if an error occurs

destroy

public void destroy()
             throws java.lang.Exception

Final processing.

Throws:

java.lang.Exception - if an error occurs

checkAndNotify

public void checkAndNotify()

Checks whether the file and its children have been created, modified or deleted.

checkAndNotify

private void checkAndNotify(FileEntry parent,
                            FileEntry[] previous,
                            java.io.File[] files)

Compares two file lists for files which have been created, modified or deleted.

Parameters:

parent - The parent entry

previous - The original list of files

files - The current list of files

createFileEntry

private FileEntry createFileEntry(FileEntry parent,
                                  java.io.File file)

Creates a new file entry for the specified file.

Parameters:

parent - The parent file entry

file - The file to create an entry for

Returns:

A new file entry

doListFiles

private FileEntry[] doListFiles(java.io.File file,
                                FileEntry entry)

Lists the files

Parameters:

file - The file to list files for

entry - the parent entry

Returns:

The child files

doCreate

private void doCreate(FileEntry entry)

Fires directory/file created events to the registered listeners.

Parameters:

entry - The file entry

doMatch

private void doMatch(FileEntry entry,
                     java.io.File file)

Fires directory/file change events to the registered listeners.

Parameters:

entry - The previous file system entry

file - The current file

doDelete

private void doDelete(FileEntry entry)

Fires directory/file delete events to the registered listeners.

Parameters:

entry - The file entry

listFiles

private java.io.File[] listFiles(java.io.File file)

Lists the contents of a directory

Parameters:

file - The file to list the contents of

Returns:

the directory contents or a zero length array if the empty or the file is not a directory

toString

public java.lang.String toString()

Returns a String representation of this observer.

Overrides:

toString in class java.lang.Object

Returns:

a String representation of this observer