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.biojavax.bio.db;
023
024import java.util.Set;
025
026import org.biojava.bio.BioException;
027import org.biojava.bio.seq.db.IllegalIDException;
028import org.biojava.bio.seq.db.SequenceDBLite;
029import org.biojava.utils.ChangeVetoException;
030import org.biojavax.bio.seq.RichSequence;
031
032/**
033 * A database of RichSequences. This may have several implementations with
034 * rich behaviour, but basically most of the time you will just use
035 * the interface methods to do stuff. A RichSequence database contains a
036 * finite number of RichSequences stored under unique keys.
037 *
038 * @author Matthew Pocock
039 * @author Gerald Loeffler
040 * @author Thomas Down
041 * @author Richard Holland
042 * @since 1.5
043 */
044public interface RichSequenceDBLite extends BioEntryDBLite,SequenceDBLite {      
045    /**
046     * Retrieve a single RichSequence by its id.
047     *
048     * @param id the id to retrieve by
049     * @return  the Sequence with that id
050     * @throws IllegalIDException if the database doesn't know about the id
051     */
052    public RichSequence getRichSequence(String id) throws BioException,IllegalIDException;
053    
054    /**
055     * Retrieve multiple RichSequence by its id.
056     *
057     * @param ids a set of ids to retrieve by
058     * @return  the RichSequences with that id
059     * @throws IllegalIDException if the database doesn't know about the id
060     */
061    public RichSequenceDB getRichSequences(Set ids) throws BioException,IllegalIDException;
062    
063    /**
064     * Retrieve multiple RichSequence into a specific sequence database. If
065     * that database is null, a new HashRichSequenceDB is used.
066     *
067     * @param ids a set of ids to retrieve by
068     * @param db a database to load the seqs into
069     * @return  the RichSequences with that id
070     * @throws IllegalIDException if the database doesn't know about the id
071     */
072    public RichSequenceDB getRichSequences(Set ids, RichSequenceDB db) throws BioException,IllegalIDException;
073    
074    /**
075     * Adds a sequence to the database.
076     *
077     * @param seq the RichSequence to add
078     * @throws IllegalIDException if a uniqe ID could not be generated for RichSequence
079     * @throws BioException if something goes wrong with adding the RichSequence
080     * @throws ChangeVetoException  if either the database does not allow
081     *         RichSequences to be added or the modification was vetoed
082     */
083    public void addRichSequence(RichSequence seq) throws IllegalIDException, BioException, ChangeVetoException;
084    
085    /**
086     * Remove the RichSequence associated with an ID from the database.
087     *
088     * @param id  the ID of the RichSequence to remove
089     * @throws  IllegalIDException if there is no RichSequence for the ID
090     * @throws  BioException if something failed while removing the RichSequence for
091     *          that ID
092     * @throws  ChangeVetoException  if either the database does not allow
093     *          RichSequences to be removed or the modification was vetoed
094     */
095    public void removeRichSequence(String id) throws IllegalIDException, BioException, ChangeVetoException;
096}