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.

  See Also:
    `FileAlterationListener`, `FileAlterationMonitor`, Serialized Form

- - ### Nested Class Summary

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

  - ### Constructor Summary

    Constructors
    Modifier | Constructor and Description
    --- | ---
    `protected` | `FileAlterationObserver(FileEntry rootEntry, FileFilter fileFilter, IOCase ioCase)` Constructs an observer for the specified directory, file filter and file comparator.

  - ### Method Summary

    All Methods Static Methods Instance Methods Concrete Methods
    Modifier and Type | Method and 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.
    `(package private) Comparator<File>` | `getComparator()`
    `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 Detail

    - #### 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.

  - ### Method Detail

    - #### addListener

          public void addListener(FileAlterationListener listener)

      Adds a file system listener.
      Parameters:
        `listener` - The file system listener.

    - #### builder

          public static FileAlterationObserver.Builder builder()

      Creates a new builder.
      Returns:
        a new builder.

    - #### 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.

    - #### getComparator

          Comparator<File> getComparator()

    - #### getDirectory

          public File getDirectory()

      Returns the directory being observed.
      Returns:
        the directory being observed.

    - #### getFileFilter

          public FileFilter getFileFilter()

      Returns the fileFilter.
      Returns:
        the fileFilter.

    - #### 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.