org.apache.commons.io.monitor

## Class FileAlterationObserver

- 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 `FileFilter`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
Version:
  $Id$
See Also:
  `FileAlterationListener`, `FileAlterationMonitor`, Serialized Form

### Constructor Summary

Constructors
`` `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
`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