LiveGraph
data visualisation and analysis framework

org.LiveGraph.dataCache
Class UpdateInvoker

java.lang.Object
  extended by org.LiveGraph.dataCache.UpdateInvoker
All Implemented Interfaces:
java.lang.Runnable, SettingsObserver

public class UpdateInvoker
extends java.lang.Object
implements java.lang.Runnable, SettingsObserver

An object of this class is used to triger updates from a data input stream into a DataCache at regular intervals.

This product includes software developed by the LiveGraph project and its contributors.
(http://www.live-graph.org)
Copyright (c) 2007 G. Paperin.
All rights reserved.

File: UpdateInvoker.java

Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following terms and conditions are met:

1. Redistributions of source code must retain the above acknowledgement of the LiveGraph project and its web-site, the above copyright notice, this list of conditions and the following disclaimer.
2. Redistributions in binary form must reproduce the above acknowledgement of the LiveGraph project and its web-site, the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution.
3. All advertising materials mentioning features or use of this software or any derived software must display the following acknowledgement:
This product includes software developed by the LiveGraph project and its contributors.
(http://www.live-graph.org)

4. All advertising materials distributed in form of HTML pages or any other technology permitting active hyper-links that mention features or use of this software or any derived software must display the acknowledgment specified in condition 3 of this agreement, and in addition, include a visible and working hyper-link to the LiveGraph homepage (http://www.live-graph.org).

THIS SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESSED OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS, CONTRIBUTORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

Version:
"1.1.1"
Author:
Greg Paperin (http://www.paperin.org)

Field Summary
private  DataCache dataCache
          Cache to hold the data.
private  java.io.File dataFile
          Data file from which to update.
private  DataStreamToCacheReader dataReader
          The data reader for the input stream.
private static long defaultTimeTickLength
          How long to sleep for when updates are to be invoked automatically.
private  boolean dontCache
          Whether cache must be reset before each read.
private  java.lang.Thread fileReadingThread
          Thread actually performing the update.
private  long interval
          Interval between updates in milliseconds.
private  long lastUpdateTime
          System milliseconds at last update.
private  boolean mustQuit
          Whether the invoker thread should wind up at the next possibility.
private  java.util.List<UpdateInvokerObserver> observers
          List of observers.
private  long remainingMillis
          Remaining milliseconds till the next update.
private static long restingTimeTickLength
          How long to sleep for when updates are to be invoked manually.
private  long sinceUpdateTime
          Milliseconds since last update.
private  long timeTickLength
          The sleep length betweek ticks at which this invoker can react to events and send mesages.
private  boolean updateInProgress
          Whether an update is currently running.
 
Constructor Summary
UpdateInvoker()
          Constructs a new invoker.
 
Method Summary
 boolean addObserver(UpdateInvokerObserver observer)
          Add an observer to this invoker.
private  void closeReader()
          Closes the current data reader.
 int countObervers()
          Count observers.
private  void createDataReader()
          Creates a reader on the currently set data input file and resets the cache.
private  void DataFileSettings_DataFile(DataFileSettings settings)
          Adjusts the file used by this invoker in response to a corresponding change in the data file settings.
private  void DataFileSettings_DoNotCacheData(DataFileSettings settings)
          Adjusts the cache resetting option used by this invoker in response to a corresponding change in the data file settings.
private  void DataFileSettings_ShowOnlyTailData(DataFileSettings settings)
          Adjusts the cache mode used by this invoker in response to a corresponding change in the data file settings.
private  void DataFileSettings_UpdateFrequency(DataFileSettings settings)
          Adjusts the update frequency used by this invoker in response to a corresponding change in the data file settings.
 long getInterval()
          The length of the interval between data updates.
 long getRemainingMillis()
          Time to next update.
 boolean hasObserver(UpdateInvokerObserver observer)
          Check for the specified observer.
 boolean isUpdateInProgress()
          Whether an update is currently running.
 void notifyObserversTimerTick()
          Notifies this invoker's observers that this observer has waken up to process events.
 void notifyObserversUpdateFinished(java.lang.String errorMsg)
          Notifies this invoker's observers that an update has finished.
 void notifyObserversUpdateStarted()
          Notifies this invoker's observers that an update was triggered.
 boolean removeObserver(UpdateInvokerObserver observer)
          Removes an observer.
 void run()
          Main invoker loop: call timeTick(); if it is time for the next update, call update(); call timeTick() again and continue the loop until mustQuit is set to true; call tidyUp() before quitting.
 void setDataCache(DataCache cache)
          Specifies the data cache to which the data read on the next update will be written.
 void setDataFile(java.io.File file)
          Sets the file from which the next update will be read and resets the data cache.
 void setDataFile(java.lang.String fileName)
          Sets the file from which the next update will be read and resets the data cache.
 void setDontCacheData(boolean state)
          Sets whether the cache should be reset before each update.
 void setInterval(long interval)
          Sets the length of the interval between automatic data updates in milliseconds.
 void setMustQuit(boolean val)
          Used to notify this invoker that is must stop running at the next possibility.
 void settingHasChanged(DataFileSettings settings, java.lang.String info)
          When the application's data file settings change which method is called in order to update the internal state accordingly.
 void settingHasChanged(ObservableSettings settings, java.lang.Object info)
          Dispatches settings change events.
private  void setUpdateInProgress(boolean state)
          Sets the internal updateInProgress state.
private  void tidyUp()
          Winds up the operations by closing the current data reader.
private  void timeTick()
          Send the this invoker to sleep for timeTickLength milliseconds.
 boolean update()
          Executes the next update from the current input file into the current data cache.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Field Detail

defaultTimeTickLength

private static final long defaultTimeTickLength
How long to sleep for when updates are to be invoked automatically.

See Also:
Constant Field Values

restingTimeTickLength

private static final long restingTimeTickLength
How long to sleep for when updates are to be invoked manually.

See Also:
Constant Field Values

dataReader

private DataStreamToCacheReader dataReader
The data reader for the input stream.


dataCache

private DataCache dataCache
Cache to hold the data.


dataFile

private java.io.File dataFile
Data file from which to update.


dontCache

private boolean dontCache
Whether cache must be reset before each read.


interval

private long interval
Interval between updates in milliseconds.


updateInProgress

private boolean updateInProgress
Whether an update is currently running.


mustQuit

private boolean mustQuit
Whether the invoker thread should wind up at the next possibility.


timeTickLength

private long timeTickLength
The sleep length betweek ticks at which this invoker can react to events and send mesages.


remainingMillis

private long remainingMillis
Remaining milliseconds till the next update.


lastUpdateTime

private long lastUpdateTime
System milliseconds at last update.


sinceUpdateTime

private long sinceUpdateTime
Milliseconds since last update.


fileReadingThread

private java.lang.Thread fileReadingThread
Thread actually performing the update.


observers

private java.util.List<UpdateInvokerObserver> observers
List of observers.

Constructor Detail

UpdateInvoker

public UpdateInvoker()
Constructs a new invoker.

Method Detail

setDataFile

public void setDataFile(java.io.File file)
                 throws java.io.FileNotFoundException
Sets the file from which the next update will be read and resets the data cache.

Parameters:
file - File from which to read the data from now on.
Throws:
java.io.FileNotFoundException - If no such file exists.
java.lang.IllegalStateException - If no valid data cache is set.

setDataFile

public void setDataFile(java.lang.String fileName)
                 throws java.io.FileNotFoundException
Sets the file from which the next update will be read and resets the data cache.

Parameters:
fileName - File from which to read the data from now on.
Throws:
java.io.FileNotFoundException - If no such file exists.
java.lang.IllegalStateException - If no valid data cache is set.

setDontCacheData

public void setDontCacheData(boolean state)
Sets whether the cache should be reset before each update.

Parameters:
state - Indicates whether the cache should be reset before each update.

setDataCache

public void setDataCache(DataCache cache)
Specifies the data cache to which the data read on the next update will be written.

Parameters:
cache - The data cache to use from now on.

setInterval

public void setInterval(long interval)
Sets the length of the interval between automatic data updates in milliseconds. If interval <= 0 the update will not be triggered automatically.

Parameters:
interval - The length of the interval between automatic data updates in milliseconds (if interval <= 0 the update will not be triggered automatically).

createDataReader

private void createDataReader()
                       throws java.io.FileNotFoundException
Creates a reader on the currently set data input file and resets the cache.

Throws:
java.io.FileNotFoundException - If the input file does not exist.

getInterval

public long getInterval()
The length of the interval between data updates. If interval <= 0 the update will not be triggered automatically.

Returns:
The length of the interval between automatic data updates in milliseconds; a value interval <= 0 indicated that no updates will be triggered automatically.

update

public boolean update()
Executes the next update from the current input file into the current data cache.

Returns:
true if the update was started successfully, false if the update could not be started (possibly, because a previous update was still in progress).

addObserver

public boolean addObserver(UpdateInvokerObserver observer)
Add an observer to this invoker.

Parameters:
observer - Observer to add.
Returns:
Whether the observer was really added because it was not there yet.

hasObserver

public boolean hasObserver(UpdateInvokerObserver observer)
Check for the specified observer.

Parameters:
observer - An observer.
Returns:
Whether the specified observer is in the observer list.

removeObserver

public boolean removeObserver(UpdateInvokerObserver observer)
Removes an observer.

Parameters:
observer - An observer.
Returns:
Whether the observer was successfully removed.

countObervers

public int countObervers()
Count observers.

Returns:
Current number of observers.

notifyObserversTimerTick

public void notifyObserversTimerTick()
Notifies this invoker's observers that this observer has waken up to process events. This gives listeners displaying various information about this invoker a chance to update their state.


notifyObserversUpdateStarted

public void notifyObserversUpdateStarted()
Notifies this invoker's observers that an update was triggered.


notifyObserversUpdateFinished

public void notifyObserversUpdateFinished(java.lang.String errorMsg)
Notifies this invoker's observers that an update has finished.

Parameters:
errorMsg - Describes any problems during the update. If there were no problems errorMsg will be null.

setMustQuit

public void setMustQuit(boolean val)
Used to notify this invoker that is must stop running at the next possibility.

Parameters:
val - Whether this invoker should stop running at the next possibility.

getRemainingMillis

public long getRemainingMillis()
Time to next update.

Returns:
Number of milliseconds left until the next update.

isUpdateInProgress

public boolean isUpdateInProgress()
Whether an update is currently running.

Returns:
Whether an update is currently running.

setUpdateInProgress

private void setUpdateInProgress(boolean state)
Sets the internal updateInProgress state.

Parameters:
state - The new state.

closeReader

private void closeReader()
Closes the current data reader.


tidyUp

private void tidyUp()
Winds up the operations by closing the current data reader.


timeTick

private void timeTick()
Send the this invoker to sleep for timeTickLength milliseconds. When it wakes it, internal time state is updated an the observers notified.


run

public void run()
Main invoker loop: call timeTick(); if it is time for the next update, call update(); call timeTick() again and continue the loop until mustQuit is set to true; call tidyUp() before quitting.

Specified by:
run in interface java.lang.Runnable

settingHasChanged

public void settingHasChanged(ObservableSettings settings,
                              java.lang.Object info)
Dispatches settings change events.

Specified by:
settingHasChanged in interface SettingsObserver
Parameters:
settings - The settings object that was changed.
info - Is used to further specify the change. Usually this is a String containing the name of the changed setting.

settingHasChanged

public void settingHasChanged(DataFileSettings settings,
                              java.lang.String info)
When the application's data file settings change which method is called in order to update the internal state accordingly.

Parameters:
settings - Application's data file settings.
info - Describes the change event.

DataFileSettings_DataFile

private void DataFileSettings_DataFile(DataFileSettings settings)
Adjusts the file used by this invoker in response to a corresponding change in the data file settings.

Parameters:
settings - The data file settigs.

DataFileSettings_UpdateFrequency

private void DataFileSettings_UpdateFrequency(DataFileSettings settings)
Adjusts the update frequency used by this invoker in response to a corresponding change in the data file settings.

Parameters:
settings - The data file settigs.

DataFileSettings_DoNotCacheData

private void DataFileSettings_DoNotCacheData(DataFileSettings settings)
Adjusts the cache resetting option used by this invoker in response to a corresponding change in the data file settings.

Parameters:
settings - The data file settigs.

DataFileSettings_ShowOnlyTailData

private void DataFileSettings_ShowOnlyTailData(DataFileSettings settings)
Adjusts the cache mode used by this invoker in response to a corresponding change in the data file settings.

Parameters:
settings - The data file settigs.

LiveGraph
data visualisation and analysis framework