LiveGraph
data visualisation and analysis framework

org.LiveGraph.dataFile.read
Class DataStreamReader

java.lang.Object
  extended by org.LiveGraph.dataFile.read.DataStreamReader
All Implemented Interfaces:
java.io.Closeable

public class DataStreamReader
extends java.lang.Object
implements java.io.Closeable

A reader for a data stream (usually, a CSV file). This reader will parse the data stream and extract the file information, the data series headings and the actual data.

The information extracted from the data stream is passed to the application using an observer pattern: after a line was parsed, the appropriate notifyXXXX(...)-method of this class is called with the extracted information. The notifyXXXX(...)-methods dispatch appropriate notifications to all DataStreamObserver-objects registered with this DataStreamReader-instance.
If required, an application may also overwrite the notifyXXXX(...)-methods to handle data read events.

See DataStreamWriter for the details of the data file format.

Note, that this class has a different role than it did in version 1.01 of the LiveGraph API. The DataStreamReader class from version 1.01 is replaced by DataStreamToCacheReader.

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

Copyright (c) 2007 by G. Paperin.

File: DataStreamReader.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)
See Also:
DataStreamObserver, DataStreamObserverAdapter, DataStreamToCacheReader

Field Summary
private  java.io.BufferedReader in
          Data stream reader.
private  boolean labelsSet
          Whether the data series headings are already set-up.
private  int nextDatasetFileIndex
          The data stream index of the next data record.
private  java.util.List<DataStreamObserver> observers
          Observers who want to know what's on the data stream.
private  java.lang.String separator
          Data values separator.
private  boolean separatorSet
          Whether the data values separator was already finalised.
 
Constructor Summary
DataStreamReader(java.io.InputStream is)
          Creates a data reader on the specified stream.
DataStreamReader(java.io.InputStream is, DataStreamObserver observer)
          Creates a data reader on the specified stream and add one initial observer.
 
Method Summary
 boolean addObserver(DataStreamObserver observer)
          Adds an observer to this parser.
 void close()
          Closes the underlying data stream.
static java.util.List<java.lang.Double> convertTokensToDoubles(java.util.List<java.lang.String> tokens)
          This static utility method converts a list of String tokens (presumably just parsed from a data line) to a list of Double objects containing the tokens' values; tokens that cannot be parsed to a Double are represented by null-objects in the resulting list.
 int countObservers()
          Counts this parser's observers.
static java.util.List<java.lang.String> createUniqueLabels(java.util.List<java.lang.String> rawLabels, boolean allowEmptyLabels)
          This static utility method converts a list of strings (presumably representing a list of labels just parsed from the data file) to a list of strings where each string is unique in respect to its equals method (case sensitive); this happens by attaching counters to repreated strings: for instance, ["boo", "foo", "boo"] it converted to ["boo (1)", "foo", "boo (2)"].
 boolean hasObserver(DataStreamObserver observer)
          Checks whether the specified observer is registered with this parser.
protected  void notifyCommentLine(java.lang.String comment)
          Notifies observers regestered with this parser of a "comment line parsed"-event.
protected  void notifyDataLineRead(java.util.List<java.lang.String> dataTokens, int datasetIndex)
          Notifies observers regestered with this parser of a "dataset parsed"-event.
protected  void notifyFileInfoLine(java.lang.String info)
          Notifies observers regestered with this parser of a "file info line parsed"-event.
protected  void notifyLabelsSet(java.util.List<java.lang.String> labels)
          Notifies observers regestered with this parser of a "data series labels parsed"-event.
protected  void notifySeparatorSet(java.lang.String separator)
          Notifies observers regestered with this parser of a "data values separator set"-event.
private  void processCommentLine(java.lang.String line)
          Parses a comments line.
private  void processDataLine(java.lang.String line)
          Parses a data line.
private  void processFileInfoLine(java.lang.String line)
          Parses a file information line.
private  void processLine(java.lang.String line)
          Examines a data line and dispatches to a specialised parsing routine.
private  void processSeparatorDefinitionLine(java.lang.String line)
          Parses a data values separator definition line.
private  void processSeriesLabelsLine(java.lang.String line)
          Parses a data series headings line.
 int readFromStream()
          Reads as many data lines from the underlying stream as there are available and parses them.
 int readFromStream(int maxLines)
          Reads up to a specified number of data lines from the underlying stream, and parses the lines.
 boolean ready()
          Tells whether this reader's underlying data stream is ready to be read.
 boolean removeObserver(DataStreamObserver observer)
          De-registeres the specified observer from this parser.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Field Detail

in

private java.io.BufferedReader in
Data stream reader.


separator

private java.lang.String separator
Data values separator.


separatorSet

private boolean separatorSet
Whether the data values separator was already finalised.


labelsSet

private boolean labelsSet
Whether the data series headings are already set-up.


nextDatasetFileIndex

private int nextDatasetFileIndex
The data stream index of the next data record.


observers

private java.util.List<DataStreamObserver> observers
Observers who want to know what's on the data stream.

Constructor Detail

DataStreamReader

public DataStreamReader(java.io.InputStream is)
Creates a data reader on the specified stream.

Parameters:
is - The stream from which to read.

DataStreamReader

public DataStreamReader(java.io.InputStream is,
                        DataStreamObserver observer)
Creates a data reader on the specified stream and add one initial observer.

Parameters:
is - The stream from which to read.
observer - An observer for the data stream contents.
Method Detail

ready

public boolean ready()
              throws java.io.IOException
Tells whether this 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.

close

