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, EventListener, EventProducer

public class UpdateInvoker
extends java.lang.Object
implements java.lang.Runnable, EventListener, EventProducer

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-2008 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:
"2.0.beta01"
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  DataStreamReader dataReader
          The data reader for the input stream.
private  long interval
          Interval between updates in milliseconds.
private  long lastUpdateTime
          System milliseconds at last update.
private  boolean memoryStreamMode
          Determines wether the invoker is in memory-stream mode.
private  boolean mustQuit
          Whether the invoker thread should wind up at the next possibility.
private  long remainingMillis
          Remaining milliseconds till the next update.
private  long sinceUpdateTime
          Milliseconds since last update.
private static long timeTickLength
          How long to sleep for when updates are to be invoked automatically.
 
Constructor Summary
UpdateInvoker(DataCache cache)
          Constructs a new invoker.
 
Method Summary
 boolean checkEventInterest(Event<? extends EventType> event)
          Does nothing.
 boolean checkEventValid(Event<? extends EventType> event, boolean soFar)
          Validates (or not) settings event.
private  void closeDataReader()
           
 void completedRegisterWithEventManager(EventManager manager)
          Does nothing.
 void completedUnregisterWithEventManager(EventManager manager)
          Does nothing.
 boolean endMemoryStreamMode()
           
 boolean eventProcessingException(Event<? extends EventType> event, EventProcessingException exception)
          Objects of this class do not handle eventProcessingException notofications.
 void eventProcessingFinished(Event<? extends EventType> event)
          Objects of this class do not handle eventProcessingFinished notifications.
 void eventRaised(Event<? extends EventType> event)
          Processes events.
 long getInterval()
          The length of the interval between data updates.
 long getRemainingMillis()
          Time to next update.
private  boolean openDataFileReader()
          Creates a new DataStreamToCacheReader for a stream on the currently set data file.
 boolean permissionRegisterWithEventManager(EventManager manager)
          Permits to register as listener with the main LiveGraph event manager and only with the main LiveGraph event manager.
 boolean permissionUnregisterWithEventManager(EventManager manager)
          Does not permit any unregistering.
private  void processSettingsEvent(Event<SettingsEvent> event)
          When the application's settings change, this method is called in order to update the internal state accordingly.
private  void raiseCannotInitiateUpdate(java.lang.String message)
           
private  void raiseTimerTick()
          Raises an event to notify listeners that this invoker has waken up to process events.
 boolean ready()
          Tells whether this invoker's reader's underlying data stream is ready to be read.
 void requestUpdate()
          Raises a UPDIN_InitiateUpdate-event to notify the DataStreamToCacheReader that it is time for a data update.
private  void resetCache(DataCache.CacheMode mode)
           
 void run()
          Main invoker loop: call timeTick(); if it is time for the next update, call requestUpdate(); call timeTick() again and continue the loop until mustQuit is set to true; call tidyUp() before quitting.
private  void setDataFile(java.lang.String fileName)
          Sets the file from which the next update will be read and closes the previously used reader.
private  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.
 DataStreamWriter startMemoryStreamMode()
          Uses a pipe buffer of 5 MB.
 boolean startMemoryStreamMode(java.io.InputStream in)
           
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.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Field Detail

timeTickLength

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

See Also:
Constant Field Values

memoryStreamMode

private boolean memoryStreamMode
Determines wether the invoker is in memory-stream mode.

See Also:
startMemoryStreamMode(InputStream)

dataReader

private DataStreamReader 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.


interval

private long interval
Interval between updates in milliseconds.


mustQuit

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


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.

Constructor Detail

UpdateInvoker

public UpdateInvoker(DataCache cache)
Constructs a new invoker.

Parameters:
cache - The application's data cache.
Method Detail

setInterval

private 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).

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.

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.

resetCache

private void resetCache(DataCache.CacheMode mode)

setDataFile

private void setDataFile(java.lang.String fileName)
Sets the file from which the next update will be read and closes the previously used reader.

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

closeDataReader

private void closeDataReader()

ready

public boolean ready()
              throws java.io.IOException
Tells whether this invoker's reader's underlying data stream is ready to be read.

Returns:
true if the next readFromStream() is guaranteed not to block for input, false otherwise. Note that returning false does not guarantee that the next read will block.
Throws:
java.io.IOException - If an I/O error occurs.

raiseCannotInitiateUpdate

private void raiseCannotInitiateUpdate(java.lang.String message)

openDataFileReader

private boolean openDataFileReader()
Creates a new DataStreamToCacheReader for a stream on the currently set data file. Called by requestUpdate() either when no data reader is available (dataReader is null), or if a data reader is available, but "do not cacha data" is activated.

