LiveGraph
data visualisation and analysis framework

org.LiveGraph.dataCache
Class DataCache

java.lang.Object
  extended by org.LiveGraph.dataCache.DataCache
All Implemented Interfaces:
EventProducer

public class DataCache
extends java.lang.Object
implements EventProducer

An instance of this class caches datasets previously read from a data file in memory. The cache applies a smart procedure to cache just enough data in order to plot a graph on the screen. Two cache modes are currently possible: CacheTailData and CacheAllData. In the first case the data sets added most recently are cached (and ultimately displayed bythe plotter). In the latter case all datasets are cached. If the number of datasets grows too large, the datasets located at odd indices in the original data file will be deleted from the cache. After this only datasets located at even indices in the original file will be cached. If the cache grows too large again, this procedure is re-applied such that only datasets at indices divisible by 4 in the original file are cached. As more datasets are added to the cache, this procedure can be re-applied again making sure that at any time the original data file is sampled at equal intervals.
The maximum cache size is CACHE_SIZE.

LiveGraph (http://www.live-graph.org).

Copyright (c) 2007 by G. Paperin.

File: DataCache.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)

Nested Class Summary
static class DataCache.CacheMode
          Defines possible cache modes.
private  class DataCache.DataSeriesLabelIterator
          A read-only iterator for data series labels.
private  class DataCache.RemoveRangeArrayList<E>
          A ArrayList which publicly publishes its removeRangeint method.
 
Field Summary
static int CACHE_SIZE
          Maximum number if datasets to be held in memory.
private  int countDelayedEvents
          Number of events that has been delayed during the current bulk operation.
private  DataCache.CacheMode currentMode
          Current operating mode.
private  java.util.List<java.lang.String> dataFileInfo
          Caches the data file info lines.
private  java.util.List<DataSeries> dataSeries
          Stores the desctibtion of the data series in this cache.
private  java.util.List<DataSet> dataSets
          Stores the data in this cache.
private  java.util.Set<CacheEvent> delayedEvents
          Stores occured cache events when operating in the delayed mode.
private  boolean delayEvents
          Whether the cache events are being delayed.
private  int dispersalFactor
          When working in CacheAllData-mode this value determines which datasets are kept in memory.
static int MAX_DELAYED_EVENTS
          Maximum number of delayed events during a bulk operation before the listeners are brought up to date.
private  double maxValueCached
          Caches the largest data value currently in the cache.
private  double minValueCached
          Caches the smallest data value currently in the cache.
static int TAIL_BALANCE_SIZE
          Number of datasets to always keep in memory when operating in CacheTailData-mode.
 
Constructor Summary
DataCache()
          Creates a new data cache in the CacheAllData-mode.
DataCache(DataCache.CacheMode mode)
          Creates a new cache in the specified mode.
DataCache(DataCache.CacheMode mode, java.util.List<java.lang.String> seriesLabels)
          Creates a new cache in a specified mode and initilises it for the specified data series.
DataCache(DataCache.CacheMode mode, java.lang.String[] seriesLabels)
          Creates a new cache in a specified mode and initilises it for the specified data series.
 
Method Summary
 void addDataFileInfo(java.lang.String info)
          Caches info on the data file.
private  boolean addDataSet_AllDataMode(DataSet ds)
          Adds a dataset when cache is in AllDataMode.
private  boolean addDataSet_TailDataMode(DataSet ds)
          Adds a dataset when cache is in TailDataMode.
 void addDataSet(DataSet ds)
          Adds a specified dataset to this cache.
 void bulkOperationCompleted()
          Ends the delayEvents-mode and returns in the normal observable mode; all events cached while in that mode are fired.
 void bulkOperationStart()
          When this method is invoked the cache enters the delayEvents-mode; while in this mode events are not supplied to observers, instead they are cached and fired only when fireDelayedEvents is invoked.
 int countDataSeries()
           
 int countDataSets()
           
 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.
 int findDataSeriesIndex(java.lang.String label)
           
 int findDataSeriesIndex(java.lang.String label, boolean ignoreCase)
           
 DataSet findDataSet(int dataFileIndex)
           
