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.BioException;
025import org.biojava.bio.seq.Sequence;
026
027/**
028 * Interface for objects which accumulate state via SeqIOListener,
029 * then construct a Sequence object.
030 *
031 * <p>
032 * It is possible to build `transducer' objects which implement this
033 * interface and pass on filtered notifications to a second, underlying
034 * SequenceBuilder.  In this case, they should provide a
035 * <code>makeSequence</code> method which delegates to the underlying
036 * SequenceBuilder.
037 * </p>
038 *
039 * <b>Note:</b> These are one-shot objects that can be used just once to make
040 * one sequence. After that, they should be discarded. The usual way to get a
041 * supply of these is via a SequenceBuilderFactory.
042 *
043 * More functionality is offered by the 
044 * {@link org.biojavax.bio.seq.io.RichSequenceBuilder RichSequenceBuilder}.
045 * @author Thomas Down
046 * @since 1.1 [newio proposal]
047 * @see org.biojavax.bio.seq.io.RichSequenceBuilder
048 */
049
050public interface SequenceBuilder extends SeqIOListener {
051    /**
052     * Return the Sequence object which has been constructed
053     * by this builder.  This method is only expected to succeed
054     * after the endSequence() notifier has been called.
055     */
056
057    public Sequence makeSequence()
058            throws BioException;
059}