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 aFileAlterationObserver
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 thecheckAndNotify()
method as required:// initialize observer.init(); ... // invoke as required observer.checkAndNotify(); ... observer.checkAndNotify(); ... // finished observer.finish();
Alternatively, register the observer(s) with aFileAlterationMonitor
, 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 usingFileFilter
s 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, capturingFile
attributes at a point in time. Custom implementations ofFileEntry
can be used to capture additional properties that the basic implementation does not support. TheFileEntry.refresh(File)
method is used to determine if a file or directory has changed since the last check and stores the current state of theFile
'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
All Methods Instance Methods Concrete Methods 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 filesprivate 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 directoryvoid
removeListener(FileAlterationListener listener)
Removes a file system listener.java.lang.String
toString()
Returns a String representation of this observer.
-
-
-
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 observefileFilter
- 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 observefileFilter
- The file filter or null if nonecaseSensitivity
- 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 observefileFilter
- 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 observefileFilter
- The file filter or null if nonecaseSensitivity
- 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 observefileFilter
- The file filter or null if nonecaseSensitivity
- 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 entryprevious
- The original list of filesfiles
- 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 entryfile
- 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 forentry
- 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 entryfile
- 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 classjava.lang.Object
- Returns:
- a String representation of this observer
-
-