org.biojavax.bio.seq.io
Class SimpleRichSequenceBuilder

java.lang.Object
  org.biojavax.bio.seq.io.RichSeqIOAdapter
      org.biojavax.bio.seq.io.SimpleRichSequenceBuilder

All Implemented Interfaces:

SeqIOListener, SequenceBuilder, RichSeqIOListener, RichSequenceBuilder

public class SimpleRichSequenceBuilder
extends RichSeqIOAdapter
implements RichSequenceBuilder

Constructs BioEntry objects by listening to events.

Since:

1.5

Author:

Richard Holland, George Waldon

Field Summary

Fields inherited from class org.biojavax.bio.seq.io.RichSeqIOAdapter

emptyFeature

Constructor Summary

SimpleRichSequenceBuilder()
Creates a new instance of SimpleRichSequenceBuilder using a SimpleSymbolListFactory with a threshold of zero.

SimpleRichSequenceBuilder(SymbolListFactory factory)
Creates a new instance of SimpleRichSequenceBuilder with the desired symbollistfactory and threshold of zero.

SimpleRichSequenceBuilder(SymbolListFactory factory, int threshold)
Creates a new instance of SimpleRichSequenceBuilder with the desired symbollistfactory and threshold.

Method Summary

void	addFeatureProperty(Object key, Object value) Notify the listener of a feature property.
void	addSequenceProperty(Object key, Object value) Notify the listener of a sequence-wide property.
void	addSymbols(Alphabet alpha, Symbol[] syms, int start, int length) Notify the listener of symbol data.
void	endFeature() Mark the end of data associated with one specific feature.
void	endSequence() Notify the listener that processing of the sequence is complete.
RichFeature	getCurrentFeature() Gets the feature currently being created.
RichSequence	makeRichSequence() Build a RichSequence.
Sequence	makeSequence() Return the Sequence object which has been constructed by this builder.
void	setAccession(String accession) Call back method so the event emitter can tell the listener the accession of the record being read. The last accession passed to this routine will always be the one used.
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	setName(String name) Notify the listener that the current sequence is generally known by a particular name.
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 ref) 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 seqVersion) 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) Notify the listener of a URI identifying the current sequence. NOT IMPLEMENTED
void	setVersion(int version) Call back method so the event emitter can tell the listener the version of the record being read.
void	startFeature(Feature.Template templ) Notify the listener that a new feature object is starting.
void	startSequence() Start the processing of a sequence.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

SimpleRichSequenceBuilder

public SimpleRichSequenceBuilder()

Creates a new instance of SimpleRichSequenceBuilder using a SimpleSymbolListFactory with a threshold of zero.

SimpleRichSequenceBuilder

public SimpleRichSequenceBuilder(SymbolListFactory factory)

Creates a new instance of SimpleRichSequenceBuilder with the desired symbollistfactory and threshold of zero.

Parameters:

factory - the symbollistfactory to use from the start.

SimpleRichSequenceBuilder

public SimpleRichSequenceBuilder(SymbolListFactory factory,
                                 int threshold)

Creates a new instance of SimpleRichSequenceBuilder with the desired symbollistfactory and threshold.

Parameters:

factory - the symbollistfactory to use.

threshold - the threshold at which the specified symbollistfactory should come into use. If <=0, it will be used from the start.

Method Detail

setVersion

public 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.

Specified by:

setVersion in interface RichSeqIOListener

Overrides:

setVersion in class RichSeqIOAdapter

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.

setURI

public void setURI(String uri)
            throws ParseException

Notify the listener of a URI identifying the current sequence. NOT IMPLEMENTED

Specified by:

setURI in interface SeqIOListener

Specified by:

setURI in interface RichSeqIOListener

Overrides:

setURI in class RichSeqIOAdapter

Throws:

ParseException

setSeqVersion

public void setSeqVersion(String seqVersion)
                   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.

Specified by:

setSeqVersion in interface RichSeqIOListener

Overrides:

setSeqVersion in class RichSeqIOAdapter

Parameters:

seqVersion - 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.

setAccession

public 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. The last accession passed to this routine will always be the one used.

Specified by:

setAccession in interface RichSeqIOListener

Overrides:

setAccession in class RichSeqIOAdapter

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), RichSeqIOListener.setURI(String uri), RichSeqIOListener.setIdentifier(String identifier)

setDescription

public 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.

Specified by:

setDescription in interface RichSeqIOListener

Overrides:

setDescription in class RichSeqIOAdapter

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.

setDivision

public 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.

Specified by:

setDivision in interface RichSeqIOListener

Overrides:

setDivision in class RichSeqIOAdapter

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.

setIdentifier

public 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.

Specified by:

setIdentifier in interface RichSeqIOListener

Overrides:

setIdentifier in class RichSeqIOAdapter

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), RichSeqIOListener.setAccession(String accession), RichSeqIOListener.setURI(String uri)

setName

public void setName(String name)
             throws ParseException

