[Biojava-l] [newio] Proposed event-notification interfaces

[Thomas Down]

--/9DWx/yDrRhgMJTb
Content-Type: text/plain; charset=us-ascii
Content-Disposition: inline

Hi...

I've been making a little more progress with my plans for
refactoring the sequence I/O framework for BioJava 1.1.  I've
attached two interfaces:

  SeqIOListener     Generic listener for events produced by
                    parsing biological sequence data

  SequenceBuilder   SeqIOListener which builds a new BioJava
                    sequence object.

Rebuilding the I/O framework around these interfaces would
meet the following objectives:

  - Decoupling all parts of the Sequence construction process
    from the file parsing.

  - An easy way to plug in filter and transducer objects between
    the parser and the Sequence construction step.

  - Potential to handle `feature-only' formats like GFF and GAME.

Issues which are still open:

  - Exactly how should multiple sequence alignments be handled
    within the framework?  One suggestion made internally at
    sanger would be to use a separate SequenceBuilder for each
    component of the alignments.  I'd welcome comments from anyone
    who uses BioJava Alignments on this topic.  Are there any
    commonly used formats for `annotated' alignments, with
    data which should be built into BioJava feature objects?

  - Are there any extra methods on SeqIOListener which I've
    missed?  For instance, it's tempting to have a specific
    method for notifying the listener about a sequence's
    database ID, if this is present in the file.  Any thoughts?

Let me know what you think of these,

   Thomas
-- 
``If I was going to carry a large axe on my back to a diplomatic
function I think I'd want it glittery too.''
           -- Terry Pratchett

--/9DWx/yDrRhgMJTb
Content-Type: text/plain; charset=us-ascii
Content-Disposition: attachment; filename="SeqIOListener.java"

package newio;

/**
 * Notification interface for objects which listen to a sequence stream
 * parser.
 *
 * @author Thomas Down
 * @since 1.1 [newio proposal]
 */

public interface SeqIOListener {
    /**
     * Start the processing of a sequence.  This method exists primarily
     * to enforce the life-cycles of SeqIOListener objects.
     */

    public void startSequence();

    /**
     * Notify the listener that processing of the sequence is complete.
     */

    public void endSequence();

    /**
     * Notify the listener of symbol data.
     *
     * <p>
     * NOTE: The SymbolReader is only guarenteed to be valid within
     * this call.  If the listener does not fully read all the data,
     * the parser <em>may</em> assume that it is not required, and
     * skip it.
     * </p>
     */

    public void addSymbols(SymbolReader sr)
        throws IOException, IllegalSymbolException;

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

    public void addSequenceProperty(String key, Object value);

    /**
     * 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.
     */

    public void startFeature(Feature.Template templ);

    /**
     * Mark the end of data associated with one specific feature.
     */

    public void endFeature();

    /**
     * Notify the listener of a feature property.
     */

    public void addFeatureProperty(String key, Object value);
}

--/9DWx/yDrRhgMJTb
Content-Type: text/plain; charset=us-ascii
Content-Disposition: attachment; filename="SequenceBuilder.java"

package newio;

import org.biojava.bio.seq.*;

/**
 * Interface for objects which accumulate state via SeqIOListener,
 * then construct a Sequence object.
 *
 * <p>
 * It is possible to build `transducer' objects which implement this
 * interface and pass on filtered notifications to a second, underlying
 * SequenceBuilder.  In this case, they should provide a
 * <code>makeSequence</code> method which delegates to the underlying
 * SequenceBuilder.
 * </p>
 *
 * @author Thomas Down
 * @since 1.1 [newio proposal]
 */

public interface SequenceBuilder extends SeqIOListener {
    /**
     * 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.
     */

    public Sequence makeSequence(); throws BioException;
}

--/9DWx/yDrRhgMJTb--