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(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:
          // 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.
    Since:
    2.0
    See Also:
    FileAlterationListener, FileAlterationMonitor, Serialized Form
    • Constructor Summary

      Constructors 
      Modifier Constructor Description
        FileAlterationObserver​(java.io.File directory)
      Constructs an observer for the specified directory.
        FileAlterationObserver​(java.io.File directory, java.io.FileFilter fileFilter)
      Constructs an observer for the specified directory and file filter.
        FileAlterationObserver​(java.io.File directory, java.io.FileFilter fileFilter, IOCase caseSensitivity)
      Constructs an observer for the specified directory, file filter and file comparator.
        FileAlterationObserver​(java.lang.String directoryName)
      Constructs an observer for the specified directory.
        FileAlterationObserver​(java.lang.String directoryName, java.io.FileFilter fileFilter)
      Constructs 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.
      protected FileAlterationObserver​(FileEntry rootEntry, java.io.FileFilter fileFilter, IOCase caseSensitivity)
      Constructs an observer for the specified directory, file filter and file comparator.
    • Constructor Detail

      • FileAlterationObserver

        public FileAlterationObserver​(java.lang.String directoryName)
        Constructs 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)
        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

        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)
        Constructs an observer for the specified directory.
        Parameters:
        directory - the directory to observe
      • FileAlterationObserver

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

        public FileAlterationObserver​(java.io.File directory,
                                      java.io.FileFilter fileFilter,
                                      IOCase caseSensitivity)
        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
        caseSensitivity - what case sensitivity to use comparing file names, null means system sensitive
      • FileAlterationObserver

        protected FileAlterationObserver​(FileEntry rootEntry,
                                         java.io.FileFilter fileFilter,
                                         IOCase caseSensitivity)
        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
        caseSensitivity - what case sensitivity to use comparing file names, null means system sensitive
    • Method Detail

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

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

        public void removeListener​(FileAlterationListener listener)
        Removes 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
        Initializes 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()
        Checks whether the file and its children have been created, modified or deleted.
      • 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