Package org.apache.commons.io.monitor

Class 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 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:
    FileAlterationListener, FileAlterationMonitor, Serialized Form

    • Field Detail

      • rootEntry

        private final FileEntry rootEntry
        The root directory to observe.

      • fileFilter

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

      • comparator

        private final java.util.Comparator<java.io.File> comparator
        Compares file names.

    • Constructor Detail

      • FileAlterationObserver

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

      • FileAlterationObserver

        @Deprecated
public FileAlterationObserver​(java.io.File directory,
                              java.io.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​(java.io.File directory,
                              java.io.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,
                               java.io.FileFilter fileFilter,
                               java.util.Comparator<java.io.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,
                                 java.io.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​(java.lang.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​(java.lang.String directoryName,
                              java.io.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​(java.lang.String directoryName,
                              java.io.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 Detail

      • toComparator

        private static java.util.Comparator<java.io.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,
                          java.io.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,
                                  java.io.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 java.lang.Exception
        Final processing.
        Throws:
        java.lang.Exception - if an error occurs.

      • fireOnChange

        private void fireOnChange​(FileEntry entry,
                          java.io.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

        java.util.Comparator<java.io.File> getComparator()

      • getDirectory

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

      • getFileFilter

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

      • 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
        Initializes the observer.
        Throws:
        java.lang.Exception - if an error occurs.

      • listFileEntries

        private FileEntry[] listFileEntries​(java.io.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 java.io.File[] listFiles​(java.io.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 java.io.File[] sort​(java.io.File[] files)

      • toString

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