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 org.biojava.bio.seq.Feature;
025import org.biojava.bio.symbol.Alphabet;
026import org.biojava.bio.symbol.IllegalAlphabetException;
027import org.biojava.bio.symbol.Symbol;
028
029/**
030 * Notification interface for objects which listen to a sequence stream
031 * parser.
032 * More functionality is offered by the 
033 * {@link org.biojavax.bio.seq.io.RichSeqIOListener RichSeqIOListener}.
034 * @author Thomas Down
035 * @author Matthew Pocock
036 * @since 1.1
037 * @see org.biojavax.bio.seq.io.RichSeqIOListener
038 */
039
040public interface SeqIOListener {
041    /**
042     * Start the processing of a sequence.  This method exists primarily
043     * to enforce the life-cycles of SeqIOListener objects.
044     */
045
046    public void startSequence() throws ParseException;
047
048    /**
049     * Notify the listener that processing of the sequence is complete.
050     */
051
052    public void endSequence() throws ParseException;
053
054    /**
055     * Notify the listener that the current sequence is generally known
056     * by a particular name.
057     *
058     * @param name the String that should be returned by getName for the sequence
059     * being parsed
060     */
061
062    public void setName(String name) throws ParseException;
063
064    /**
065     * Notify the listener of a URI identifying the current sequence.
066     */
067
068    public void setURI(String uri) throws ParseException;
069
070    /**
071     * Notify the listener of symbol data.  All symbols passed to
072     * this method are guarenteed to be contained within the
073     * specified alphabet.  Generally all calls to a given Listener
074     * should have the same alphabet -- if not, the listener implementation
075     * is likely to throw an exception
076     *
077     * @param alpha The alphabet of the symbol data
078     * @param syms An array containing symbols
079     * @param start The start offset of valid data within the array
080     * @param length The number of valid symbols in the array
081     *
082     * @throws IllegalAlphabetException if we can't cope with this
083     *                                  alphabet.
084     */
085
086    public void addSymbols(Alphabet alpha, Symbol[] syms, int start, int length)
087        throws IllegalAlphabetException;
088
089    /**
090     * Notify the listener of a sequence-wide property.  This might
091     * be stored as an entry in the sequence's annotation bundle.
092     */
093
094    public void addSequenceProperty(Object key, Object value) throws ParseException;
095
096    /**
097     * Notify the listener that a new feature object is starting.
098     * Every call to startFeature should have a corresponding call
099     * to endFeature.  If the listener is concerned with a hierarchy
100     * of features, it should maintain a stack of `open' features.
101     */
102
103    public void startFeature(Feature.Template templ) throws ParseException;
104
105    /**
106     * Mark the end of data associated with one specific feature.
107     */
108
109    public void endFeature() throws ParseException;
110
111    /**
112     * Notify the listener of a feature property.
113     */
114
115    public void addFeatureProperty(Object key, Object value) throws ParseException;
116}