LiveGraph
data visualisation and analysis framework

org.LiveGraph.dataCache
Class DataStreamToCacheReader

java.lang.Object
  extended by org.LiveGraph.dataCache.DataStreamToCacheReader
All Implemented Interfaces:
DataStreamObserver, EventListener, EventProducer

public class DataStreamToCacheReader
extends java.lang.Object
implements DataStreamObserver, EventListener, EventProducer

This reader will parse a data stream using DataStreamReader and store all information in a data cache for further processing by the application.

See DataStreamWriter for the details of the data file format.

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: DataStreamToCacheReader.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 cache
          Cache for storage of extracted data.
static long maxWaitForUpdate
          The maximum period of time the reader will wait to be able to do an update before canceling the update.
private  DataStreamReader previousReader
          Data reader used for the previous update.
private  boolean updateInProgress
          Whether an update is currently running.
 
Constructor Summary
DataStreamToCacheReader(DataCache cache)
          Creates a data reader on the specified stream.
 
Method Summary
 boolean checkEventInterest(Event<? extends EventType> event)
          Does nothing.
 boolean checkEventValid(Event<? extends EventType> event, boolean soFar)
          Does nothing.
private  boolean checkReaderOpen(DataStreamReader reader)
          Checks whether the specified reader is still open by trying to execute an action on it.
private  Event<DataUpdateEvent> checkUpdateCanStart(DataStreamReader reader)
          Verifies that an update may begin by first checking whether another update is not in progress and then requesting all event listeners to verify a UPDIN_UpdateStart-event.
 void completedRegisterWithEventManager(EventManager manager)
          Does nothing.
 void completedUnregisterWithEventManager(EventManager manager)
          Does nothing.
private  Event<DataUpdateEvent> doCheckUpdateCanStart()
          Used by checkUpdateCanStart: Verifies that an update may begin by first checking whether another update is not in progress and then requesting all event listeners to verify a UPDIN_UpdateStart-event.
 void eventCommentLine(java.lang.String line, DataStreamReader reader)
          Used for callback by the DataStreamReader; does nothing.
 void eventDataLineRead(java.util.List<java.lang.String> dataTokens, int datasetIndex, DataStreamReader reader)
          Used for callback by the DataStreamReader; adds a dataset to the cache.
 void eventFileInfoLine(java.lang.String info, DataStreamReader reader)
          Used for callback by the DataStreamReader; adds a file info line to the cache.
 void eventLabelsSet(java.util.List<java.lang.String> labels, DataStreamReader reader)
          Used for callback by the DataStreamReader; setts the data column labels in the cache.
 boolean eventProcessingException(Event<? extends EventType> event, EventProcessingException exception)
          Does nothing.
 void eventProcessingFinished(Event<? extends EventType> event)
          Does nothing.
 void eventRaised(Event<? extends EventType> event)
          Processes LiveGraph events.
 void eventSeparatorSet(java.lang.String separator, DataStreamReader reader)
          Used for callback by the DataStreamReader; does nothing.
 boolean isUpdateInProgress()
          Whether an update is currently running.
 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 processDataUpdateEvent(Event<DataUpdateEvent> event)
          Attempts to initiate an update when a UPDIN_InitiateUpdate-event is received.
private  void raiseUpdateFinishedError(java.lang.Throwable err)
          Raises an event to notify listeners that an update has finished with errors.
private  void raiseUpdateFinishedSusccess()
          Raises an event to notify listeners that an update has finished without any errors.
private  void readFromStream(DataStreamReader reader, boolean closeAfterRead)
          Reads as many data lines from the underlying stream as there are available, parses the lines and stores the extracted information (if any) in this reader's data cache.
private  void setUpdateInProgress(boolean state)
          Sets the internal updateInProgress state.
private  void startDataUpdate(DataStreamReader reader, boolean closeAfterRead)
          Attempts to initiate a data update in a new thread.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Field Detail

maxWaitForUpdate

public static final long maxWaitForUpdate
The maximum period of time the reader will wait to be able to do an update before canceling the update.

See Also:
Constant Field Values

cache

private DataCache cache
Cache for storage of extracted data.


updateInProgress

private boolean updateInProgress
Whether an update is currently running.


previousReader

private DataStreamReader previousReader
Data reader used for the previous update.

Constructor Detail

DataStreamToCacheReader

public DataStreamToCacheReader(DataCache cache)
Creates a data reader on the specified stream.

Parameters:
cache - The data cache into which to store the data.
Method Detail

readFromStream

private void readFromStream(DataStreamReader reader,
                            boolean closeAfterRead)
                     throws java.io.IOException,
                            DataFormatException
Reads as many data lines from the underlying stream as there are available, parses the lines and stores the extracted information (if any) in this reader's data cache.

Parameters:
reader - Data source.
closeAfterRead - Whether to close reader after reading.
Throws:
java.io.IOException - If an I/O error occurs.
DataFormatException - If the data stream contents do not conform with the expected data stream format.
See Also:
DataStreamWriter, DataStreamReader

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.

