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;
023
024import org.biojava.bio.BioException;
025import org.biojava.bio.symbol.IllegalAlphabetException;
026import org.biojava.utils.ChangeVetoException;
027
028/**
029 * An object which adds some additional information to a Sequence.
030 *
031 * <p>
032 * There are two approaches which can be taken to adding features
033 * to a sequence:
034 *
035 * <ol><li>Directly adding features to a Sequence which implements
036 * MutableFeatureHolder</li>
037 * <li>Creating a new Sequence object which acts as a view on an
038 * underlying Sequence, and presents extra features.</li></ol>
039 *
040 * At present, this interface supports both these mechanisms.  It
041 * is the responsibility of the implementor to document which approach
042 * is taken.
043 * </p>
044 *
045 * @author Thomas Down
046 */
047
048public interface SequenceAnnotator {
049    /**
050     * Return an annotated version of a sequence.
051     *
052     * @param seq The sequence to be annotated.
053     * @return An annotated version of <code>seq</code> (may be the
054     *          same object).
055     * @throws IllegalAlphabetException If the sequence is over
056     *                                  an inappropriate alphabet for
057     *                                  the annotated method being
058     *                                  encapsulated
059     * @throws BioException if the sequence fails to be annotated
060     * @throws ChangeVetoException if either the sequence doesn't allow
061     *         annotation or if the change was vetoed
062     */
063
064    public Sequence annotate(Sequence seq) throws BioException,
065                                              IllegalAlphabetException,
066                                              ChangeVetoException;
067    
068}