public void close()
           throws java.io.IOException
Closes the underlying data stream. Further reading is not possible after calling this method.

Specified by:
close in interface java.io.Closeable
Throws:
java.io.IOException - If an I/O error occurs.

readFromStream

public int readFromStream()
                   throws java.io.IOException,
                          DataFormatException
Reads as many data lines from the underlying stream as there are available and parses them.

Returns:
The number on non-empty data lines read.
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, readFromStream(int)

readFromStream

public int readFromStream(int maxLines)
                   throws java.io.IOException,
                          DataFormatException
Reads up to a specified number of data lines from the underlying stream, and parses the lines. Reading is stopped when the specified number of lines in reached or if no more lines are available.

Parameters:
maxLines - The maximum number of data lines to read (empty lines are ignored and not counted, but all other lines including comment lines are counted). If negative, all available lines will be read.
Returns:
The number on non-empty data lines read.
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

notifySeparatorSet

protected void notifySeparatorSet(java.lang.String separator)
Notifies observers regestered with this parser of a "data values separator set"-event.

Parameters:
separator - New data separator to be passed to the observers.

notifyCommentLine

protected void notifyCommentLine(java.lang.String comment)
Notifies observers regestered with this parser of a "comment line parsed"-event.

Parameters:
comment - The parsed comment line to be passed to the observers.

notifyFileInfoLine

protected void notifyFileInfoLine(java.lang.String info)
Notifies observers regestered with this parser of a "file info line parsed"-event.

Parameters:
info - The parsed file info to be passed to the observers.

notifyLabelsSet

protected void notifyLabelsSet(java.util.List<java.lang.String> labels)
Notifies observers regestered with this parser of a "data series labels parsed"-event.

Parameters:
labels - The parsed data series labels to be passed to the observers.

notifyDataLineRead

protected void notifyDataLineRead(java.util.List<java.lang.String> dataTokens,
                                  int datasetIndex)
Notifies observers regestered with this parser of a "dataset parsed"-event.

Parameters:
dataTokens - The parsed data tokens to be passed to the observers.
datasetIndex - The file index of the parsed dataset to be passed to the observers.

addObserver

public boolean addObserver(DataStreamObserver observer)
Adds an observer to this parser.

Parameters:
observer - The observer to add.
Returns:
if the specified observer cound not be added because it was already registered, true otherwise.

hasObserver

public boolean hasObserver(DataStreamObserver observer)
Checks whether the specified observer is registered with this parser.

Parameters:
observer - An observer.
Returns:
true if the specified observer is not null and is regestered with this parser, false otherwise.

removeObserver

public boolean removeObserver(DataStreamObserver observer)
De-registeres the specified observer from this parser.

Parameters:
observer - An observer.
Returns:
true if the specified observer is not null and was on the list of registered observers and is now removed from this list, false otherwise.

countObservers

public int countObservers()
Counts this parser's observers.

Returns:
The number of observers registered with this parser.

convertTokensToDoubles

public static java.util.List<java.lang.Double> convertTokensToDoubles(java.util.List<java.lang.String> tokens)
This static utility method converts a list of String tokens (presumably just parsed from a data line) to a list of Double objects containing the tokens' values; tokens that cannot be parsed to a Double are represented by null-objects in the resulting list.

Parameters:
tokens - A list of data tokens.
Returns:
A list of the double values of the specified tokens.

createUniqueLabels

public static java.util.List<java.lang.String> createUniqueLabels(java.util.List<java.lang.String> rawLabels,
                                                                  boolean allowEmptyLabels)
This static utility method converts a list of strings (presumably representing a list of labels just parsed from the data file) to a list of strings where each string is unique in respect to its equals method (case sensitive); this happens by attaching counters to repreated strings: for instance, ["boo", "foo", "boo"] it converted to ["boo (1)", "foo", "boo (2)"].

Parameters:
rawLabels - The list of labels to convert.
allowEmptyLabels - If this is false, all empty strings ("") are converted to underscores ("_") before possibly applying the counters.
Returns:
A list of unique data series labels based on the specified list.

processLine

private void processLine(java.lang.String line)
                  throws DataFormatException
Examines a data line and dispatches to a specialised parsing routine.

Parameters:
line - A data line.
Throws:
DataFormatException - If the data stream contents do not conform with the expected data stream format.

processSeparatorDefinitionLine

private void processSeparatorDefinitionLine(java.lang.String line)
                                     throws DataFormatException
Parses a data values separator definition line.

Parameters:
line - Data line to parse.
Throws:
DataFormatException - If the data line contents are not in the expected format.

processCommentLine

private void processCommentLine(java.lang.String line)
                         throws DataFormatException
Parses a comments line.

Parameters:
line - Data line to parse.
Throws:
DataFormatException - If the data line contents are not in the expected format.

processFileInfoLine

private void processFileInfoLine(java.lang.String line)
                          throws DataFormatException
Parses a file information line.

Parameters:
line - Data line to parse.
Throws:
DataFormatException - If the data line contents are not in the expected format.

processSeriesLabelsLine

private void processSeriesLabelsLine(java.lang.String line)
                              throws DataFormatException
Parses a data series headings line.

Parameters:
line - Data line to parse.
Throws:
DataFormatException - If the data line contents are not in the expected format.

processDataLine

private void processDataLine(java.lang.String line)
                      throws DataFormatException
Parses a data line.

Parameters:
line - Data line to parse.
Throws:
DataFormatException - If the data line contents are not in the expected format.

LiveGraph
data visualisation and analysis framework