com.mucommander.file.util
Class FileMonitor

java.lang.Object
  com.mucommander.file.util.FileMonitor

All Implemented Interfaces:

FileMonitorConstants, java.lang.Runnable

public class FileMonitor
extends java.lang.Object
implements FileMonitorConstants, java.lang.Runnable

FileMonitor allows to monitor a file and detect changes in the file's attributes and notify registered FileChangeListener listeners accordingly.

FileMonitor detects attributes changes by polling the file's attributes at a given frequency and comparing their values with the previous ones. If any of the monitored attributes has changed, FileChangeListener.fileChanged(AbstractFile, int) is called on each of the registered listeners to notify them of the file attributes that have changed.
Here's the list of file attributes that can be monitored:

• FileMonitorConstants.DATE_ATTRIBUTE
• FileMonitorConstants.SIZE_ATTRIBUTE
• FileMonitorConstants.PERMISSIONS_ATTRIBUTE
• FileMonitorConstants.IS_DIRECTORY_ATTRIBUTE
• FileMonitorConstants.EXISTS_ATTRIBUTE

The polling frequency is controlled by the poll period. This parameter determines how often the file's attributes are checked. The lower this period is, the faster changes will be reported to listeners, but also the higher the impact on I/O and CPU. This parameter should be carefully specified to avoid hogging resources excessively.

Note that FileMonitor uses file attributes polling because the Java API doesn't currently provide any better way to do detect file changes. If Java ever does provide a callback mechanism for detecting file changes, this class will be modified to take advantage of it. Another possible improvement would be to add JNI hooks for platform-specific filesystem events such as 'inotify' (Linux Kernel), 'kqueue' (BSD, Mac OS X), PAM (Solaris), ...

Author:

Maxence Bernard

See Also:

FileChangeListener

Field Summary

Fields inherited from interface com.mucommander.file.util.FileMonitorConstants

ALL_ATTRIBUTES, DATE_ATTRIBUTE, DEFAULT_ATTRIBUTES, DEFAULT_POLL_PERIOD, EXISTS_ATTRIBUTE, IS_DIRECTORY_ATTRIBUTE, PERMISSIONS_ATTRIBUTE, SIZE_ATTRIBUTE

Constructor Summary

FileMonitor(AbstractFile file)
Creates a new FileMonitor that monitors the given file for changes, using the default attribute set (as defined by FileMonitorConstants.DEFAULT_ATTRIBUTES) and default poll period (as defined by FileMonitorConstants.DEFAULT_POLL_PERIOD).

FileMonitor(AbstractFile file, int attributes)
Creates a new FileMonitor that monitors the given file for changes, using the specified attribute set and default poll period as defined by FileMonitorConstants.DEFAULT_POLL_PERIOD.

FileMonitor(AbstractFile file, int attributes, long pollPeriod)
Creates a new FileMonitor that monitors the given file for changes, using the specified attribute set and poll period.

FileMonitor(AbstractFile file, long pollPeriod)
Creates a new FileMonitor that monitors the given file for changes, using the specified poll period and default attribute set as defined by FileMonitorConstants.DEFAULT_ATTRIBUTES).

Method Summary

void	addFileChangeListener(FileChangeListener listener) Adds the given FileChangeListener instance to the list of registered listeners.
boolean	isMonitoring() Returns true if this FileMonitor is currently monitoring the file.
void	removeFileChangeListener(FileChangeListener listener) Removes the given FileChangeListener instance to the list of registered listeners.
void	run()
void	startMonitoring() Starts monitoring the monitored file in a dedicated thread.
void	stopMonitoring() Stops monitoring the monitored file.

Methods inherited from class java.lang.Object

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

Constructor Detail

FileMonitor

public FileMonitor(AbstractFile file)

Creates a new FileMonitor that monitors the given file for changes, using the default attribute set (as defined by FileMonitorConstants.DEFAULT_ATTRIBUTES) and default poll period (as defined by FileMonitorConstants.DEFAULT_POLL_PERIOD).

See the general constructor FileMonitor(AbstractFile, int, long) for more information.

Parameters:

