001/*
002 *                    BioJava development code
003 *
004 * This code may be freely distributed and modified under the
005 * terms of the GNU Lesser General Public Licence.  This should
006 * be distributed with the code.  If you do not have a copy,
007 * see:
008 *
009 *      http://www.gnu.org/copyleft/lesser.html
010 *
011 * Copyright for this code is held jointly by the individual
012 * authors.  These should be listed in @author doc comments.
013 *
014 * For more information on the BioJava project and its aims,
015 * or to join the biojava-l mailing list, visit the home page
016 * at:
017 *
018 *      http://www.biojava.org/
019 *
020 */
021
022package org.biojava.bio.seq.io;
023
024import java.io.BufferedReader;
025import java.io.IOException;
026import java.io.PrintStream;
027
028import org.biojava.bio.BioException;
029import org.biojava.bio.seq.Sequence;
030import org.biojava.bio.symbol.IllegalSymbolException;
031
032/**
033 * Defines what a sequence format does.
034 *
035 * <p>Sequence formats are responsible for both reading and writing a
036 * sequence in a format, presumably in such a way as the written
037 * record can be read back in by the same formatter.</p>
038 *
039 * <p>Where possible, the methods are parameterised so that they don't
040 * need any knowledge of the specific implementation of Sequence they
041 * are reading or writing. E.g. it should be possible to parameterise
042 * readSequence to read from a Genbank stream and construct Ensembl
043 * CORBA objects, just by specifying an Ensembl SequenceFactory.</p>
044 * 
045 * <p>More functionality is offered by {@link org.biojavax.bio.seq.io.RichSequenceFormat RichSequenceFormat},
046 * Use of this interface is prefered.</p>
047 *
048 * @author Matthew Pocock
049 * @author Thomas Down
050 * @author Keith James
051 */
052
053public interface SequenceFormat
054{
055    /**
056     * Read a sequence and pass data on to a SeqIOListener.
057     *
058     * @param reader The stream of data to parse.
059     * @param symParser A SymbolParser defining a mapping from
060     * character data to Symbols.
061     * @param listener A listener to notify when data is extracted
062     * from the stream.
063     *
064     * @return a boolean indicating whether or not the stream contains
065     * any more sequences.
066     *
067     * @throws IOException if an error occurs while reading from the
068     * stream.
069     * @throws IllegalSymbolException if it is not possible to
070     * translate character data from the stream into valid BioJava
071     * symbols.
072     * @throws BioException if there is an error in the format of the
073     * stream.
074     */
075    public boolean readSequence(BufferedReader     reader,
076                                SymbolTokenization symParser,
077                                SeqIOListener      listener)
078        throws BioException, IllegalSymbolException, IOException;
079
080    /**
081     * <code>writeSequence</code> writes a sequence to the specified
082     * PrintStream, using the default format.
083     *
084     * @param seq the sequence to write out.
085     * @param os the printstream to write to.
086     */
087    public void writeSequence(Sequence seq, PrintStream os)
088        throws IOException;
089
090    /**
091     * <code>writeSequence</code> writes a sequence to the specified
092     * <code>PrintStream</code>, using the specified format.
093     *
094     * @param seq a <code>Sequence</code> to write out.
095     * @param format a <code>String</code> indicating which sub-format
096     * of those available from a particular
097     * <code>SequenceFormat</code> implemention to use when
098     * writing.
099     * @param os a <code>PrintStream</code> object.
100     *
101     * @exception IOException if an error occurs.
102     * @deprecated use writeSequence(Sequence seq, PrintStream os)
103     */
104    public void writeSequence(Sequence seq, String format, PrintStream os)
105        throws IOException;
106
107    /**
108     * <code>getDefaultFormat</code> returns the String identifier for
109     * the default sub-format written by a <code>SequenceFormat</code>
110     * implementation.
111     *
112     * @return a <code>String</code>.
113     * @deprecated new implementations should only write a single
114     * format.
115     */
116    public String getDefaultFormat();
117}