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;
023import java.util.Set;
024
025import org.biojava.bio.BioException;
026import org.biojava.bio.seq.db.IllegalIDException;
027import org.biojava.utils.ChangeType;
028import org.biojava.utils.ChangeVetoException;
029import org.biojavax.bio.BioEntry;
030
031/**
032 * A database of BioEntrys. This may have several implementations with
033 * rich behaviour, but basically most of the time you will just use
034 * the interface methods to do stuff. A BioEntry database contains a
035 * finite number of BioEntrys stored under unique keys.
036 *
037 * @author Matthew Pocock
038 * @author Gerald Loeffler
039 * @author Thomas Down
040 * @author Richard Holland
041 * @since 1.5
042 */
043public interface BioEntryDBLite {
044    /**
045     * Signals that sequences are being added to or remove from the database.
046     * The sequences being removed should be listed in the previous field by
047     * id, either as a single String, an array or a Set. The sequences
048     * being added should be listed in the change field as either an array
049     * Object[] { id, seq}, or a Map of id->seq.
050     */
051    public static final ChangeType BIOENTRYS = new ChangeType(
052            "BioEntrys have been added or removed from the database",
053            "org.biojavax.bio.db.BioEntryDB",
054            "BIOENTRYS"
055            );
056    
057    /**
058     * Get the name of this sequence database.
059     *
060     * @return the name of the sequence database, which may be null.
061     */
062    public String getName();
063    
064    /**
065     * Retrieve a single BioEntry by its id.
066     *
067     * @param id the id to retrieve by
068     * @return  the BioEntry with that id
069     * @throws IllegalIDException if the database doesn't know about the id
070     * @throws BioException if there was a failure in retrieving the BioEntry
071     */
072    public BioEntry getBioEntry(String id) throws IllegalIDException, BioException;
073    
074    /**
075     * Retrieve multiple BioEntry by their ids.
076     *
077     * @param ids a set of ids to retrieve by
078     * @return  the BioEntrys with those ids
079     * @throws IllegalIDException if the database doesn't know about the id
080     */
081    public BioEntryDB getBioEntrys(Set ids) throws BioException,IllegalIDException;
082    
083    /**
084     * Retrieve multiple BioEntry into a specific sequence database. If
085     * that database is null, a new HashBioEntryDB is used.
086     *
087     * @param ids a set of ids to retrieve by
088     * @param db a database to load the seqs into
089     * @return  the BioEntrys with that id
090     * @throws IllegalIDException if the database doesn't know about the id
091     */
092    public BioEntryDB getBioEntrys(Set ids, BioEntryDB db) throws BioException,IllegalIDException;
093    
094    /**
095     * Adds a sequence to the database.
096     *
097     * @param seq the BioEntry to add
098     * @throws IllegalIDException if a uniqe ID could not be generated for BioEntry
099     * @throws BioException if something goes wrong with adding the BioEntry
100     * @throws ChangeVetoException  if either the database does not allow
101     *         BioEntrys to be added or the modification was vetoed
102     */
103    public void addBioEntry(BioEntry seq) throws IllegalIDException, BioException, ChangeVetoException;
104    
105    /**
106     * Remove the BioEntry associated with an ID from the database.
107     *
108     * @param id  the ID of the BioEntry to remove
109     * @throws  IllegalIDException if there is no BioEntry for the ID
110     * @throws  BioException if something failed while removing the BioEntry for
111     *          that ID
112     * @throws  ChangeVetoException  if either the database does not allow
113     *          BioEntrys to be removed or the modification was vetoed
114     */
115    public void removeBioEntry(String id) throws IllegalIDException, BioException, ChangeVetoException;
116}