private  void fireEvent(CacheEvent eventType)
          Notifies the observers of a specified event.
 DataCache.CacheMode getCacheMode()
           
 java.lang.String getDataFileInfo()
           
 DataSeries getDataSeries(int index)
           
 DataSet getDataSet(int cacheIndex)
           
 int getMaxDataFileIndex()
           
 double getMaxValueCached()
           
 int getMinDataFileIndex()
           
 double getMinValueCached()
           
private  void includeExtremeValues(DataSet ds)
          Updates the internal state of this cache and its data series to include the min and max values of the specified dataset.
private  void increaseDispersalFactor()
          Increases the value which must divide datafile indices of all cached datasets without remainder.
 com.softnetConsult.utils.collections.ReadOnlyIterator<DataSeries> iterateDataSeries()
           
 com.softnetConsult.utils.collections.ReadOnlyIterator<java.lang.String> iterateDataSeriesLabels()
           
 com.softnetConsult.utils.collections.ReadOnlyIterator<DataSet> iterateDataSets()
           
 java.util.List<java.lang.String> listDataFileInfo()
           
private  void raiseDelayedEvents()
          Raises all events delayed so far during a buld operation:
private  void raiseEvent(CacheEvent eventType)
          Notifies the observers of an event of a specified type.
private  void removeDatalistHead()
          Removes the oldest datasets in this cache.
 void resetCache()
          Removes all data from this cache and resets is to the empty state.
 void resetCache(DataCache.CacheMode mode)
          Removes all data from this cache and resets is to the empty state.
 void resetCache(DataCache.CacheMode mode, java.util.List<java.lang.String> seriesLabels)
          Removes all data from this cache and resets is to the empty state.
 void resetData()
          Resets the cache while keeping the same operating mode.
 void resetData(DataCache.CacheMode mode)
          Resets the cache to the specified mode.
 void resetDataFileInfo()
          Delets all data file info strings held by this cache.
private  void resetExtremeValues()
          Delets the information of min and max values held by this cache and any of its data series.
 void resetLabels()
          Removes all data series informatioon from the cache without deleting the actual data.
 void resetLabels(java.util.List<java.lang.String> seriesLabels)
          Removes all data series informatioon from the cache and replaces is with new empty series.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Field Detail

CACHE_SIZE

public static final int CACHE_SIZE
Maximum number if datasets to be held in memory.

See Also:
Constant Field Values

MAX_DELAYED_EVENTS

public static final int MAX_DELAYED_EVENTS
Maximum number of delayed events during a bulk operation before the listeners are brought up to date.

See Also:
Constant Field Values

TAIL_BALANCE_SIZE

public static final int TAIL_BALANCE_SIZE
Number of datasets to always keep in memory when operating in CacheTailData-mode.

See Also:
Constant Field Values

dataSeries

private java.util.List<DataSeries> dataSeries
Stores the desctibtion of the data series in this cache. A data series corresponds to a column in a data file.


dataSets

private java.util.List<DataSet> dataSets
Stores the data in this cache.


currentMode

private DataCache.CacheMode currentMode
Current operating mode.


dispersalFactor

private int dispersalFactor
When working in CacheAllData-mode this value determines which datasets are kept in memory. At any time, exactly the datasets for which DataSet.getDataFileIndex() returns a value that can be divided by dispersalFactor without remainder will be kept in the cache.


dataFileInfo

private java.util.List<java.lang.String> dataFileInfo
Caches the data file info lines.


minValueCached

private double minValueCached
Caches the smallest data value currently in the cache.


maxValueCached

private double maxValueCached
Caches the largest data value currently in the cache.


delayedEvents

