Package ca.cgjennings.io

Class FileChangeMonitor

  • public class FileChangeMonitor
extends java.lang.Object
    Listeners that register a file with a FileChangeMonitor receive notification when it changes.
    Author:
    Chris Jennings

    • Nested Class Summary

      Nested Classes 
      Modifier and Type Class Description
      static class  FileChangeMonitor.ChangeType
      The kind of change detected by the monitor.

    • Field Summary

      Fields 
      Modifier and Type Field Description
      protected java.util.Map<java.lang.String,​ca.cgjennings.io.FileChangeMonitor.MonitorTask> taskMap
      Map from listeners to their tasks.
      protected java.util.Timer timer
      The timer that triggers file checks.

    • Constructor Summary

      Constructors 
      Constructor Description
      FileChangeMonitor()
      Creates a new file change monitor which is independent of the shared instance.

    • Field Detail

      • timer

        protected java.util.Timer timer
        The timer that triggers file checks.

      • taskMap

        protected java.util.Map<java.lang.String,​ca.cgjennings.io.FileChangeMonitor.MonitorTask> taskMap
        Map from listeners to their tasks.

    • Constructor Detail

      • FileChangeMonitor

        public FileChangeMonitor()
        Creates a new file change monitor which is independent of the shared instance. It is generally preferable to use the shared instance.
        See Also:
        getSharedInstance()

    • Method Detail

      • getSharedInstance

        public static FileChangeMonitor getSharedInstance()
        Return a shared instance of FileChangeMonitor.
        Returns:
        an shared instance

      • setDefaultCheckPeriod

        public static void setDefaultCheckPeriod​(long periodInMS)
        Sets a hint describing how often files should be checked for changes by default. Note that this class makes no guarantee about how it monitors files for changes, so this value may have no effect.
        Parameters:
        periodInMS - the default check period, in milliseconds

      • getDefaultCheckPeriod

        public static long getDefaultCheckPeriod()
        Returns a hint describing how often files should be checked for changes by default. Note that this class makes no guarantee about how it monitors files for changes, so this value may have no effect. (It will only have an effect if the class must poll the file system for changes, and even then the exact delay between checks cannot be guaranteed.)
        Returns:
        periodInMS the default check period, in milliseconds

      • dispose

        public void dispose()
        Removes all listeners being monitored and ends the monitoring thread. Once a monitor has been disposed, it cannot have any more listeners added. If this method is called on the shared instance, it will throw an UnsupportedOperationException.
        Throws:
        java.lang.UnsupportedOperationException - if called on getSharedInstance()

      • addFileChangeListener

        public void addFileChangeListener​(FileChangeListener listener,
                                  java.io.File file,
                                  long updatePeriod)
        Begin monitoring a file for changes. Changes will cause the listener's FileChangeListener.fileChanged(java.io.File, ca.cgjennings.io.FileChangeMonitor.ChangeType) method to be called. The value of updatePeriod is an approximate maximum delay, in milliseconds, before a change in file state is detected. The monitor does not guarantee that updatePeriod will be honoured. If listener has already been registered to monitor file, the existing monitor will be removed and it will be replaced by one with the new updatePeriod. If the updatePeriod is 0, then the monitor is not added (it is removed if it already exists).
        Parameters:
        listener - the listener to notify when file changes
        file - the file to monitor
        updatePeriod - the approximate maximum delay before change notification takes place
        Throws:
        java.lang.NullPointerException - if listener or file is null
        java.lang.IllegalArgumentException - if updatePeriod is negative
        java.lang.IllegalStateException - if this monitor has been dispose()d of
        See Also:
        getDefaultCheckPeriod()

      • removeFileChangeListener

        public void removeFileChangeListener​(FileChangeListener listener,
                                     java.io.File file)
        Stop monitoring a specific file registered with this listener. Note that the listener might be called one more time after this method is called if a file change was already being handled when the method was called.
        Parameters:
        listener - the listener to stop notifying
        file - the file to stop notifying the listener about

      • removeFileChangeListener

        public void removeFileChangeListener​(FileChangeListener listener)
        Stop monitoring all files that are registered with a listener. This is more efficient than removing each file individually.
        Parameters:
        listener - the listener to stop monitoring

      • purge

        public void purge()
        Remove all monitor tasks that are no longer valid because the listener was garbage collected without removing itself. This may be done automatically from time to time, but you can force it to occur at any time by calling this method.