Package 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 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(FileUtils.current(), "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.

## Deprecating Serialization

Serialization is deprecated and will be removed in 3.0.

Since:
  2.0
See Also:
  - `FileAlterationListener`
  - `FileAlterationMonitor`
  - Serialized Form

- ## Nested Class Summary

  Nested Classes
  Modifier and Type
  Class
  Description
  `static final class`
  `FileAlterationObserver.Builder`
  Builds instances of `FileAlterationObserver`.

- ## Constructor Summary

  Constructors
  Modifier
  Constructor
  Description
  ``
  `FileAlterationObserver(File directory)`
  Deprecated.
  Use `builder()`.
  ``
  `FileAlterationObserver(File directory, FileFilter fileFilter)`
  Deprecated.
  Use `builder()`.
  ``
  `FileAlterationObserver(File directory, FileFilter fileFilter, IOCase ioCase)`
  Deprecated.
  Use `builder()`.
  ``
  `FileAlterationObserver(String directoryName)`
  Deprecated.
  Use `builder()`.
  ``
  `FileAlterationObserver(String directoryName, FileFilter fileFilter)`
  Deprecated.
  Use `builder()`.
  ``
  `FileAlterationObserver(String directoryName, FileFilter fileFilter, IOCase ioCase)`
  Deprecated.
  Use `builder()`.
  `protected`
  `FileAlterationObserver(FileEntry rootEntry, FileFilter fileFilter, IOCase ioCase)`
  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.
  `static FileAlterationObserver.Builder`
  `builder()`
  Creates a new builder.
  `void`
  `checkAndNotify()`
  Checks whether the file and its children have been created, modified or deleted.
  `void`
  `destroy()`
  Final processing.
  `File`
  `getDirectory()`
  Returns the directory being observed.
  `FileFilter`
  `getFileFilter()`
  Returns the fileFilter.
  `Iterable<FileAlterationListener>`
  `getListeners()`
  Returns the set of registered file system listeners.
  `void`
  `initialize()`
  Initializes the observer.
  `void`
  `removeListener(FileAlterationListener listener)`
  Removes a file system listener.
  `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`

- ## Constructor Details

  - ### FileAlterationObserver

    @Deprecated public FileAlterationObserver(File directory)
    Deprecated.
    Use `builder()`.
    Constructs an observer for the specified directory.
    Parameters:
      `directory` - the directory to observe.

  - ### FileAlterationObserver

    @Deprecated public FileAlterationObserver(File directory, FileFilter fileFilter)
    Deprecated.
    Use `builder()`.
    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

    @Deprecated public FileAlterationObserver(File directory, FileFilter fileFilter, IOCase ioCase)
    Deprecated.
    Use `builder()`.
    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.
      `ioCase` - What case sensitivity to use comparing file names, null means system sensitive.

  - ### FileAlterationObserver

    protected FileAlterationObserver(FileEntry rootEntry, FileFilter fileFilter, IOCase ioCase)
    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.
      `ioCase` - What case sensitivity to use comparing file names, null means system sensitive.

  - ### FileAlterationObserver

    @Deprecated public FileAlterationObserver(String directoryName)
    Deprecated.
    Use `builder()`.
    Constructs an observer for the specified directory.
    Parameters:
      `directoryName` - the name of the directory to observe.

  - ### FileAlterationObserver

    @Deprecated public FileAlterationObserver(String directoryName, FileFilter fileFilter)
    Deprecated.
    Use `builder()`.
    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

    @Deprecated public FileAlterationObserver(String directoryName, FileFilter fileFilter, IOCase ioCase)
    Deprecated.
    Use `builder()`.
    Constructs 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.
      `ioCase` - what case sensitivity to use comparing file names, null means system sensitive.

- ## Method Details

  - ### builder

    public static FileAlterationObserver.Builder builder()
    Creates a new builder.
    Returns:
      a new builder.
    Since:
      2.18.0

  - ### addListener

    public void addListener(FileAlterationListener listener)
    Adds a file system listener.
    Parameters:
      `listener` - The file system listener.

  - ### checkAndNotify

    public void checkAndNotify()
    Checks whether the file and its children have been created, modified or deleted.

  - ### destroy

    public void destroy() throws Exception
    Final processing.
    Throws:
      `Exception` - if an error occurs.

  - ### getDirectory

    public File getDirectory()
    Returns the directory being observed.
    Returns:
      the directory being observed.

  - ### getFileFilter

    public FileFilter getFileFilter()
    Returns the fileFilter.
    Returns:
      the fileFilter.
    Since:
      2.1

  - ### getListeners

    public Iterable<FileAlterationListener> getListeners()
    Returns the set of registered file system listeners.
    Returns:
      The file system listeners

  - ### initialize

    public void initialize() throws Exception
    Initializes the observer.
    Throws:
      `Exception` - if an error occurs.

  - ### removeListener

    public void removeListener(FileAlterationListener listener)
    Removes a file system listener.
    Parameters:
      `listener` - The file system listener.

  - ### toString

    public String toString()
    Returns a String representation of this observer.
    Overrides:
      `toString` in class `Object`
    Returns:
      a String representation of this observer.