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.biojavax.bio.seq.io;
023
024import org.biojava.bio.seq.io.ParseException;
025import org.biojava.bio.seq.io.SeqIOListener;
026import org.biojavax.Namespace;
027import org.biojavax.RankedCrossRef;
028import org.biojavax.RankedDocRef;
029import org.biojavax.bio.BioEntryRelationship;
030import org.biojavax.bio.seq.RichFeature;
031import org.biojavax.bio.taxa.NCBITaxon;
032
033/**
034 * An interface for classes that listen to BioEntry or 
035 * RichSequence I/O streams. The listener works as a call back interface.
036 * The callback methods would be generated by an object that is, for example,
037 * reading a sequence flat file. Guidelines on how many times the listener can
038 * expect each callback to occur are given below.
039 * Exactly what the Listener does with each call back is totally at the discretion
040 * of the implementor. The listener may aggregate events and build objects.
041 * The listener may selectively filter events and parse on others to another
042 * listener. The listener may choose to modify events. The options are endless.
043 * Although the name of the class and the name of some of the events suggest a
044 * sequence centric design the class could be used to listen to a parser of a
045 * bioentry style record that doesn't actually contain any sequence. In this
046 * case no addSymbols() methods would be called. The listener may
047 * be an implementation that only builds BioEntry objects and
048 * ignores sequence information completely.
049 * @author Mark Schreiber
050 * @author Richard Holland
051 * @since 1.5
052 */
053public interface RichSeqIOListener extends SeqIOListener {
054    
055    /**
056     * Call back method so the event emitter can tell the listener
057     * the accession of the record being read. It is possible that some
058     * records have more than one accession. As a guide the first one
059     * sent to the listener should be the primary one.
060     * @param accession The accession of the record
061     * @throws org.biojava.bio.seq.io.ParseException If the Listener cannot understand the event, is unable
062     * to deal with the event or is not expecting the event.
063     *
064     * @see #setName(String name)
065     * @see #setURI(String uri)
066     * @see #setIdentifier(String identifier)
067     *
068     */
069    public void setAccession(String accession) throws ParseException;
070    
071    /**
072     * Call back method so the event emitter can tell the listener
073     * the identifier of the record being read. There should be
074     * zero or one identifier per bioentry. If there is more
075     * than one the Listener should consider throwing an exception.
076     * For some formats like fasta the identifier may not exist. For others
077     * like GenBank the identifier best maps to the GI.
078     * @param identifier The identifier of the Bioentry.
079     * @throws org.biojava.bio.seq.io.ParseException If the Listener cannot understand the event, is unable
080     * to deal with the event or is not expecting the event.
081     * @see #setName(String name)
082     * @see #setAccession(String accession)
083     * @see #setURI(String uri)
084     */
085    public void setIdentifier(String identifier) throws ParseException;
086    
087    /**
088     * Call back method so the event emitter can tell the listener
089     * the division of the record being read. If the source of the
090     * calls back is a GenBank parser the division will be a Genbank division.
091     * This method would typically be called 0 or 1 times. It should
092     * not be called more than once per entry and an exception could be thrown
093     * if it is.
094     * @param division The division the entry belongs too.
095     * @throws org.biojava.bio.seq.io.ParseException If the Listener cannot understand the event, is unable
096     * to deal with the event or is not expecting the event.
097     */
098    public void setDivision(String division) throws ParseException;
099    
100    /**
101     * Call back method so the event emitter can tell the listener
102     * the description of the record being read. For example the description
103     * line of a FASTA format file would be the description. This method
104     * would typically be called 0 or 1 times and may cause an exception
105     * if it is called more than once per entry.
106     * @param description The description of the record
107     * @throws org.biojava.bio.seq.io.ParseException If the Listener cannot understand the event, is unable
108     * to deal with the event or is not expecting the event.
109     */
110    public void setDescription(String description)throws ParseException;
111    
112    /**
113     * Call back method so the event emitter can tell the listener
114     * the version of the record being read. This method would typically
115     * be called 0 or 1 times per entry. If it is not called the
116     * Listener should assume the version is 0. If it is called more
117     * than once per entry an exception should be thrown.
118     * @param version the version of the record
119     * @throws org.biojava.bio.seq.io.ParseException If the Listener cannot understand the event, is unable
120     * to deal with the event or is not expecting the event.
121     */
122    public void setVersion(int version) throws ParseException;
123    
124    /**
125     * Call back method so the event emitter can tell the listener
126     * the version of the sequence of the record being read. This method would typically
127     * be called 0 or 1 times per entry. If it is not called the
128     * Listener should assume the version is 0. If it is called more
129     * than once per entry an exception should be thrown.
130     * @param version the version of the record
131     * @throws org.biojava.bio.seq.io.ParseException If the Listener cannot understand the event, is unable
132     * to deal with the event or is not expecting the event.
133     */
134    public void setSeqVersion(String version) throws ParseException;
135    
136    /**
137     * Call back method so the event emitter can tell the listener
138     * about a comment in the record being read. The comment is typically
139     * one or more comment lines relevant to the record as a whole and
140     * bundled in a Commment object.
141     * This method may be called zero or one times per entry. It can be called zero or more times.
142     * @param comment The comment
143     * @throws org.biojava.bio.seq.io.ParseException If the Listener cannot understand the event, is unable
144     * to deal with the event or is not expecting the event.
145     */
146    public void setComment(String comment) throws ParseException;
147    
148    /**
149     * Call back method so the event emitter can tell the listener
150     * about a literature reference in the record being read. This method
151     * may be called zero or more times.
152     * @param ref A literature reference contained in the entry.
153     * @throws org.biojava.bio.seq.io.ParseException If the Listener cannot understand the event, is unable
154     * to deal with the event or is not expecting the event.
155     */
156    public void setRankedDocRef(RankedDocRef ref) throws ParseException;
157    
158    /**
159     * Call back method so the event emitter can tell the listener
160     * the Taxon of the record being read. This method may be called
161     * zero or one times. An exception may be thrown if it is called
162     * more than once. As a design decision NCBI's taxon model was chosen as it
163     * is commonly used and is supported by the BioSQL schema. The setting of
164     * an NCBI taxon should be considered entirely optional.
165     *
166     * @param taxon The taxon information relevant to this entry.
167     * @throws org.biojava.bio.seq.io.ParseException If the Listener cannot understand the event, is unable
168     * to deal with the event or is not expecting the event.
169     */
170    public void setTaxon(NCBITaxon taxon) throws ParseException;
171    
172    /**
173     * Call back method so the event emitter can tell the listener
174     * the namespace of the record being read. The method can be called
175     * zero or one time. If it is called more than once an exception
176     * may be thrown.<p>
177     * The namespace is a concept from the BioSQL schema that enables
178     * Bioentries to be disambiguated. It is possible in BioSQL and should be possible
179     * in other collections of BioEntries to have records that have the same
180     * name, accession and version but different namespaces. This method would be
181     * expected to be called if you are reading a sequence from a biosql database or
182     * if you are implementing a listener that knows how to write to a biosql database.
183     * If you give a sequence a namespace and it is persited to biosql at somepoint in it's
184     * life you could expect it to be persisted to that namespace (if possible).
185     *
186     * @param namespace The namespace of the entry.
187     * @throws org.biojava.bio.seq.io.ParseException If the Listener cannot understand the event, is unable
188     * to deal with the event or is not expecting the event.
189     */
190    public void setNamespace(Namespace namespace) throws ParseException;
191    
192    /**
193     * Call back method so the event emitter can tell the listener
194     * about a relationship between the bioentry or sequence in the
195     * record being read and another bioentry. This may be called zero
196     * or more times.
197     * @param relationship The relationship
198     * @throws org.biojava.bio.seq.io.ParseException If the Listener cannot understand the event, is unable
199     * to deal with the event or is not expecting the event.
200     */
201    public void setRelationship(BioEntryRelationship relationship) throws ParseException;
202    
203    /**
204     * Call back method so the event emitter can tell the listener about a cross reference.
205     * This could be called zero or more times per entry.
206     * @param crossRef the cross reference
207     * @throws org.biojava.bio.seq.io.ParseException If the Listener cannot understand the event, is unable
208     * to deal with the event or is not expecting the event.
209     */
210    public void setRankedCrossRef(RankedCrossRef crossRef) throws ParseException;
211    
212    /**
213     * {@inheritDoc}
214     * @deprecated There is no clear mapping between URI and BioSQL. This
215     *  method is no longer used or supported in biojavax. Don't use it. Calling
216     *  it may result in exceptions. Use instead setName(String name),
217     *  setAccession(String accession), setVersion(int version) etc as
218     *  appropriate.
219     */
220    public void setURI(String uri) throws ParseException;
221    
222    /**
223     * Gets the feature currently being created.
224     * @return the feature under construction.
225     * @throws ParseException if a feature is not currently being created.
226     */ 
227    public RichFeature getCurrentFeature() throws ParseException;
228    
229    /**
230     * Defined this sequence being parser as circular. It is best to call this
231     * as early as possible during parsing. It should definitely be called
232     * before doing anything with locations or features.
233     * @throws org.biojava.bio.seq.io.ParseException If the Listener cannot understand the event, is unable
234     * to deal with the event or is not expecting the event.
235     * @param circular set this to true if you want it to be circular.
236     */ 
237    public void setCircular(boolean circular) throws ParseException;
238    
239}