org.biojavax.bio.seq.io

Interface RichSeqIOListener

All Superinterfaces:

SeqIOListener

All Known Subinterfaces:

RichSequenceBuilder

All Known Implementing Classes:

DebuggingRichSeqIOListener, RichSeqIOAdapter, SimpleRichSequenceBuilder

public interface RichSeqIOListener
extends SeqIOListener

An interface for classes that listen to BioEntry or RichSequence I/O streams. The listener works as a call back interface. The callback methods would be generated by an object that is, for example, reading a sequence flat file. Guidelines on how many times the listener can expect each callback to occur are given below. Exactly what the Listener does with each call back is totally at the discretion of the implementor. The listener may aggregate events and build objects. The listener may selectively filter events and parse on others to another listener. The listener may choose to modify events. The options are endless. Although the name of the class and the name of some of the events suggest a sequence centric design the class could be used to listen to a parser of a bioentry style record that doesn't actually contain any sequence. In this case no addSymbols() methods would be called. The listener may be an implementation that only builds BioEntry objects and ignores sequence information completely.

Since:

1.5

Author:

Mark Schreiber, Richard Holland

Method Summary

Methods

Modifier and Type	Method and Description
RichFeature	getCurrentFeature() Gets the feature currently being created.
void	setAccession(String accession) Call back method so the event emitter can tell the listener the accession of the record being read.
void	setCircular(boolean circular) Defined this sequence being parser as circular.
void	setComment(String comment) Call back method so the event emitter can tell the listener about a comment in the record being read.
void	setDescription(String description) Call back method so the event emitter can tell the listener the description of the record being read.
void	setDivision(String division) Call back method so the event emitter can tell the listener the division of the record being read.
void	setIdentifier(String identifier) Call back method so the event emitter can tell the listener the identifier of the record being read.
void	setNamespace(Namespace namespace) Call back method so the event emitter can tell the listener the namespace of the record being read.
void	setRankedCrossRef(RankedCrossRef crossRef) Call back method so the event emitter can tell the listener about a cross reference.
void	setRankedDocRef(RankedDocRef ref) Call back method so the event emitter can tell the listener about a literature reference in the record being read.
void	setRelationship(BioEntryRelationship relationship) Call back method so the event emitter can tell the listener about a relationship between the bioentry or sequence in the record being read and another bioentry.
void	setSeqVersion(String version) Call back method so the event emitter can tell the listener the version of the sequence of the record being read.
void	setTaxon(NCBITaxon taxon) Call back method so the event emitter can tell the listener the Taxon of the record being read.
void	setURI(String uri) Deprecated. There is no clear mapping between URI and BioSQL. This method is no longer used or supported in biojavax. Don't use it. Calling it may result in exceptions. Use instead setName(String name), setAccession(String accession), setVersion(int version) etc as appropriate.
void	setVersion(int version) Call back method so the event emitter can tell the listener the version of the record being read.

Methods inherited from interface org.biojava.bio.seq.io.SeqIOListener

addFeatureProperty, addSequenceProperty, addSymbols, endFeature, endSequence, setName, startFeature, startSequence

Method Detail

setAccession

void setAccession(String accession)
                  throws ParseException

Call back method so the event emitter can tell the listener the accession of the record being read. It is possible that some records have more than one accession. As a guide the first one sent to the listener should be the primary one.

Parameters:

accession - The accession of the record

Throws:

ParseException - If the Listener cannot understand the event, is unable to deal with the event or is not expecting the event.

See Also:

SeqIOListener.setName(String name), setURI(String uri), setIdentifier(String identifier)

setIdentifier

void setIdentifier(String identifier)
                   throws ParseException

Call back method so the event emitter can tell the listener the identifier of the record being read. There should be zero or one identifier per bioentry. If there is more than one the Listener should consider throwing an exception. For some formats like fasta the identifier may not exist. For others like GenBank the identifier best maps to the GI.

Parameters:

identifier - The identifier of the Bioentry.

Throws:

ParseException - If the Listener cannot understand the event, is unable to deal with the event or is not expecting the event.

See Also:

SeqIOListener.setName(String name), setAccession(String accession), setURI(String uri)

setDivision

void setDivision(String division)
                 throws ParseException

Call back method so the event emitter can tell the listener the division of the record being read. If the source of the calls back is a GenBank parser the division will be a Genbank division. This method would typically be called 0 or 1 times. It should not be called more than once per entry and an exception could be thrown if it is.

Parameters:

division - The division the entry belongs too.

Throws:

ParseException - If the Listener cannot understand the event, is unable to deal with the event or is not expecting the event.

setDescription

void setDescription(String description)
                    throws ParseException

Call back method so the event emitter can tell the listener the description of the record being read. For example the description line of a FASTA format file would be the description. This method would typically be called 0 or 1 times and may cause an exception if it is called more than once per entry.

