Overview | Package | Class | Use | Tree | Deprecated | Index | Help
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

## 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 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 1304052 2012-03-22 20:55:29Z ggregory $
See Also:
  `FileAlterationListener`, `FileAlterationMonitor`, Serialized Form

Constructor Summary
`` | `FileAlterationObserver(File directory)` Construct an observer for the specified directory.
`protected` | `FileAlterationObserver(FileEntry rootEntry, FileFilter fileFilter, IOCase caseSensitivity)` Construct an observer for the specified directory, file filter and file comparator.
`` | `FileAlterationObserver(File directory, FileFilter fileFilter)` Construct an observer for the specified directory and file filter.
`` | `FileAlterationObserver(File directory, FileFilter fileFilter, IOCase caseSensitivity)` Construct an observer for the specified directory, file filter and file comparator.
`` | `FileAlterationObserver(String directoryName)` Construct an observer for the specified directory.
`` | `FileAlterationObserver(String directoryName, FileFilter fileFilter)` Construct an observer for the specified directory and file filter.
`` | `FileAlterationObserver(String directoryName, FileFilter fileFilter, IOCase caseSensitivity)` Construct an observer for the specified directory, file filter and file comparator.

Method Summary
`void` | `addListener(FileAlterationListener listener)` Add a file system listener.
`void` | `checkAndNotify()` Check whether the file and its chlidren have been created, modified or deleted.
`void` | `destroy()` Final processing.
`File` | `getDirectory()` Return the directory being observed.
`FileFilter` | `getFileFilter()` Return the fileFilter.
`Iterable<FileAlterationListener>` | `getListeners()` Returns the set of registered file system listeners.
`void` | `initialize()` Initialize the observer.
`void` | `removeListener(FileAlterationListener listener)` Remove a file system listener.
`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`

Constructor Detail

### FileAlterationObserver

    public FileAlterationObserver(String directoryName)

  Construct an observer for the specified directory.

  Parameters:
    `directoryName` - the name of the directory to observe

### FileAlterationObserver

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

  Construct an observer for the specified directory.

  Parameters:
    `directory` - the directory to observe

### FileAlterationObserver

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

  Return the directory being observed.

  Returns:
    the directory being observed

### getFileFilter

    public 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 Iterable<FileAlterationListener> getListeners()

  Returns the set of registered file system listeners.

  Returns:
    The file system listeners

### initialize

    public void initialize()
                    throws Exception

  Initialize the observer.

  Throws:
    `Exception` - if an error occurs

### destroy

    public void destroy()
                 throws Exception

  Final processing.

  Throws:
    `Exception` - if an error occurs

### checkAndNotify

    public void checkAndNotify()

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

### toString

    public String toString()

  Provide a String representation of this observer.

  Overrides:
    `toString` in class `Object`
  Returns:
    a String representation of this observer

Overview | Package | Class | Use | Tree | Deprecated | Index | Help
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

Copyright © 2002-2012 The Apache Software Foundation. All Rights Reserved.