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}