Package org.apache.commons.io.monitor
Class FileAlterationObserver
java.lang.Object
org.apache.commons.io.monitor.FileAlterationObserver
- All Implemented Interfaces:
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 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 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, 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:
-
Constructor Summary
ConstructorsModifierConstructorDescriptionFileAlterationObserver
(File directory) Constructs an observer for the specified directory.FileAlterationObserver
(File directory, FileFilter fileFilter) Constructs an observer for the specified directory and file filter.FileAlterationObserver
(File directory, FileFilter fileFilter, IOCase caseSensitivity) Constructs an observer for the specified directory, file filter and file comparator.FileAlterationObserver
(String directoryName) Constructs an observer for the specified directory.FileAlterationObserver
(String directoryName, FileFilter fileFilter) Constructs an observer for the specified directory and file filter.FileAlterationObserver
(String directoryName, FileFilter fileFilter, IOCase caseSensitivity) Construct an observer for the specified directory, file filter and file comparator.protected
FileAlterationObserver
(FileEntry rootEntry, FileFilter fileFilter, IOCase caseSensitivity) Constructs an observer for the specified directory, file filter and file comparator. -
Method Summary
Modifier and TypeMethodDescriptionvoid
addListener
(FileAlterationListener listener) Adds a file system listener.void
Checks whether the file and its children have been created, modified or deleted.void
destroy()
Final processing.Returns the directory being observed.Returns the fileFilter.Returns the set of registered file system listeners.void
Initializes the observer.void
removeListener
(FileAlterationListener listener) Removes a file system listener.toString()
Returns a String representation of this observer.
-
Constructor Details
-
FileAlterationObserver
Constructs an observer for the specified directory.- Parameters:
directoryName
- the name of the directory to observe
-
FileAlterationObserver
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
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
Constructs an observer for the specified directory.- Parameters:
directory
- the directory to observe
-
FileAlterationObserver
Constructs an observer for the specified directory and file filter.- Parameters:
directory
- the directory to observefileFilter
- The file filter or null if none
-
FileAlterationObserver
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, 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 Details
-
getDirectory
Returns the directory being observed.- Returns:
- the directory being observed
-
getFileFilter
Returns the fileFilter.- Returns:
- the fileFilter
- Since:
- 2.1
-
addListener
Adds a file system listener.- Parameters:
listener
- The file system listener
-
removeListener
Removes a file system listener.- Parameters:
listener
- The file system listener
-
getListeners
Returns the set of registered file system listeners.- Returns:
- The file system listeners
-
initialize
Initializes the observer.- Throws:
Exception
- if an error occurs
-
destroy
Final processing.- Throws:
Exception
- if an error occurs
-
checkAndNotify
Checks whether the file and its children have been created, modified or deleted. -
toString
Returns a String representation of this observer.
-