FileAlterationObserver

java.lang.Object
- org.apache.commons.io.monitor.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:
- 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(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 Summary

Fields
Modifier and Type	Field and Description
`private java.util.Comparator<java.io.File>`	`comparator` Compares file names.
`private java.io.FileFilter`	`fileFilter` The file filter or null if none.
`private java.util.List<FileAlterationListener>`	`listeners` List of listeners.
`private FileEntry`	`rootEntry` The root directory to observe.
`private static long`	`serialVersionUID`

Constructor Summary

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

Method Summary

All Methods Static Methods Instance Methods Concrete Methods
Modifier and Type	Method and Description
`void`	`addListener(FileAlterationListener listener)` Adds a file system listener.
`private void`	`checkAndFire(FileEntry parentEntry, FileEntry[] previousEntries, java.io.File[] currentEntries)` Compares two file lists for files which have been created, modified or deleted.
`void`	`checkAndNotify()` Checks whether the file and its children have been created, modified or deleted.
`private FileEntry`	`createFileEntry(FileEntry parent, java.io.File file)` Creates a new file entry for the specified file.
`void`	`destroy()` Final processing.
`private void`	`fireOnChange(FileEntry entry, java.io.File file)` Fires directory/file change events to the registered listeners.
`private void`	`fireOnCreate(FileEntry entry)` Fires directory/file created events to the registered listeners.
`private void`	`fireOnDelete(FileEntry entry)` Fires directory/file delete events to the registered listeners.
`java.io.File`	`getDirectory()` Returns the directory being observed.
`java.io.FileFilter`	`getFileFilter()` Returns the fileFilter.
`java.lang.Iterable<FileAlterationListener>`	`getListeners()` Returns the set of registered file system listeners.
`void`	`initialize()` Initializes the observer.
`private FileEntry[]`	`listFileEntries(java.io.File file, FileEntry entry)` Lists the file entries in `file`.
`private java.io.File[]`	`listFiles(java.io.File directory)` Lists the contents of a directory.
`void`	`removeListener(FileAlterationListener listener)` Removes a file system listener.
`private java.io.File[]`	`sort(java.io.File[] files)`
`private static java.util.Comparator<java.io.File>`	`toComparator(IOCase ioCase)`
`java.lang.String`	`toString()` Returns a String representation of this observer.

Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

- Field Detail
  - serialVersionUID
```
private static final long serialVersionUID
```
    See Also:
    
    Constant Field Values
  - listeners
```
private final transient java.util.List<FileAlterationListener> listeners
```
    List of listeners.
  - 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
```
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 ioCase)
```
    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
```
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 ioCase)
```
    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.
  - 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.

Class FileAlterationObserver

Basic Usage

File Filters

FileEntry

Deprecating Serialization

Field Summary

Constructor Summary

Method Summary

Methods inherited from class java.lang.Object

Field Detail

serialVersionUID

listeners

rootEntry

fileFilter

comparator

Constructor Detail

FileAlterationObserver

FileAlterationObserver

FileAlterationObserver

FileAlterationObserver

FileAlterationObserver

FileAlterationObserver

FileAlterationObserver

FileAlterationObserver

Method Detail

toComparator

addListener

checkAndFire

checkAndNotify

createFileEntry

destroy

fireOnChange

fireOnCreate

fireOnDelete

getDirectory

getFileFilter

getListeners

initialize

listFileEntries

listFiles

removeListener

sort

toString