FileAlterationObserver (Apache Commons IO 2.6 API)

java.lang.Object
- org.apache.commons.io.monitor.FileAlterationObserver

All Implemented Interfaces:

Serializable
```
public class FileAlterationObserver
extends Object
implements Serializable
```
FileAlterationObserver represents the state of files below a root directory, checking the filesystem 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

Version:

$Id$

See Also:

FileAlterationListener, FileAlterationMonitor, Serialized Form

Constructor Summary

Constructors
Modifier	Constructor and Description
	`FileAlterationObserver(File directory)` Construct an observer for the specified directory.
`protected`	`FileAlterationObserver(FileEntry rootEntry, FileFilter fileFilter, IOCase caseSensitivity)` Construct an observer for the specified directory, file filter and file comparator.
	`FileAlterationObserver(File directory, FileFilter fileFilter)` Construct an observer for the specified directory and file filter.
	`FileAlterationObserver(File directory, FileFilter fileFilter, IOCase caseSensitivity)` Construct an observer for the specified directory, file filter and file comparator.
	`FileAlterationObserver(String directoryName)` Construct an observer for the specified directory.
	`FileAlterationObserver(String directoryName, FileFilter fileFilter)` Construct 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.

Method Summary

All Methods Instance Methods Concrete Methods
Modifier and Type	Method and Description
`void`	`addListener(FileAlterationListener listener)` Add a file system listener.
`void`	`checkAndNotify()` Check whether the file and its children have been created, modified or deleted.
`void`	`destroy()` Final processing.
`File`	`getDirectory()` Return the directory being observed.
`FileFilter`	`getFileFilter()` Return the fileFilter.
`Iterable<FileAlterationListener>`	`getListeners()` Returns the set of registered file system listeners.
`void`	`initialize()` Initialize the observer.
`void`	`removeListener(FileAlterationListener listener)` Remove a file system listener.
`String`	`toString()` Provide a String representation of this observer.

Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

- Constructor Detail
  - FileAlterationObserver
```
public FileAlterationObserver(String directoryName)
```
    Construct an observer for the specified directory.
    
    Parameters:
    
    directoryName - the name of the directory to observe
  - FileAlterationObserver
```
public FileAlterationObserver(String directoryName,
                              FileFilter fileFilter)
```
    Construct 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(String directoryName,
                              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(File directory)
```
    Construct an observer for the specified directory.
    
    Parameters:
    
    directory - the directory to observe
  - FileAlterationObserver
```
public FileAlterationObserver(File directory,
                              FileFilter fileFilter)
```
    Construct 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(File directory,
                              FileFilter fileFilter,
                              IOCase caseSensitivity)
```
    Construct 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,
                                 FileFilter fileFilter,
                                 IOCase caseSensitivity)
```
    Construct 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 File getDirectory()
```
    Return the directory being observed.
    
    Returns:
    
    the directory being observed
  - getFileFilter
```
public FileFilter getFileFilter()
```
    Return the fileFilter.
    
    Returns:
    
    the fileFilter
    
    Since:
    
    2.1
  - addListener
```
public void addListener(FileAlterationListener listener)
```
    Add a file system listener.
    
    Parameters:
    
    listener - The file system listener
  - removeListener
```
public void removeListener(FileAlterationListener listener)
```
    Remove a file system listener.
    
    Parameters:
    
    listener - The file system listener
  - getListeners
```
public Iterable<FileAlterationListener> getListeners()
```
    Returns the set of registered file system listeners.
    
    Returns:
    
    The file system listeners
  - initialize
```
public void initialize()
                throws Exception
```
    Initialize the observer.
    
    Throws:
    
    Exception - if an error occurs
  - destroy
```
public void destroy()
             throws Exception
```
    Final processing.
    
    Throws:
    
    Exception - if an error occurs
  - checkAndNotify
```
public void checkAndNotify()
```
    Check whether the file and its children have been created, modified or deleted.
  - toString
```
public String toString()
```
    Provide a String representation of this observer.
    
    Overrides:
    
    toString in class Object
    
    Returns:
    
    a String representation of this observer

Class FileAlterationObserver

Basic Usage

File Filters

FileEntry

Constructor Summary

Method Summary

Methods inherited from class java.lang.Object

Constructor Detail

FileAlterationObserver

FileAlterationObserver

FileAlterationObserver

FileAlterationObserver

FileAlterationObserver

FileAlterationObserver

FileAlterationObserver

Method Detail

getDirectory

getFileFilter

addListener

removeListener

getListeners

initialize

destroy

checkAndNotify

toString