001 package edu.nrao.sss.model.source.parser;
002
003 import java.io.Writer;
004 import java.io.OutputStream;
005
006 import edu.nrao.sss.model.source.SourceCatalog;
007 import edu.nrao.sss.util.FileCompressionFormat;
008
009 /**
010 * A writer that converts source catalogs to a text format.
011 * <p>
012 * <b>CVS Info:</b>
013 * <table style="margin-left:2em">
014 * <tr><td>$Revision: 714 $</td></tr>
015 * <tr><td>$Date: 2007-06-13 10:36:05 -0600 (Wed, 13 Jun 2007) $</td></tr>
016 * <tr><td>$Author: btruitt $</td></tr>
017 * </table></p>
018 */
019 public interface SourceCatalogWriter
020 {
021 /**
022 * Writes the sources in {@code cat} to a file
023 *
024 * @param fileName the name of a file.
025 * @param cat the catalog of sources to output
026 * @return <i>true</i> if nothing unexpected occurred while writing data.
027 *
028 * @see #write(SourceCatalog, Writer)
029 */
030 public boolean write(SourceCatalog cat, String fileName);
031
032 /**
033 * Writes the sources in {@code cat} to the Writer {@code out}.
034 *
035 * @param out the destination of the text representation.
036 * @param cat the catalog of sources to output
037 *
038 * @return <i>true</i> if nothing unexpected occurred while reading data.
039 *
040 * @see #getErrors
041 * @throws NullPointerException if {@code cat} is NULL.
042 */
043 public boolean write(SourceCatalog cat, Writer out);
044
045 /**
046 * Writes the sources in {@code cat} to the OutputStream {@code out}.
047 *
048 * @param out the destination of the text representation.
049 * @param cat the catalog of sources to output
050 *
051 * @return <i>true</i> if nothing unexpected occurred while reading data.
052 *
053 * @see #write(SourceCatalog, OutputStream, FileCompressionFormat)
054 */
055 public boolean write(SourceCatalog cat, OutputStream out);
056
057 /**
058 * Writes the sources in {@code cat} to the OutputStream {@code out}. If
059 * {@code format} is specified, non-null, and not equal to {@code UNCOMPRESSED}
060 * the data should be compressed before being written to {@code out}.
061 *
062 * @param cat the source of sources that can be written out in a text format.
063 * @param out the OutputStream to which the sources should be written.
064 * @param format determines what kind of compression, if any, that should be used.
065 *
066 * @return <i>true</i> if nothing unexpected occurred while reading data.
067 *
068 * @see #getErrors()
069 */
070 public boolean write(SourceCatalog cat, OutputStream out, FileCompressionFormat format);
071
072 /**
073 * Returns <i>true</i> if the most recently read data caused
074 * no parsing errors. Note that the {@code SourceCatalog} created
075 * by this reader may be perfectly fine even if this method
076 * returns <i>false</i>.
077 *
078 * @return <i>true</i> if there were no incidents during the
079 * most recent read.
080 */
081 public boolean getSuccess();
082
083 /**
084 * Returns the combined text of all errors found during the most recent write.
085 * <p>
086 * Note that an "error" is anything unexpected encountered while
087 * writing. Not all errors are harmful. The text of each error includes
088 * the line number where it occurred and an explanation of what was wrong.</p>
089 *
090 * @return the combined text of all errors found during the most recent write.
091 */
092 public StringBuilder getErrors();
093
094 /**
095 * Returns the {@code index}<sup>th</sup> error found during the most
096 * recent write.
097 *
098 * @param index a positional value >= zero and < {@link #getErrorCount()}.
099 *
100 * @return the {@code index}<sup>th</sup> error found during the most
101 * recent write.
102 *
103 * @see #getErrors()
104 */
105 public String getError(int index);
106
107 /**
108 * Returns the number of errors found during the most recent write.
109 * @return the number of errors found during the most recent write.
110 * @see #getErrors()
111 */
112 public int getErrorCount();
113 }