001/**
002 * DataReader -- Interface for classes that read and write data files.
003 *
004 * Copyright (C) 2003-2015, by Joseph A. Huwaldt. All rights reserved.
005 *
006 * This library is free software; you can redistribute it and/or modify it under the terms
007 * of the GNU Lesser General Public License as published by the Free Software Foundation;
008 * either version 2 of the License, or (at your option) any later version.
009 *
010 * This library is distributed in the hope that it will be useful, but WITHOUT ANY
011 * WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A
012 * PARTICULAR PURPOSE. See the GNU Library General Public License for more details.
013 *
014 * You should have received a copy of the GNU Lesser General Public License along with
015 * this program; if not, write to the Free Software Foundation, Inc., 59 Temple Place -
016 * Suite 330, Boston, MA 02111-1307, USA. Or visit: http://www.gnu.org/licenses/lgpl.html
017 */
018package jahuwaldt.js.datareader;
019
020import java.awt.Frame;
021import java.io.BufferedInputStream;
022import java.io.IOException;
023import java.io.InputStream;
024import java.io.OutputStream;
025import java.util.List;
026import java.util.ResourceBundle;
027
028/**
029 * This class provides a standard interface for reading and writing data files of various
030 * formats. Sub-classes actually do the translation from the data file's format to the
031 * DataSet data structure in memory and vise versa.
032 *
033 * <p> Modified by: Joseph A. Huwaldt </p>
034 *
035 * @author Joseph A. Huwaldt, Date: March 6, 2003
036 * @version October 15, 2015
037 */
038public interface DataReader extends Comparable<DataReader> {
039
040    /**
041     * The resource bundle for this package.
042     */
043    public static final ResourceBundle RESOURCES
044            = ResourceBundle.getBundle("jahuwaldt.js.datareader.DataReader", java.util.Locale.getDefault());
045    
046    /**
047     * Constant indicating that a reader can not read a specified file stream.
048     */
049    public static final int NO = 0;
050
051    /**
052     * Constant indicating that a reader can certainly read a specified file stream.
053     */
054    public static final int YES = 1;
055
056    /**
057     * Constant indicating that a reader might be able to read a specified file stream,
058     * but can't determine for sure.
059     */
060    public static final int MAYBE = -1;
061
062    /**
063     * Interface for reading in data from an input stream and returning that data as a
064     * list of {@link DataSet} objects.
065     *
066     * @param pathName The path to the file to be read.
067     * @param input    An input stream containing the data to be read.
068     * @return A list of DataSet objects that contain the data read in from the specified
069     * stream.
070     * @throws Exception If there is a problem reading the specified stream.
071     */
072    public List<DataSet> read(String pathName, InputStream input) throws IOException;
073
074    /**
075     * Interface for writing out all the data stored in the specified list of
076     * {@link DataSet} objects to the specified output stream.
077     *
078     * @param output The output stream to which the data is to be written.
079     * @param data   The list of DataSet objects to be written out.
080     * @throws IOException If there is a problem writing to the specified stream.
081     */
082    public void write(OutputStream output, List<DataSet> data) throws IOException;
083
084    /**
085     * Sets the default set name to use for data formats that do not have named data sets.
086     */
087    public void setDefaultSetName(CharSequence name);
088
089    /**
090     * Method that determines if this reader can read data from the specified input
091     * stream.
092     *
093     * @param pathName The path to the file to be read.
094     * @param input    An input stream containing the data to be read. Any methods that
095     *                 read from this stream must first set a mark and then reset back to
096     *                 that mark before the method returns (even if it returns with an
097     *                 exception).
098     * @return DataReader.NO if the file format is not recognized by this reader.
099     *         DataReader.YES if the file format is definitely recognized by this reader.
100     *         DataReader.MAYBE if the file format might be readable by this reader, but
101     *         that can't easily be determined without actually reading the file.
102     */
103    public int canReadData(String pathName, BufferedInputStream input) throws IOException;
104
105    /**
106     * Returns true if this class can write at least some data in the format supported by
107     * this class. Returns false if it can not.
108     */
109    public boolean canWriteData();
110
111    /**
112     * Returns a data structure that contains the data in the input list filtered in
113     * whatever way is necessary to save it using a particular format. This is done by
114     * applying rules and/or by asking the user to choose what data should be saved. The
115     * requirements for what can be saved is specific to each format.
116     *
117     * @param parent Determines the Frame in which the dialog is displayed; if null, or if
118     *               the parentComponent has no Frame, a default Frame is used.
119     * @param data   The input data set that is to be selected for saving.
120     * @return A list of DataSet objects containing the selected data to be saved. If this
121     *         DataReader does not supporting saving, then null is returned.
122     */
123    public List<DataSet> selectDataForSaving(Frame parent, List<DataSet> data);
124
125    /**
126     * Returns the preferred file extension (not including the ".") for files of this
127     * DataReader's type.
128     */
129    public String getExtension();
130}