001 package edu.nrao.sss.model.source.parser;
002
003 import java.io.FileNotFoundException;
004 import java.io.Reader;
005 import java.io.InputStream;
006
007 import edu.nrao.sss.model.source.SourceCatalog;
008 import edu.nrao.sss.util.FileCompressionFormat;
009
010 /**
011 * A reader that creates source catalogs from text.
012 * <p>
013 * <b>CVS Info:</b>
014 * <table style="margin-left:2em">
015 * <tr><td>$Revision: 1273 $</td></tr>
016 * <tr><td>$Date: 2008-05-07 13:46:38 -0600 (Wed, 07 May 2008) $</td></tr>
017 * <tr><td>$Author: jrochfor $</td></tr>
018 * </table></p>
019 *
020 * @author David M. Harland
021 * @since 2006-11-20
022 */
023 public interface SourceCatalogReader
024 {
025
026 /**
027 * Reads data from a file and uses it to add sources to
028 * a {@code SourceCatalog}.
029 *
030 * @param fileName the name of a data file.
031 *
032 * @return <i>true</i> if nothing unexpected occurred while reading data.
033 *
034 * @throws FileNotFoundException if the data file could not be found.
035 *
036 * @see #read(Reader, SourceCatalog)
037 */
038 public boolean read(String fileName) throws FileNotFoundException;
039
040 /**
041 * Reads data from a file and uses it to add sources to
042 * {@code destination}.
043 *
044 * @param fileName the name of a data file.
045 *
046 * @param destination the catalog to which the sources should be
047 * added. If this parameter is <i>null</i>,
048 * a new catalog will be created.
049 *
050 * @return <i>true</i> if nothing unexpected occurred while reading data.
051 *
052 * @throws FileNotFoundException if the data file could not be found.
053 *
054 * @see #read(Reader, SourceCatalog)
055 */
056 public boolean read(String fileName, SourceCatalog destination)
057 throws FileNotFoundException;
058
059 /**
060 * Reads data from {@code in} and uses it to add sources to
061 * a {@code SourceCatalog}.
062 *
063 * @param in the source of text that can be read and turned into
064 * {@code Source} objects.
065 * @return <i>true</i> if nothing unexpected occurred while reading data.
066 *
067 * @see #read(Reader, SourceCatalog)
068 */
069 public boolean read(Reader in);
070
071 /**
072 * Reads data from {@code in} and uses it to add sources to
073 * {@code destination}.
074 *
075 * @param in the source of text that can be read and turned into
076 * {@code Source} objects.
077 *
078 * @param destination the catalog to which the sources should be
079 * added. If this parameter is <i>null</i>,
080 * a new catalog will be created.
081 *
082 * @return <i>true</i> if nothing unexpected occurred while reading data.
083 *
084 * @see #getCatalog()
085 * @see #getErrors()
086 */
087 public boolean read(Reader in, SourceCatalog destination);
088
089 /**
090 * Reads data from {@code in} and uses it to add sources to
091 * a {@code SourceCatalog}.
092 *
093 * @param in the source of text that can be read and turned into
094 * {@code Source} objects.
095 * @return <i>true</i> if nothing unexpected occurred while reading data.
096 *
097 * @see #read(InputStream, SourceCatalog)
098 */
099 public boolean read(InputStream in);
100
101 /**
102 * Reads data from {@code in} and uses it to add sources to
103 * {@code destination}.
104 *
105 * @param in the source of text that can be read and turned into
106 * {@code Source} objects.
107 *
108 * @param destination the catalog to which the sources should be
109 * added. If this parameter is <i>null</i>,
110 * a new catalog will be created.
111 *
112 * @return <i>true</i> if nothing unexpected occurred while reading data.
113 *
114 * @see #getCatalog()
115 * @see #getErrors()
116 */
117 public boolean read(InputStream in, SourceCatalog destination);
118
119 /**
120 * Reads data from {@code in} and uses it to add sources to a {@code
121 * SourceCatalog}. If {@code format} is specified and non-null, the
122 * InputStream should be uncompressed if necessary before being used as a
123 * source for Source information.
124 *
125 * @param in the source of text that can be read and turned into
126 * {@code Source} objects.
127 *
128 * @return <i>true</i> if nothing unexpected occurred while reading data.
129 *
130 * @see #getCatalog()
131 * @see #getErrors()
132 */
133 public boolean read(InputStream in, FileCompressionFormat format);
134
135 /**
136 * Reads data from {@code in} and uses it to add sources to {@code
137 * destination}. If {@code format} is specified and non-null, the
138 * InputStream should be uncompressed if necessary before being used as a
139 * source for Source information.
140 *
141 * @param in the source of text that can be read and turned into
142 * {@code Source} objects.
143 *
144 * @param destination the catalog to which the sources should be
145 * added. If this parameter is <i>null</i>,
146 * a new catalog will be created.
147 *
148 * @return <i>true</i> if nothing unexpected occurred while reading data.
149 *
150 * @see #getCatalog()
151 * @see #getErrors()
152 */
153 public boolean read(InputStream in, SourceCatalog destination, FileCompressionFormat format);
154
155 /**
156 * Returns the catalog most recently created by this reader.
157 * <p>
158 * If this reader had trouble parsing the catalog data, the
159 * returned catalog may be partially or completely unfilled.
160 * If the read method has never been called, a new catalog
161 * will be returned.</p>
162 *
163 * @return the catalog most recently created by this reader.
164 * This value is guaranteed to be non-null.
165 */
166 public SourceCatalog getCatalog();
167
168 /**
169 * Returns <i>true</i> if the most recently read data caused
170 * no parsing errors. Note that the {@code SourceCatalog} created
171 * by this reader may be perfectly fine even if this method
172 * returns <i>false</i>.
173 *
174 * @return <i>true</i> if there were no incidents during the
175 * most recent read.
176 */
177 public boolean getSuccess();
178
179 /**
180 * Returns the combined text of all errors found during the most recent read.
181 * <p>
182 * Note that an "error" is anything unexpected encountered while
183 * reading. Not all errors are harmful. The text of each error includes
184 * the line number where it occurred and an explanation of what was wrong.</p>
185 *
186 * @return the combined text of all errors found during the most recent read.
187 */
188 public StringBuilder getErrors();
189
190 /**
191 * Returns the {@code index}<sup>th</sup> error found during the most
192 * recent read.
193 *
194 * @param index a positional value >= zero and < {@link #getErrorCount()}.
195 *
196 * @return the {@code index}<sup>th</sup> error found during the most
197 * recent read.
198 *
199 * @see #getErrors()
200 */
201 public String getError(int index);
202
203 /**
204 * Returns the number of errors found during the most recent read.
205 * @return the number of errors found during the most recent read.
206 * @see #getErrors()
207 */
208 public int getErrorCount();
209
210 /**
211 * Sets text that will be used as the source of information for each source
212 * read by this reader.
213 *
214 * @param origin text that will be used as the source of information for each
215 * source read by this reader. A value of <i>null</i> will be
216 * interpreted as a single not to set the source's origin of
217 * information.
218 */
219 public void setOriginOfSourceInformation(String origin);
220
221 /**
222 * Sets text that will be used as a prefix for any historical source records
223 * generated by this reader.
224 *
225 * @param prefix text that will be used as a prefix for any historical source
226 * records generated by this reader.
227 */
228 public void setPrefixForHistoricalRecords(String prefix);
229 }