classpathhelper.filechangelistener
Class FileChangeMonitor

java.lang.Object
  classpathhelper.filechangelistener.FileChangeMonitor

public class FileChangeMonitor

extends java.lang.Object

Utility class used to monitor files, or files within directories. When file changes are detected FileChangedEvent events are fired to registered IFileChangeListener listeners.

The frequency (in time) with which scans for changes occur as well how many scans to wait before reporting changes are both configurable at construction time.

Usage

A single instance of FileChangeMonitor can monitor several files and directories located in many locations. First create an instance and register one or more listeners.

   FileChangeMonitor monitor = new FileChangeMonitor();
   monitor.addFileChangeListener(listener);
 

Then add the files or directories that should be monitored.

   monitor.addSource("/somefile.txt");
   monitor.addSource("/somedir");
 

It is also possible to use standard java.io.FileFilter and java.io.FilenameFilter instances when monitoring directories to restrict which files are viewed.

   // add directory only monitoring jar files.
   monitor.addSource("/lib", new FileNameFilter() {
       public boolean accept(File dir, String name) {
           return name.endsWith(".jar");
       }
   });
 

By default a monitored directory will not recursively monitor sub directories. Passing in true when a directory is specified will monitor all sub files and directories.

   monitor.addSource("/classes", true);
 

When using recursive monitoring, FileFilter and FilenameFilter will also restrict which subdirectories are monitored.

Starting and Stopping

Once a monitor is constructed and sources have been added to the monitor it needs to be started. A monitor can also be temporarily stopped (and subsequently restarted).

When a monitor is nolonger needed it should be cancelled. A cancelled monitor cannot be restarted.

Implementation Notes

This class uses a Timer for scheduling and performing the monitoring tasks.

Since:

1.0

Author:

bharris

Constructor Summary

FileChangeMonitor()
Creates a monitor using the default (60s) scan rate and default (2 scans) quiescent count.

FileChangeMonitor(long theScanRate, int theQuiescentScans)
Creates a monitor specifying the scan rate and the quiescent scan count.

Method Summary

void	addFileChangeListener(IFileChangeListener listener) Adds a listener for file change events.
void	addSource(java.io.File file) Adds a new file or directory to be monitored for changes.
void	addSource(java.io.File file, boolean includeSubDirs) Adds a new directory for monitoring, while explicitly indicating whether or not subdirectories should also be scanned.
void	addSource(java.io.File file, boolean includeSubDirs, java.io.FileFilter filter) Adds a new directory for monitoring, while explicitly indicating whether or not subdirectories should also be scanned.
void	addSource(java.io.File file, boolean includeSubDirs, java.io.FilenameFilter filter) Adds a new directory for monitoring, while explicitly indicating whether or not subdirectories should also be scanned.
void	addSource(java.io.File file, java.io.FileFilter filter) Adds a new directory for monitoring, while providing a filter that will restrict which files are monitored.
void	addSource(java.io.File file, java.io.FilenameFilter filter) Adds a new directory for monitoring, while providing a filter that will restrict which files are monitored.
void	addSource(java.lang.String file) Adds a new file or directory to be monitored for changes.
void	addSource(java.lang.String file, boolean includeSubDirs) Adds a new directory for monitoring, while explicitly indicating whether or not subdirectories should also be scanned.
void	addSource(java.lang.String file, boolean includeSubDirs, java.io.FileFilter filter) Adds a new directory for monitoring, while explicitly indicating whether or not subdirectories should also be scanned.
void	addSource(java.lang.String file, boolean includeSubDirs, java.io.FilenameFilter filter) Adds a new directory for monitoring, while explicitly indicating whether or not subdirectories should also be scanned.
void	addSource(java.lang.String file, java.io.FileFilter filter) Adds a new directory for monitoring, while providing a filter that will restrict which files are monitored.
void	addSource(java.lang.String file, java.io.FilenameFilter filter) Adds a new directory for monitoring, while providing a filter that will restrict which files are monitored.
void	cancel() Call used to permanently stop a monitor.
protected void	finalize()
protected void	firePendingFileChangedEvents() Fires all pending events to all registered listeners.
protected void	monitor() Internal method (actually called by the timer thread when its schedule task is running) that performs the actualy file monitoring.
protected void	postFileChangedEvent(FileChangedEvent evt) Method called from the sub monitors to post an event (for later firing to the listeners).
boolean	removeFileChangeListener(IFileChangeListener listener) Removes a previously registered listener.
void	startMonitor() Call used to start the process of monitoring files previously added via addSource().
void	stopMonitor() Call used to stop a previously started monitor.

Methods inherited from class java.lang.Object

clone, equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

FileChangeMonitor

public FileChangeMonitor()

Creates a monitor using the default (60s) scan rate and default (2 scans) quiescent count.

see FileChangeMonitor(long, int) for more information on scan and quiescent scan values.

Since:

1.0

FileChangeMonitor

public FileChangeMonitor(long theScanRate,
                         int theQuiescentScans)

Creates a monitor specifying the scan rate and the quiescent scan count.

Parameters:

theScanRate - The time in milliseconds to wait between scanning for changes.

theQuiescentScans - The number of scans (with no changes detected) before reporting changes. It is sometimes useful to wait for changes to settle down before reporting them (e.g. if every file change triggers an expensive operation).

Since:

1.0

Method Detail

addSource

public void addSource(java.lang.String file)

Adds a new file or directory to be monitored for changes.

Parameters:

file - The path to a file or directory.

Since:

1.0

addSource

public void addSource(java.lang.String file,
                      boolean includeSubDirs)

Adds a new directory for monitoring, while explicitly indicating whether or not subdirectories should also be scanned.

Parameters:

file - The directory path.

