LiveGraph
data visualisation and analysis framework

org.LiveGraph.dataCache
Class DataCache

java.lang.Object
  extended by org.LiveGraph.dataCache.DataCache

public class DataCache
extends java.lang.Object

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:
"1.1.1"
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  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<CacheObserver.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.
private  double maxValueCached
          Caches the largest data value currently in the cache.
private  double minValueCached
          Caches the smallest data value currently in the cache.
private  java.util.List<CacheObserver> observers
           
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.
 boolean addObserver(CacheObserver observer)
          Adds an observer to this cache.
 int countDataSeries()
           
 int countDataSets()
           
 int countObservers()
           
 int findDataSeriesIndex(java.lang.String label)
           
 int findDataSeriesIndex(java.lang.String label, boolean ignoreCase)
           
 DataSet findDataSet(int dataFileIndex)
           
 void fireDelayedEvents()
          Ends the delayEvents-mode and returns in the normal observable mode; all events cached while in that mode are fired.
 void fireEvent(CacheObserver.CacheEvent event)
          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()
           
 java.util.List<CacheObserver> getObservers()
           
 boolean hasObserver(CacheObserver observer)
           
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 removeDatalistHead()
          Removes the oldest datasets in this cache.
 boolean removeObserver(CacheObserver observer)
           
 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.
 void startDelayEvents()
          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.
 
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

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

observers

private java.util.List<CacheObserver> observers

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<CacheObserver.CacheEvent> delayedEvents
Stores occured cache events when operating in the delayed mode.


delayEvents

private boolean delayEvents
Whether the cache events are being delayed.

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 which 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.

addObserver

public boolean addObserver(CacheObserver observer)
Adds an observer to this cache.

Parameters:
observer - An observer.
Returns:
Whether the observer was really added because is was not yet on the list.

hasObserver

public boolean hasObserver(CacheObserver observer)
Parameters:
observer - An observer.
Returns:
Whether this cache already has the specified observer.

removeObserver

public boolean removeObserver(CacheObserver observer)
Parameters:
observer - An observer to remove.
Returns:
Whther teh observer was there as was removed.

countObservers

public int countObservers()
Returns:
Number of observers.

getObservers

public java.util.List<CacheObserver> getObservers()
Returns:
Read-only list of observers.

fireEvent

public void fireEvent(CacheObserver.CacheEvent event)
Notifies the observers of a specified event. If this cache is currently in delayEvents mode, the observers are not notyfied and the event is cached.

Parameters:
event - An event.

startDelayEvents

public void startDelayEvents()
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:
fireDelayedEvents()

fireDelayedEvents

public void fireDelayedEvents()
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.


LiveGraph
data visualisation and analysis framework