checkReaderOpen

private boolean checkReaderOpen(DataStreamReader reader)
Checks whether the specified reader is still open by trying to execute an action on it.

Parameters:
reader - A data stream reader.
Returns:
true if the reader is not closed, false otherwise.

doCheckUpdateCanStart

private Event<DataUpdateEvent> doCheckUpdateCanStart()
Used by checkUpdateCanStart: Verifies that an update may begin by first checking whether another update is not in progress and then requesting all event listeners to verify a UPDIN_UpdateStart-event.

Returns:
A readily validated event of type DataUpdateEvent.UPDIN_UpdateStart if an update may begin, null if the verification was not successfull.

checkUpdateCanStart

private Event<DataUpdateEvent> checkUpdateCanStart(DataStreamReader reader)
Verifies that an update may begin by first checking whether another update is not in progress and then requesting all event listeners to verify a UPDIN_UpdateStart-event. If the verification is not successful, the method pauses the current thread and then reattempts the verification. This may be repeated several times. If the verification was not successfull after maxWaitForUpdate milliseconds, it will be regarded as failed. This private method assumes that the calling method has synchronised on this.

Parameters:
reader - Data source for the update.
Returns:
A readily validated event of type DataUpdateEvent.UPDIN_UpdateStart if an update may begin, null otherwise.

startDataUpdate

private void startDataUpdate(DataStreamReader reader,
                             boolean closeAfterRead)
Attempts to initiate a data update in a new thread. First this method verifies that no other update is already in progress, then it validates a UPDIN_UpdateStart-event against all listeners. If both succeeds, a new thread is started that will read the stream into the cache. The verification may be attempted several times, but no longer than maxWaitForUpdate milliseconds.

Parameters:
reader - Data source.
closeAfterRead - Whether to close reader after reading.

raiseUpdateFinishedSusccess

private void raiseUpdateFinishedSusccess()
Raises an event to notify listeners that an update has finished without any errors.


raiseUpdateFinishedError

private void raiseUpdateFinishedError(java.lang.Throwable err)
Raises an event to notify listeners that an update has finished with errors.

Parameters:
err - The Throwable describing the error.

eventCommentLine

public void eventCommentLine(java.lang.String line,
                             DataStreamReader reader)
Used for callback by the DataStreamReader; does nothing.

Specified by:
eventCommentLine in interface DataStreamObserver
Parameters:
line - The comment line.
reader - The reader which produced this event.

eventDataLineRead

public void eventDataLineRead(java.util.List<java.lang.String> dataTokens,
                              int datasetIndex,
                              DataStreamReader reader)
Used for callback by the DataStreamReader; adds a dataset to the cache.

Specified by:
eventDataLineRead in interface DataStreamObserver
Parameters:
dataTokens - An unmodifiable list containing all data tokens parsed from this line.
datasetIndex - The number of this data line in the stream (i.e. dataset file index).
reader - The reader which produced this event.

eventFileInfoLine

public void eventFileInfoLine(java.lang.String info,
                              DataStreamReader reader)
Used for callback by the DataStreamReader; adds a file info line to the cache.

Specified by:
eventFileInfoLine in interface DataStreamObserver
Parameters:
info - File description/info string.
reader - The reader which produced this event.

eventLabelsSet

public void eventLabelsSet(java.util.List<java.lang.String> labels,
                           DataStreamReader reader)
Used for callback by the DataStreamReader; setts the data column labels in the cache.

Specified by:
eventLabelsSet in interface DataStreamObserver
Parameters:
labels - An unmodifiable list containing all parsed data series labels.
reader - The reader which produced this event.

eventSeparatorSet

public void eventSeparatorSet(java.lang.String separator,
                              DataStreamReader reader)
Used for callback by the DataStreamReader; does nothing.

Specified by:
eventSeparatorSet in interface DataStreamObserver
Parameters:
separator - The new data values separator string.
reader - The reader which produced this event.

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)
Does nothing.

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:
true.
See Also:
EventListener.checkEventValid(Event, boolean)

eventRaised

public void eventRaised(Event<? extends EventType> event)
                 throws java.lang.Exception
Processes LiveGraph events.

Specified by:
eventRaised in interface EventListener
Parameters:
event - The event to process.
Throws:
java.lang.Exception

processDataUpdateEvent

private void processDataUpdateEvent(Event<DataUpdateEvent> event)
Attempts to initiate an update when a UPDIN_InitiateUpdate-event is received.

Parameters:
event - The event to process.

eventProcessingException

public boolean eventProcessingException(Event<? extends EventType> event,
                                        EventProcessingException exception)
Does nothing.

Specified by:
eventProcessingException in interface EventProducer
Parameters:
event - Event that cause an exception.
exception - The exception.
Returns:
false.

eventProcessingFinished

public void eventProcessingFinished(Event<? extends EventType> event)
Does nothing.

Specified by:
eventProcessingFinished in interface EventProducer
Parameters:
event - Event that was processed.

LiveGraph
data visualisation and analysis framework