FileAlterationObserver (Commons IO 2.5)
Date: 2016-12-01

org.apache.commons.io.monitor

## Class FileAlterationObserver

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

- All Implemented Interfaces:
    java.io.Serializable

      public class FileAlterationObserver
      extends java.lang.Object
      implements java.io.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:

            // intialize
            observer.init();
            ...
            // invoke as required
            observer.checkAndNotify();
            ...
            observer.checkAndNotify();
            ...
            // finished
            observer.finish();

  Alternatively, register the oberver(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: FileAlterationObserver.java 1686747 2015-06-21 18:44:49Z krosenvold $
  See Also:
    `FileAlterationListener`, `FileAlterationMonitor`, Serialized Form

- - ### Field Summary

    Fields
    Modifier and Type | Field and Description
    --- | ---
    `private java.util.Comparator<java.io.File>` | `comparator`
    `private java.io.FileFilter` | `fileFilter`
    `private java.util.List<FileAlterationListener>` | `listeners`
    `private FileEntry` | `rootEntry`
    `private static long` | `serialVersionUID`

  - ### Constructor Summary

    Constructors
    Modifier | Constructor and Description
    --- | ---
    `` | `FileAlterationObserver(java.io.File directory)` Construct an observer for the specified directory.
    `protected` | `FileAlterationObserver(FileEntry rootEntry, java.io.FileFilter fileFilter, IOCase caseSensitivity)` Construct an observer for the specified directory, file filter and file comparator.
    `` | `FileAlterationObserver(java.io.File directory, java.io.FileFilter fileFilter)` Construct an observer for the specified directory and file filter.
    `` | `FileAlterationObserver(java.io.File directory, java.io.FileFilter fileFilter, IOCase caseSensitivity)` Construct an observer for the specified directory, file filter and file comparator.
    `` | `FileAlterationObserver(java.lang.String directoryName)` Construct an observer for the specified directory.
    `` | `FileAlterationObserver(java.lang.String directoryName, java.io.FileFilter fileFilter)` Construct an observer for the specified directory and file filter.
    `` | `FileAlterationObserver(java.lang.String directoryName, java.io.FileFilter fileFilter, IOCase caseSensitivity)` Construct an observer for the specified directory, file filter and file comparator.

  - ### Method Summary

    Methods
    Modifier and Type | Method and Description
    --- | ---
    `void` | `addListener(FileAlterationListener listener)` Add a file system listener.
    `void` | `checkAndNotify()` Check whether the file and its chlidren have been created, modified or deleted.
    `private void` | `checkAndNotify(FileEntry parent, FileEntry[] previous, java.io.File[] files)` Compare two file lists for files which have been created, modified or deleted.
    `private FileEntry` | `createFileEntry(FileEntry parent, java.io.File file)` Create a new file entry for the specified file.
    `void` | `destroy()` Final processing.
    `private void` | `doCreate(FileEntry entry)` Fire directory/file created events to the registered listeners.
    `private void` | `doDelete(FileEntry entry)` Fire directory/file delete events to the registered listeners.
    `private FileEntry[]` | `doListFiles(java.io.File file, FileEntry entry)` List the files
    `private void` | `doMatch(FileEntry entry, java.io.File file)` Fire directory/file change events to the registered listeners.
    `java.io.File` | `getDirectory()` Return the directory being observed.
    `java.io.FileFilter` | `getFileFilter()` Return the fileFilter.
    `java.lang.Iterable<FileAlterationListener>` | `getListeners()` Returns the set of registered file system listeners.
    `void` | `initialize()` Initialize the observer.
    `private java.io.File[]` | `listFiles(java.io.File file)` List the contents of a directory
    `void` | `removeListener(FileAlterationListener listener)` Remove a file system listener.
    `java.lang.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`

- - ### Field Detail

    - #### serialVersionUID

          private static final long serialVersionUID

      See Also:
        Constant Field Values

    - #### listeners

          private final java.util.List<FileAlterationListener> listeners

    - #### rootEntry

          private final FileEntry rootEntry

    - #### fileFilter

          private final java.io.FileFilter fileFilter

    - #### comparator

          private final java.util.Comparator<java.io.File> comparator

  - ### Constructor Detail

    - #### FileAlterationObserver

          public FileAlterationObserver(java.lang.String directoryName)

      Construct an observer for the specified directory.
      Parameters:
        `directoryName` - the name of the directory to observe

    - #### FileAlterationObserver

          public FileAlterationObserver(java.lang.String directoryName,
                                java.io.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(java.lang.String directoryName,
                                java.io.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(java.io.File directory)

      Construct an observer for the specified directory.
      Parameters:
        `directory` - the directory to observe

    - #### FileAlterationObserver

          public FileAlterationObserver(java.io.File directory,
                                java.io.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(java.io.File directory,
                                java.io.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,
                                java.io.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 java.io.File getDirectory()

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

    - #### getFileFilter

          public java.io.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 java.lang.Iterable<FileAlterationListener> getListeners()

      Returns the set of registered file system listeners.
      Returns:
        The file system listeners

    - #### initialize

          public void initialize()
                          throws java.lang.Exception

      Initialize the observer.
      Throws:
        `java.lang.Exception` - if an error occurs

    - #### destroy

          public void destroy()
                       throws java.lang.Exception

      Final processing.
      Throws:
        `java.lang.Exception` - if an error occurs

    - #### checkAndNotify

          public void checkAndNotify()

      Check whether the file and its chlidren have been created, modified or deleted.

    - #### checkAndNotify

          private void checkAndNotify(FileEntry parent,
                            FileEntry[] previous,
                            java.io.File[] files)

      Compare two file lists for files which have been created, modified or deleted.
      Parameters:
        `parent` - The parent entry
        `previous` - The original list of files
        `files` - The current list of files

    - #### createFileEntry

          private FileEntry createFileEntry(FileEntry parent,
                                  java.io.File file)

      Create a new file entry for the specified file.
      Parameters:
        `parent` - The parent file entry
        `file` - The file to create an entry for
      Returns:
        A new file entry

    - #### doListFiles

          private FileEntry[] doListFiles(java.io.File file,
                                FileEntry entry)

      List the files
      Parameters:
        `file` - The file to list files for
        `entry` - the parent entry
      Returns:
        The child files

    - #### doCreate

          private void doCreate(FileEntry entry)

      Fire directory/file created events to the registered listeners.
      Parameters:
        `entry` - The file entry

    - #### doMatch

          private void doMatch(FileEntry entry,
                     java.io.File file)

      Fire directory/file change events to the registered listeners.
      Parameters:
        `entry` - The previous file system entry
        `file` - The current file

    - #### doDelete

          private void doDelete(FileEntry entry)

      Fire directory/file delete events to the registered listeners.
      Parameters:
        `entry` - The file entry

    - #### listFiles

          private java.io.File[] listFiles(java.io.File file)

      List the contents of a directory
      Parameters:
        `file` - The file to list the contents of
      Returns:
        the directory contents or a zero length array if the empty or the file is not a directory

    - #### toString

          public java.lang.String toString()

      Provide a String representation of this observer.
      Overrides:
        `toString` in class `java.lang.Object`
      Returns:
        a String representation of this observer

Copyright (c) 2002-2016 Apache Software Foundation