org.xins.common.io

Class FileWatcher

java.lang.Object

java.lang.Thread

org.xins.common.io.FileWatcher

All Implemented Interfaces:

Runnable

Direct Known Subclasses:

HTTPFileWatcher

public class FileWatcher
extends Thread

File watcher thread.

This thread monitors one or more files, checking them at preset intervals. A listener is notified of the findings.

The check is performed every n seconds, where the interval n can be configured (see setInterval(int) and getInterval()).

Initially this thread will be a daemon thread. This can be changed by calling Thread.setDaemon(boolean).

Since:

XINS 1.0.0

Version:

$Revision: 1.56 $ $Date: 2013/01/04 10:11:15 $

Author:

Ernst de Haan, Anthony Goubard

Nested Class Summary

Nested Classes

Modifier and Type	Class and Description
static interface	FileWatcher.Listener Interface for file watcher listeners.

Nested classes/interfaces inherited from class java.lang.Thread

Thread.State, Thread.UncaughtExceptionHandler

Field Summary

Fields

Modifier and Type	Field and Description
protected String	_filePaths The string representation of the files to watch.
protected long	_lastModified Timestamp of the last modification of the file.

Fields inherited from class java.lang.Thread

MAX_PRIORITY, MIN_PRIORITY, NORM_PRIORITY

Constructor Summary

Constructors

Constructor and Description
FileWatcher(String[] files, int interval, FileWatcher.Listener listener) Creates a new FileWatcher for the specified set of files, with the specified interval.
FileWatcher(String file, FileWatcher.Listener listener) Creates a new FileWatcher for the specified file.
FileWatcher(String file, int interval, FileWatcher.Listener listener) Creates a new FileWatcher for the specified file, with the specified interval.

Method Summary

Methods

Modifier and Type	Method and Description
void	check() Checks if the file changed.
void	end() Stops this thread.
protected void	firstCheck() Performs the first check on the file to determine the date the file was last modified.
int	getInterval() Returns the current interval.
protected long	getLastModified() Gets the time at which the last file was modified.
void	run() Runs this thread.
void	setInterval(int newInterval) Changes the file check interval.
protected void	storeFiles(String[] files) Stores the files in a class variable.

Methods inherited from class java.lang.Thread

activeCount, checkAccess, clone, countStackFrames, currentThread, destroy, dumpStack, enumerate, getAllStackTraces, getContextClassLoader, getDefaultUncaughtExceptionHandler, getId, getName, getPriority, getStackTrace, getState, getThreadGroup, getUncaughtExceptionHandler, holdsLock, interrupt, interrupted, isAlive, isDaemon, isInterrupted, join, join, join, resume, setContextClassLoader, setDaemon, setDefaultUncaughtExceptionHandler, setName, setPriority, setUncaughtExceptionHandler, sleep, sleep, start, stop, stop, suspend, toString, yield

Methods inherited from class java.lang.Object

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

Field Detail

_filePaths

protected String _filePaths

The string representation of the files to watch. Not null.

_lastModified

protected long _lastModified

Timestamp of the last modification of the file. The value -1L indicates that the file could not be found the last time this was checked.

Initially this field is -1L.

Constructor Detail

FileWatcher

public FileWatcher(String file,
           FileWatcher.Listener listener)
            throws IllegalArgumentException

Creates a new FileWatcher for the specified file.

The interval must be set before the thread can be started.

Parameters:

file - the name of the file to watch, cannot be null.

listener - the object to notify on events, cannot be null.

Throws:

IllegalArgumentException - if file == null || listener == null

Since:

XINS 1.2.0

FileWatcher

public FileWatcher(String file,
           int interval,
           FileWatcher.Listener listener)
            throws IllegalArgumentException

Creates a new FileWatcher for the specified file, with the specified interval.

Parameters:

file - the name of the file to watch, cannot be null.

interval - the interval in seconds, must be greater than or equal to 0. if the interval is 0 the interval must be set before the thread can be started.

listener - the object to notify on events, cannot be null.

Throws:

IllegalArgumentException - if file == null || listener == null || interval < 0

FileWatcher

public FileWatcher(String[] files,
           int interval,
           FileWatcher.Listener listener)
            throws IllegalArgumentException

Creates a new FileWatcher for the specified set of files, with the specified interval.

Parameters:

files - the name of the files to watch, cannot be null. It should also have at least one file and none of the file should be null.

interval - the interval in seconds, must be greater than or equal to 0. if the interval is 0 the interval must be set before the thread can be started.

listener - the object to notify on events, cannot be null.

Throws:

IllegalArgumentException - if files == null || listener == null || interval < 0 || files.length < 1 or if one of the file is null.

Method Detail

storeFiles

protected void storeFiles(String[] files)

Stores the files in a class variable.

Parameters:

files - the String files to check, cannot be null.

firstCheck

protected void firstCheck()

Performs the first check on the file to determine the date the file was last modified. This method is called from the constructors. If the file cannot be accessed due to a SecurityException, then this exception is logged and ignored.

run

public void run()
         throws IllegalStateException

Runs this thread. This method should not be called directly, call Thread.start() instead. That method will call this method.

Specified by:

run in interface Runnable

Overrides:

run in class Thread

Throws:

IllegalStateException - if Thread.currentThread() != this, if the thread is already running or should stop, or if the interval was not set yet.

getInterval

public int getInterval()

Returns the current interval.

Returns:

interval the current interval in seconds, always greater than or equal to 1, except if the interval is not initialized yet, in which case 0 is returned.

setInterval

public void setInterval(int newInterval)
                 throws IllegalArgumentException

Changes the file check interval.

Parameters:

newInterval - the new interval in seconds, must be greater than or equal to 1.

Throws:

IllegalArgumentException - if interval < 1

end

public void end()
         throws IllegalStateException

Stops this thread.

Throws:

IllegalStateException - if the thread is currently not running or already stopping.

check

public void check()

Checks if the file changed. The following algorithm is used:

• check if the file is readable;
• if so, then determine when the file was last modified;
• if either the file existence check or the file modification check causes a SecurityException to be thrown, then FileWatcher.Listener.securityException(SecurityException) is called and the method returns;
• otherwise if the file is not readable (it may not exist), then FileWatcher.Listener.fileNotFound() is called and the method returns;
• otherwise if the file is readable, but previously was not, then FileWatcher.Listener.fileFound() is called and the method returns;
• otherwise if the file was modified, then FileWatcher.Listener.fileModified() is called and the method returns;
• otherwise the file was not modified, then FileWatcher.Listener.fileNotModified() is called and the method returns.

Since:

XINS 1.2.0

getLastModified

protected long getLastModified()
                        throws SecurityException

Gets the time at which the last file was modified. If for any reason, a file could no be read -1 is returned.

Returns:

the time of the last modified file or -1.

Throws:

SecurityException - if one of the file could not be read because of a security issue.