includeSubDirs - flag indicating whether or not to include recursive subdirectories in monitoring.

Throws:

java.lang.IllegalArgumentException - If file does not specify a directory and includeSubDirs is true.

Since:

1.0

addSource

public void addSource(java.lang.String file,
                      java.io.FileFilter filter)

Adds a new directory for monitoring, while providing a filter that will restrict which files are monitored.

Parameters:

file - The directory path.

filter - The filter used to restrict the files to monitor.

Throws:

java.lang.IllegalArgumentException - If file does not specify a directory and filter is not null.

Since:

1.0

addSource

public void addSource(java.lang.String file,
                      boolean includeSubDirs,
                      java.io.FileFilter filter)

Adds a new directory for monitoring, while explicitly indicating whether or not subdirectories should also be scanned.

Parameters:

file - The directory path.

includeSubDirs - flag indicating whether or not to include recursive subdirectories in monitoring.

filter - The filter used to restrict the files to monitor.

Throws:

java.lang.IllegalArgumentException - If file does not specify a directory and includeSubDirs is true or filter is not null.

Since:

1.0

addSource

public void addSource(java.lang.String file,
                      java.io.FilenameFilter filter)

Adds a new directory for monitoring, while providing a filter that will restrict which files are monitored.

Parameters:

file - The directory path.

filter - The filter used to restrict the files to monitor.

Throws:

java.lang.IllegalArgumentException - If file does not specify a directory and filter is not null.

Since:

1.0

addSource

public void addSource(java.lang.String file,
                      boolean includeSubDirs,
                      java.io.FilenameFilter filter)

Adds a new directory for monitoring, while explicitly indicating whether or not subdirectories should also be scanned.

Parameters:

file - The directory path.

includeSubDirs - flag indicating whether or not to include recursive subdirectories in monitoring.

filter - The filter used to restrict the files to monitor.

Throws:

java.lang.IllegalArgumentException - If file does not specify a directory and includeSubDirs is true or filter is not null.

Since:

1.0

addSource

public void addSource(java.io.File file)

Adds a new file or directory to be monitored for changes.

Parameters:

file - The file or directory.

Since:

1.0

addSource

public void addSource(java.io.File file,
                      boolean includeSubDirs)

Adds a new directory for monitoring, while explicitly indicating whether or not subdirectories should also be scanned.

Parameters:

file - The directory.

includeSubDirs - flag indicating whether or not to include recursive subdirectories in monitoring.

Throws:

java.lang.IllegalArgumentException - If file does not specify a directory and includeSubDirs is true.

Since:

1.0

addSource

public void addSource(java.io.File file,
                      java.io.FileFilter filter)

Adds a new directory for monitoring, while providing a filter that will restrict which files are monitored.

Parameters:

file - The directory.

filter - The filter used to restrict the files to monitor.

Throws:

java.lang.IllegalArgumentException - If file does not specify a directory and filter is not null.

Since:

1.0

addSource

public void addSource(java.io.File file,
                      boolean includeSubDirs,
                      java.io.FileFilter filter)

Adds a new directory for monitoring, while explicitly indicating whether or not subdirectories should also be scanned.

Parameters:

file - The directory.

includeSubDirs - flag indicating whether or not to include recursive subdirectories in monitoring.

filter - The filter used to restrict the files to monitor.

Throws:

java.lang.IllegalArgumentException - If file does not specify a directory and includeSubDirs is true or filter is not null.

Since:

1.0

addSource

public void addSource(java.io.File file,
                      java.io.FilenameFilter filter)

Adds a new directory for monitoring, while providing a filter that will restrict which files are monitored.

Parameters:

file - The directory.

filter - The filter used to restrict the files to monitor.

Throws:

java.lang.IllegalArgumentException - If file does not specify a directory and filter is not null.

Since:

1.0

addSource

public void addSource(java.io.File file,
                      boolean includeSubDirs,
                      java.io.FilenameFilter filter)

Adds a new directory for monitoring, while explicitly indicating whether or not subdirectories should also be scanned.

Parameters:

file - The directory.

includeSubDirs - flag indicating whether or not to include recursive subdirectories in monitoring.

filter - The filter used to restrict the files to monitor.

Throws:

java.lang.IllegalArgumentException - If file does not specify a directory and includeSubDirs is true or filter is not null.

Since:

1.0

addFileChangeListener

public void addFileChangeListener(IFileChangeListener listener)

Adds a listener for file change events.

Parameters:

listener - The listener.

Since:

1.0

removeFileChangeListener

public boolean removeFileChangeListener(IFileChangeListener listener)

Removes a previously registered listener.

Parameters:

listener - The listener to remove.

Returns:

true if the listener was previously registred and successfully removed. Otherwise false

Since:

1.0

startMonitor

public void startMonitor()

Call used to start the process of monitoring files previously added via addSource(). This method can also be called to restart the monitor after a call to stopMonitor().

Since:

1.0

stopMonitor

public void stopMonitor()

Call used to stop a previously started monitor.

Since:

1.0

cancel

public void cancel()

Call used to permanently stop a monitor. A call to cancel does not need to be proceeded by stopMonitor(). Once a monitor is cancelled it should be discared.

Since:

1.0

monitor

protected void monitor()

Internal method (actually called by the timer thread when its schedule task is running) that performs the actualy file monitoring.

Since:

1.0

postFileChangedEvent

protected void postFileChangedEvent(FileChangedEvent evt)

Method called from the sub monitors to post an event (for later firing to the listeners).

Parameters:

evt - The event to post.

Since:

1.0

firePendingFileChangedEvents

protected void firePendingFileChangedEvents()

Fires all pending events to all registered listeners.

Since:

1.0

finalize

protected void finalize()
                 throws java.lang.Throwable

Throws:

java.lang.Throwable