Notify the listener that the current sequence is generally known by a particular name.

Specified by:

setName in interface SeqIOListener

Overrides:

setName in class RichSeqIOAdapter

Parameters:

name - the String that should be returned by getName for the sequence being parsed

Throws:

ParseException

setRankedCrossRef

public void setRankedCrossRef(RankedCrossRef ref)
                       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.

Specified by:

setRankedCrossRef in interface RichSeqIOListener

Overrides:

setRankedCrossRef in class RichSeqIOAdapter

Parameters:

ref - 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.

addSymbols

public void addSymbols(Alphabet alpha,
                       Symbol[] syms,
                       int start,
                       int length)
                throws IllegalAlphabetException

Notify the listener of symbol data. All symbols passed to this method are guarenteed to be contained within the specified alphabet. Generally all calls to a given Listener should have the same alphabet -- if not, the listener implementation is likely to throw an exception

Specified by:

addSymbols in interface SeqIOListener

Overrides:

addSymbols in class RichSeqIOAdapter

Parameters:

alpha - The alphabet of the symbol data

syms - An array containing symbols

start - The start offset of valid data within the array

length - The number of valid symbols in the array

Throws:

IllegalAlphabetException - if we can't cope with this alphabet.

setComment

public 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.

Specified by:

setComment in interface RichSeqIOListener

Overrides:

setComment in class RichSeqIOAdapter

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.

setNamespace

public 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).

Specified by:

setNamespace in interface RichSeqIOListener

Overrides:

setNamespace in class RichSeqIOAdapter

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.

startFeature

public void startFeature(Feature.Template templ)
                  throws ParseException

Notify the listener that a new feature object is starting. Every call to startFeature should have a corresponding call to endFeature. If the listener is concerned with a hierarchy of features, it should maintain a stack of `open' features.

Specified by:

startFeature in interface SeqIOListener

Overrides:

startFeature in class RichSeqIOAdapter

Throws:

ParseException

getCurrentFeature

public RichFeature getCurrentFeature()
                              throws ParseException

Gets the feature currently being created.

Specified by:

getCurrentFeature in interface RichSeqIOListener

Overrides:

getCurrentFeature in class RichSeqIOAdapter

Returns:

the feature under construction.

Throws:

ParseException - if a feature is not currently being created.

setTaxon

public 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.

Specified by:

setTaxon in interface RichSeqIOListener

Overrides:

setTaxon in class RichSeqIOAdapter

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.

setRelationship

public 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.

Specified by:

setRelationship in interface RichSeqIOListener

Overrides:

setRelationship in class RichSeqIOAdapter

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.

setRankedDocRef

public 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.

Specified by:

setRankedDocRef in interface RichSeqIOListener

Overrides:

setRankedDocRef in class RichSeqIOAdapter

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.

startSequence

public void startSequence()
                   throws ParseException

Start the processing of a sequence. This method exists primarily to enforce the life-cycles of SeqIOListener objects.

Specified by:

startSequence in interface SeqIOListener

Overrides:

startSequence in class RichSeqIOAdapter

Throws:

ParseException

addFeatureProperty

public void addFeatureProperty(Object key,
                               Object value)
                        throws ParseException

Notify the listener of a feature property.

Specified by:

addFeatureProperty in interface SeqIOListener

Overrides:

addFeatureProperty in class RichSeqIOAdapter

Throws:

ParseException

addSequenceProperty

public void addSequenceProperty(Object key,
                                Object value)
                         throws ParseException

Notify the listener of a sequence-wide property. This might be stored as an entry in the sequence's annotation bundle.

Specified by:

addSequenceProperty in interface SeqIOListener

Overrides:

addSequenceProperty in class RichSeqIOAdapter

Throws:

ParseException

endFeature

public void endFeature()
                throws ParseException

Mark the end of data associated with one specific feature.

Specified by:

endFeature in interface SeqIOListener

Overrides:

endFeature in class RichSeqIOAdapter

Throws:

ParseException

endSequence

public void endSequence()
                 throws ParseException

Notify the listener that processing of the sequence is complete.

Specified by:

endSequence in interface SeqIOListener

Overrides:

endSequence in class RichSeqIOAdapter

Throws:

ParseException

setCircular

public 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.

Specified by:

setCircular in interface RichSeqIOListener

Overrides:

setCircular in class RichSeqIOAdapter

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.

makeSequence

public Sequence makeSequence()
                      throws BioException

Return the Sequence object which has been constructed by this builder. This method is only expected to succeed after the endSequence() notifier has been called.

Specified by:

makeSequence in interface SequenceBuilder

Specified by:

makeSequence in interface RichSequenceBuilder

Throws:

BioException

makeRichSequence

public RichSequence makeRichSequence()
                              throws BioException

Build a RichSequence.

Specified by:

makeRichSequence in interface RichSequenceBuilder

Returns:

a RichSequence

Throws:

BioException - if it is not possible to build a RichSequence