001/**
002 * DataReader -- Interface for classes that read and write data files.
003 *
004 * Copyright (C) 2003-2025, 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 February 23, 2025
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 IOException 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
086     * data sets.
087     *
088     * @param name The default set name to use for data formats that do not have
089     *              named data sets.
090     */
091    public void setDefaultSetName(CharSequence name);
092
093    /**
094     * Method that determines if this reader can read data from the specified input
095     * stream.
096     *
097     * @param pathName The path to the file to be read.
098     * @param input    An input stream containing the data to be read. Any methods that
099     *                 read from this stream must first set a mark and then reset back to
100     *                 that mark before the method returns (even if it returns with an
101     *                 exception).
102     * @return DataReader.NO if the file format is not recognized by this reader.
103     *         DataReader.YES if the file format is definitely recognized by this reader.
104     *         DataReader.MAYBE if the file format might be readable by this reader, but
105     *         that can't easily be determined without actually reading the file.
106     * @throws IOException if the data can not be read in.
107     */
108    public int canReadData(String pathName, BufferedInputStream input) throws IOException;
109
110    /**
111     * Returns true if this class can write at least some data in the format supported by
112     * this class. Returns false if it can not.
113     *
114     * @return A value of true if this class can write at least some data, false
115     *         otherwise.
116     */
117    public boolean canWriteData();
118
119    /**
120     * Returns a data structure that contains the data in the input list filtered in
121     * whatever way is necessary to save it using a particular format. This is done by
122     * applying rules and/or by asking the user to choose what data should be saved. The
123     * requirements for what can be saved is specific to each format.
124     *
125     * @param parent Determines the Frame in which the dialog is displayed; if null, or if
126     *               the parentComponent has no Frame, a default Frame is used.
127     * @param data   The input data set that is to be selected for saving.
128     * @return A list of DataSet objects containing the selected data to be saved. If this
129     *         DataReader does not supporting saving, then null is returned.
130     */
131    public List<DataSet> selectDataForSaving(Frame parent, List<DataSet> data);
132
133    /**
134     * Returns the preferred file extension (not including the ".") for files of this
135     * DataReader's type.
136     *
137     * @return The preferred file extension (not including the ".") for files of this
138     * DataReader's type.
139     */
140    public String getExtension();
141}