private java.util.Set<CacheEvent> delayedEvents
Stores occured cache events when operating in the delayed mode.


delayEvents

private boolean delayEvents
Whether the cache events are being delayed.


countDelayedEvents

private int countDelayedEvents
Number of events that has been delayed during the current bulk operation.

Constructor Detail

DataCache

public DataCache()
Creates a new data cache in the CacheAllData-mode.


DataCache

public DataCache(DataCache.CacheMode mode)
Creates a new cache in the specified mode.

Parameters:
mode - Mode of the new cache.

DataCache

public DataCache(DataCache.CacheMode mode,
                 java.util.List<java.lang.String> seriesLabels)
Creates a new cache in a specified mode and initilises it for the specified data series.

Parameters:
mode - Mode to use.
seriesLabels - Names of the data series.

DataCache

public DataCache(DataCache.CacheMode mode,
                 java.lang.String[] seriesLabels)
Creates a new cache in a specified mode and initilises it for the specified data series.

Parameters:
mode - Mode to use.
seriesLabels - Names of the data series.
Method Detail

resetCache

public void resetCache()
Removes all data from this cache and resets is to the empty state.


resetCache

public void resetCache(DataCache.CacheMode mode)
Removes all data from this cache and resets is to the empty state.

Parameters:
mode - The mode the cache will have after the reset.

resetCache

public void resetCache(DataCache.CacheMode mode,
                       java.util.List<java.lang.String> seriesLabels)
Removes all data from this cache and resets is to the empty state. New data series are set up according to the specified labels.

Parameters:
mode - The mode the cache will have after the reset.
seriesLabels - The data series labels for the reset cache

resetLabels

public void resetLabels()
Removes all data series informatioon from the cache without deleting the actual data.


resetLabels

public void resetLabels(java.util.List<java.lang.String> seriesLabels)
Removes all data series informatioon from the cache and replaces is with new empty series. Actual data is not affected.

Parameters:
seriesLabels - Labels for the new data series.

resetData

public void resetData()
Resets the cache while keeping the same operating mode. All data is deleted.


resetData

public void resetData(DataCache.CacheMode mode)
Resets the cache to the specified mode. All data is deleted.

Parameters:
mode - New operating mode.

resetExtremeValues

private void resetExtremeValues()
Delets the information of min and max values held by this cache and any of its data series.


resetDataFileInfo

public void resetDataFileInfo()
Delets all data file info strings held by this cache.


getCacheMode

public DataCache.CacheMode getCacheMode()
Returns:
Current operating mode.

countDataSeries

public int countDataSeries()
Returns:
Number of data series in the cache (i.e. data columns in the data file).

iterateDataSeries

public com.softnetConsult.utils.collections.ReadOnlyIterator<DataSeries> iterateDataSeries()
Returns:
a Read-olny iterator over this cache's data series.

getDataSeries

public DataSeries getDataSeries(int index)
Parameters:
index - Data series number (0-based).
Returns:
The data series at the specified index.

iterateDataSeriesLabels

public com.softnetConsult.utils.collections.ReadOnlyIterator<java.lang.String> iterateDataSeriesLabels()
Returns:
An read-only iterator over the labels of the data series in this cache.

findDataSeriesIndex

public int findDataSeriesIndex(java.lang.String label)
Parameters:
label - A data series label.
Returns:
The index of the series with the specified label or -1 if not found.

findDataSeriesIndex

public int findDataSeriesIndex(java.lang.String label,
                               boolean ignoreCase)
Parameters:
label - A data series label.
ignoreCase - Whether case shuld be ignore in string comparison.
Returns:
The index of the series with the specified label or -1 if not found.

countDataSets

public int countDataSets()
Returns:
Number of datasets currently in cache.

iterateDataSets

public com.softnetConsult.utils.collections.ReadOnlyIterator<DataSet> iterateDataSets()
Returns:
Read-only iterator over the datasets in this cache.

