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

    • 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

        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

      • checkAndNotify

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

      • destroy

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

      • 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

      • initialize

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

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