Returns:
true if a data reader was opened, false if a data reader could not be successfully opened (also raises an UPDIN_CannotInitiateUpdate-event).

requestUpdate

public void requestUpdate()
Raises a UPDIN_InitiateUpdate-event to notify the DataStreamToCacheReader that it is time for a data update.


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.


raiseTimerTick

private void raiseTimerTick()
Raises an event to notify listeners that this invoker has waken up to process events. This gives listeners displaying various information about this invoker a chance to update their state.


tidyUp

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


run

public void run()
Main invoker loop: call timeTick(); if it is time for the next update, call requestUpdate(); 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

startMemoryStreamMode

public DataStreamWriter startMemoryStreamMode()
Uses a pipe buffer of 5 MB. To customise the buffer size, create your own streams and use startMemoryStreamMode(InputStream) to initiate the memory stream mode.

Returns:
xxx

startMemoryStreamMode

public boolean startMemoryStreamMode(java.io.InputStream in)
                              throws java.io.IOException
Throws:
java.io.IOException

endMemoryStreamMode

public boolean endMemoryStreamMode()

permissionRegisterWithEventManager

public boolean permissionRegisterWithEventManager(EventManager manager)
Permits to register as listener with the main LiveGraph event manager and only with the main LiveGraph event manager.

Specified by:
permissionRegisterWithEventManager in interface EventListener
Parameters:
manager - The EventManager for the registering attempt.
Returns:
(LiveGraph.application().eventManager() == manager).
See Also:
EventListener.permissionRegisterWithEventManager(EventManager)

permissionUnregisterWithEventManager

public boolean permissionUnregisterWithEventManager(EventManager manager)
Does not permit any unregistering.

Specified by:
permissionUnregisterWithEventManager in interface EventListener
Parameters:
manager - The EventManager for the registering attempt.
Returns:
false.
See Also:
EventListener.permissionUnregisterWithEventManager(EventManager)

completedRegisterWithEventManager

public void completedRegisterWithEventManager(EventManager manager)
Does nothing.

Specified by:
completedRegisterWithEventManager in interface EventListener
Parameters:
manager - The EventManager with which this EventListener is now registered.
See Also:
EventListener.completedRegisterWithEventManager(EventManager)

completedUnregisterWithEventManager

public void completedUnregisterWithEventManager(EventManager manager)
Does nothing.

Specified by:
completedUnregisterWithEventManager in interface EventListener
Parameters:
manager - The EventManager with which this EventListener is now unregistered.
See Also:
EventListener.completedUnregisterWithEventManager(EventManager)

checkEventInterest

public boolean checkEventInterest(Event<? extends EventType> event)
Does nothing.

Specified by:
checkEventInterest in interface EventListener
Parameters:
event - An event in which this EventListener may be interested.
Returns:
false.
See Also:
EventListener.checkEventInterest(Event)

checkEventValid

public boolean checkEventValid(Event<? extends EventType> event,
                               boolean soFar)
Validates (or not) settings event. When in "memory stream mode" this invoker will not valudate changing of cache mode (all-data/tail-only or cache/dont-cache) or changing the data file.

Specified by:
checkEventValid in interface EventListener
Parameters:
event - The event to be validated.
soFar - Whether event has been successfuly validated by whichever EventListeners (if any) were invoked to validate event before this EventListener.
Returns:
false if this invoker is in memoryStreamMode and if the event is of the types [DFS_DataFile, DFS_DoNotCacheData, DFS_ShowOnlyTailData, DFS_Load].
See Also:
EventListener.checkEventValid(Event, boolean)

eventRaised

public void eventRaised(Event<? extends EventType> event)
Processes events.

Specified by:
eventRaised in interface EventListener
Parameters:
event - Event to process.

processSettingsEvent

private void processSettingsEvent(Event<SettingsEvent> event)
When the application's settings change, this method is called in order to update the internal state accordingly.

Parameters:
event - Describes the change event.

eventProcessingFinished

public void eventProcessingFinished(Event<? extends EventType> event)
Objects of this class do not handle eventProcessingFinished notifications.

Specified by:
eventProcessingFinished in interface EventProducer
Parameters:
event - Ignored.

eventProcessingException

public boolean eventProcessingException(Event<? extends EventType> event,
                                        EventProcessingException exception)
Objects of this class do not handle eventProcessingException notofications.

Specified by:
eventProcessingException in interface EventProducer
Parameters:
event - Ignored.
exception - Never actually thrown.
Returns:
false.

LiveGraph
data visualisation and analysis framework