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:

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

Deprecating Serialization

Serialization is deprecated and will be removed in 3.0.

Since:
2.0
See Also:

  • Field Details

    • serialVersionUID

      private static final long serialVersionUID
      See Also:

    • listeners

      private final transient List<FileAlterationListener> listeners
      List of listeners.

    • rootEntry

      private final FileEntry rootEntry
      The root directory to observe.

    • fileFilter

      private final transient FileFilter fileFilter
      The file filter or null if none.

    • comparator

      private final Comparator<File> comparator
      Compares file names.

  • 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

      private FileAlterationObserver(FileEntry rootEntry, FileFilter fileFilter, Comparator<File> comparator)
      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.
      comparator - How to compare files.

    • 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

    • toComparator

      private static Comparator<File> toComparator(IOCase ioCase)

    • addListener

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

    • checkAndFire

      private void checkAndFire(FileEntry parentEntry, FileEntry[] previousEntries, File[] currentEntries)
      Compares two file lists for files which have been created, modified or deleted.
      Parameters:
      parentEntry - The parent entry.
      previousEntries - The original list of file entries.
      currentEntries - The current list of files entries.

    • checkAndNotify

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

    • createFileEntry

      private FileEntry createFileEntry(FileEntry parent, File file)
      Creates a new file entry for the specified file.
      Parameters:
      parent - The parent file entry.
      file - The file to wrap.
      Returns:
      A new file entry.

    • destroy

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

    • fireOnChange

      private void fireOnChange(FileEntry entry, File file)
      Fires directory/file change events to the registered listeners.
      Parameters:
      entry - The previous file system entry.
      file - The current file.

    • fireOnCreate

      private void fireOnCreate(FileEntry entry)
      Fires directory/file created events to the registered listeners.
      Parameters:
      entry - The file entry.

    • fireOnDelete

      private void fireOnDelete(FileEntry entry)
      Fires directory/file delete events to the registered listeners.
      Parameters:
      entry - The file entry.

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

    • listFileEntries

      private FileEntry[] listFileEntries(File file, FileEntry entry)
      Lists the file entries in file.
      Parameters:
      file - The directory to list.
      entry - the parent entry.
      Returns:
      The child file entries.

    • listFiles

      private File[] listFiles(File directory)
      Lists the contents of a directory.
      Parameters:
      directory - The directory to list.
      Returns:
      the directory contents or a zero length array if the empty or the file is not a directory

    • removeListener

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

    • sort

      private File[] sort(File[] files)

    • toString

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