file - the AbstractFile to monitor for changes

FileMonitor

public FileMonitor(AbstractFile file,
                   int attributes)

Creates a new FileMonitor that monitors the given file for changes, using the specified attribute set and default poll period as defined by FileMonitorConstants.DEFAULT_POLL_PERIOD.

See the general constructor FileMonitor(AbstractFile, int, long) for more information.

Parameters:

file - the AbstractFile to monitor for changes

attributes - the set of attributes to monitor, see constant fields for a list of possible attributes

FileMonitor

public FileMonitor(AbstractFile file,
                   long pollPeriod)

Creates a new FileMonitor that monitors the given file for changes, using the specified poll period and default attribute set as defined by FileMonitorConstants.DEFAULT_ATTRIBUTES).

See the general constructor FileMonitor(AbstractFile, int, long) for more information.

Parameters:

file - the AbstractFile to monitor for changes

pollPeriod - number of milliseconds between two file attributes polls

FileMonitor

public FileMonitor(AbstractFile file,
                   int attributes,
                   long pollPeriod)

Creates a new FileMonitor that monitors the given file for changes, using the specified attribute set and poll period.

Note that monitoring will only start after startMonitoring() has been called.

The following attributes can be monitored:

• FileMonitorConstants.DATE_ATTRIBUTE
• FileMonitorConstants.SIZE_ATTRIBUTE
• FileMonitorConstants.PERMISSIONS_ATTRIBUTE
• FileMonitorConstants.IS_DIRECTORY_ATTRIBUTE
• FileMonitorConstants.EXISTS_ATTRIBUTE

Several attributes can be specified by combining them with the binary OR operator.

The poll period specified in the constructor determines how often the file's attributes will be checked. The lower this period is, the faster changes will be reported to registered listeners, but also the higher the impact on I/O and CPU.
Note that the time spent for polling is taken into account for the poll period. For example, if the poll period is 1000ms, and polling the file's attributes took 50ms, the next poll will happen in 950ms.

Parameters:

file - the AbstractFile to monitor for changes

attributes - the set of attributes to monitor, see constant fields for a list of possible attributes

pollPeriod - number of milliseconds between two file attributes polls

Method Detail

addFileChangeListener

public void addFileChangeListener(FileChangeListener listener)

Adds the given FileChangeListener instance to the list of registered listeners.

Listeners are stored as weak references so removeFileChangeListener(FileChangeListener) doesn't need to be called for listeners to be garbage collected when they're not used anymore.

Parameters:

listener - the FileChangeListener to add to the list of registered listeners.

See Also:

removeFileChangeListener(FileChangeListener)

removeFileChangeListener

public void removeFileChangeListener(FileChangeListener listener)

Removes the given FileChangeListener instance to the list of registered listeners.

Parameters:

listener - the FileChangeListener to remove from the list of registered listeners.

See Also:

addFileChangeListener(FileChangeListener)

startMonitoring

public void startMonitoring()

Starts monitoring the monitored file in a dedicated thread. Does nothing if monitoring has already been started and not stopped yet. Calling this method after stopMonitoring() has been called will resume monitoring.

Once started, the monitoring thread will check for changes in the monitored file attributes specified in the constructor, and call registered FileChangeListener instances whenever a change in one or several attributes has been detected. The poll period specified in the constructor determines how often the file's attributes will be checked.

This method waits until the thread is started effectively and the monitor is ready to monitor file changes. This guarantees that all changes made to the monitored file after this method returns will be caught and properly reported to listeners.

FileMonitor will keep monitoring the file until stopMonitoring() is called, even if the monitored file doesn't exist anymore. Thus, it is important not to forget to call stopMonitoring() when monitoring is not needed anymore, in order to prevent unnecessary resource hogging.

stopMonitoring

public void stopMonitoring()

Stops monitoring the monitored file. Does nothing if monitoring has not yet been started.

isMonitoring

public boolean isMonitoring()

Returns true if this FileMonitor is currently monitoring the file.

Returns:

true if this FileMonitor is currently monitoring the file.

run

public void run()

Specified by:

run in interface java.lang.Runnable