001    package org.LiveGraph.dataFile.read;
002    
003    import java.util.List;
004    
005    
006    /**
007     * Defines an observer that is notified about parsing events of a data stream.
008     * Objects implementing this interface can be registered with a {@link DataStreamReader}
009     * which will then notify these objects whenever new information has been read from the
010     * underlying data stream. 
011     * 
012     * <p><strong>LiveGraph</strong> (http://www.live-graph.org).</p>
013     * <p>Copyright (c) 2007 by G. Paperin.</p>
014     * <p>File: DataStreamObserver.java</p> 
015     * <p style="font-size:smaller;">Redistribution and use in source and binary forms, with or
016     *    without modification, are permitted provided that the following terms and conditions are met:
017     * </p>
018     * <p style="font-size:smaller;">1. Redistributions of source code must retain the above
019     *    acknowledgement of the LiveGraph project and its web-site, the above copyright notice,
020     *    this list of conditions and the following disclaimer.<br />
021     *    2. Redistributions in binary form must reproduce the above acknowledgement of the
022     *    LiveGraph project and its web-site, the above copyright notice, this list of conditions
023     *    and the following disclaimer in the documentation and/or other materials provided with
024     *    the distribution.<br />
025     *    3. All advertising materials mentioning features or use of this software or any derived
026     *    software must display the following acknowledgement:<br />
027     *    <em>This product includes software developed by the LiveGraph project and its
028     *    contributors.<br />(http://www.live-graph.org)</em><br />
029     *    4. All advertising materials distributed in form of HTML pages or any other technology
030     *    permitting active hyper-links that mention features or use of this software or any
031     *    derived software must display the acknowledgment specified in condition 3 of this
032     *    agreement, and in addition, include a visible and working hyper-link to the LiveGraph
033     *    homepage (http://www.live-graph.org).
034     * </p>
035     * <p style="font-size:smaller;">THIS SOFTWARE IS PROVIDED &quot;AS IS&quot;, WITHOUT WARRANTY
036     *    OF ANY KIND, EXPRESSED OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
037     *    MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND  NONINFRINGEMENT. IN NO EVENT SHALL
038     *    THE AUTHORS, CONTRIBUTORS OR COPYRIGHT  HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
039     *    LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING  FROM, OUT OF OR
040     *    IN CONNECTION WITH THE SOFTWARE OR THE USE OR  OTHER DEALINGS IN THE SOFTWARE.
041     * </p>
042     * 
043     * @author Greg Paperin (http://www.paperin.org)
044     * @version {@value org.LiveGraph.LiveGraph#version}
045     */
046    public interface DataStreamObserver {
047    
048    /**
049     * Is called when a data values separator has been parsed by the data reader.
050     * 
051     * @param separator The new data values separator string.
052     * @param reader The reader which produced this event.
053     */
054    public void eventSeparatorSet(String separator, DataStreamReader reader);
055    
056    /**
057     * Is called when a comment line has been encontered by the data reader.
058     * 
059     * @param comment The comment line.
060     * @param reader The reader which produced this event.
061     */
062    public void eventCommentLine(String comment, DataStreamReader reader);
063    
064    /**
065     * Is called when a file info/description comment line has been parsed by the data reader.
066     * 
067     * @param info File description/info string.
068     * @param reader The reader which produced this event.
069     */
070    public void eventFileInfoLine(String info, DataStreamReader reader);
071    
072    /**
073     * Is called when data series labels have been parsed by the data reader.
074     * 
075     * @param labels An <em>unmodifiable</em> list containing all parsed data series labels.
076     * @param reader The reader which produced this event.
077     */
078    public void eventLabelsSet(List<String> labels, DataStreamReader reader);
079    
080    /**
081     * Is called each time a data line (data set) has been parsed by the data reader.
082     * 
083     * @param dataTokens An <em>unmodifiable</em> list containing all data tokens parsed from this line.
084     * @param datasetIndex The number of this data line in the stream (i.e. dataset file index).
085     * @param reader The reader which produced this event.
086     */
087    public void eventDataLineRead(List<String> dataTokens, int datasetIndex, DataStreamReader reader);
088    
089    }