Parameters:

description - The description of the record

Throws:

ParseException - If the Listener cannot understand the event, is unable to deal with the event or is not expecting the event.

setVersion

void setVersion(int version)
                throws ParseException

Call back method so the event emitter can tell the listener the version of the record being read. This method would typically be called 0 or 1 times per entry. If it is not called the Listener should assume the version is 0. If it is called more than once per entry an exception should be thrown.

Parameters:

version - the version of the record

Throws:

ParseException - If the Listener cannot understand the event, is unable to deal with the event or is not expecting the event.

setSeqVersion

void setSeqVersion(String version)
                   throws ParseException

Call back method so the event emitter can tell the listener the version of the sequence of the record being read. This method would typically be called 0 or 1 times per entry. If it is not called the Listener should assume the version is 0. If it is called more than once per entry an exception should be thrown.

Parameters:

version - the version of the record

Throws:

ParseException - If the Listener cannot understand the event, is unable to deal with the event or is not expecting the event.

setComment

void setComment(String comment)
                throws ParseException

Call back method so the event emitter can tell the listener about a comment in the record being read. The comment is typically one or more comment lines relevant to the record as a whole and bundled in a Commment object. This method may be called zero or one times per entry. It can be called zero or more times.

Parameters:

comment - The comment

Throws:

ParseException - If the Listener cannot understand the event, is unable to deal with the event or is not expecting the event.

setRankedDocRef

void setRankedDocRef(RankedDocRef ref)
                     throws ParseException

Call back method so the event emitter can tell the listener about a literature reference in the record being read. This method may be called zero or more times.

Parameters:

ref - A literature reference contained in the entry.

Throws:

ParseException - If the Listener cannot understand the event, is unable to deal with the event or is not expecting the event.

setTaxon

void setTaxon(NCBITaxon taxon)
              throws ParseException

Call back method so the event emitter can tell the listener the Taxon of the record being read. This method may be called zero or one times. An exception may be thrown if it is called more than once. As a design decision NCBI's taxon model was chosen as it is commonly used and is supported by the BioSQL schema. The setting of an NCBI taxon should be considered entirely optional.

Parameters:

taxon - The taxon information relevant to this entry.

Throws:

ParseException - If the Listener cannot understand the event, is unable to deal with the event or is not expecting the event.

setNamespace

void setNamespace(Namespace namespace)
                  throws ParseException

Call back method so the event emitter can tell the listener the namespace of the record being read. The method can be called zero or one time. If it is called more than once an exception may be thrown.

The namespace is a concept from the BioSQL schema that enables Bioentries to be disambiguated. It is possible in BioSQL and should be possible in other collections of BioEntries to have records that have the same name, accession and version but different namespaces. This method would be expected to be called if you are reading a sequence from a biosql database or if you are implementing a listener that knows how to write to a biosql database. If you give a sequence a namespace and it is persited to biosql at somepoint in it's life you could expect it to be persisted to that namespace (if possible).

Parameters:

namespace - The namespace of the entry.

Throws:

ParseException - If the Listener cannot understand the event, is unable to deal with the event or is not expecting the event.

setRelationship

void setRelationship(BioEntryRelationship relationship)
                     throws ParseException

Call back method so the event emitter can tell the listener about a relationship between the bioentry or sequence in the record being read and another bioentry. This may be called zero or more times.

Parameters:

relationship - The relationship

Throws:

ParseException - If the Listener cannot understand the event, is unable to deal with the event or is not expecting the event.

setRankedCrossRef

void setRankedCrossRef(RankedCrossRef crossRef)
                       throws ParseException

Call back method so the event emitter can tell the listener about a cross reference. This could be called zero or more times per entry.

Parameters:

crossRef - the cross reference

Throws:

ParseException - If the Listener cannot understand the event, is unable to deal with the event or is not expecting the event.

setURI

void setURI(String uri)
            throws ParseException

Deprecated. There is no clear mapping between URI and BioSQL. This method is no longer used or supported in biojavax. Don't use it. Calling it may result in exceptions. Use instead setName(String name), setAccession(String accession), setVersion(int version) etc as appropriate.

Notify the listener of a URI identifying the current sequence.

Specified by:

setURI in interface SeqIOListener

Throws:

ParseException

getCurrentFeature

RichFeature getCurrentFeature()
                              throws ParseException

Gets the feature currently being created.

Returns:

the feature under construction.

Throws:

ParseException - if a feature is not currently being created.

setCircular

void setCircular(boolean circular)
                 throws ParseException

Defined this sequence being parser as circular. It is best to call this as early as possible during parsing. It should definitely be called before doing anything with locations or features.

Parameters:

circular - set this to true if you want it to be circular.

Throws:

ParseException - If the Listener cannot understand the event, is unable to deal with the event or is not expecting the event.