getDataSet

public DataSet getDataSet(int cacheIndex)
Parameters:
cacheIndex - Cache-index of a dataset.
Returns:
Dataset at the specified index.

getMinValueCached

public double getMinValueCached()
Returns:
Smallest value currently in the cache or Double.NaN if the cache is empty.

getMaxValueCached

public double getMaxValueCached()
Returns:
Largest value currently in the cache or Double.NaN if the cache is empty.

getMinDataFileIndex

public int getMinDataFileIndex()
Returns:
The index which the first dataset in this chache had in the original datafile.

getMaxDataFileIndex

public int getMaxDataFileIndex()
Returns:
The index that the last dataset in this chache had in the original datafile.

findDataSet

public DataSet findDataSet(int dataFileIndex)
Parameters:
dataFileIndex - An index in the original datafile.
Returns:
A dataset which was located at the specified index in the original data file, or null if there is no such dataset in the cache.

addDataSet

public void addDataSet(DataSet ds)
Adds a specified dataset to this cache.

Parameters:
ds - A dataset.

includeExtremeValues

private void includeExtremeValues(DataSet ds)
Updates the internal state of this cache and its data series to include the min and max values of the specified dataset.

Parameters:
ds - A dataset.

addDataSet_AllDataMode

private boolean addDataSet_AllDataMode(DataSet ds)
Adds a dataset when cache is in AllDataMode.

Parameters:
ds - A dataset.
Returns:
Whether the dataset was actually added.

increaseDispersalFactor

private void increaseDispersalFactor()
Increases the value which must divide datafile indices of all cached datasets without remainder. Datasets with the wrong datafile indices are removed from the cache and the cache indices are updated. This method is used to compact the cache in AllDataMode-mode.


addDataSet_TailDataMode

private boolean addDataSet_TailDataMode(DataSet ds)
Adds a dataset when cache is in TailDataMode.

Parameters:
ds - A dataset.
Returns:
true.

removeDatalistHead

private void removeDatalistHead()
Removes the oldest datasets in this cache. This method is used to compact the cache in AllDataMode-mode.


addDataFileInfo

public void addDataFileInfo(java.lang.String info)
Caches info on the data file.

Parameters:
info - File info.

listDataFileInfo

public java.util.List<java.lang.String> listDataFileInfo()
Returns:
A list of all caches data file info strings.

getDataFileInfo

public java.lang.String getDataFileInfo()
Returns:
The data file info where all cached info strings are separated by new-lines and concatenated into a single string.

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.

fireEvent

private void fireEvent(CacheEvent eventType)
Notifies the observers of a specified event. If this cache is currently in delayEvents mode, the observers are not notified and the event is cached. However, even in the delayEvents-mode, if the number of events delayed so far exceeds MAX_DELAYED_EVENTS, all events delayed so far are fired - this ensured that listeners are brought up to date from time to time during very long bulk operations.

Parameters:
eventType - An event type.

raiseEvent

private void raiseEvent(CacheEvent eventType)
Notifies the observers of an event of a specified type.

Parameters:
eventType - Type of event to raise;

bulkOperationStart

public void bulkOperationStart()
When this method is invoked the cache enters the delayEvents-mode; while in this mode events are not supplied to observers, instead they are cached and fired only when fireDelayedEvents is invoked. This is can be useful when the cache is modified several times in one go. In such case the notification of observers can be consolidated which might save processing similar events many times.

See Also:
bulkOperationCompleted()

bulkOperationCompleted

public void bulkOperationCompleted()
Ends the delayEvents-mode and returns in the normal observable mode; all events cached while in that mode are fired. However, each type of event is fired at most once. The order in which the events are fires is unspecified and might not correspond to the order in which the events actually occured.


raiseDelayedEvents

private void raiseDelayedEvents()
Raises all events delayed so far during a buld operation:


LiveGraph
data visualisation and analysis framework