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.distributed;
023
024import java.util.Set;
025
026import org.biojava.bio.BioException;
027import org.biojava.bio.seq.FeatureFilter;
028import org.biojava.bio.seq.FeatureHolder;
029import org.biojava.bio.seq.Sequence;
030
031/**
032 * <p>Object which contributes data to a DistributedSequenceDB.</p>
033 *
034 * <p>DistDataSource is responsible for providing some information about what sequences exist,
035 * what the SymbolList associated with it and what features are here. Typically, the objects
036 * returned from DistributedSequenceDB will be composed from information from multiple
037 * DistDataSource instances.</p>
038 *
039 * @author Thomas Down
040 * @since 1.2
041 *
042 * Take an instance of this interface and add it to a DistributedSequenceDB.
043 *
044 * Implement this if you have information about some seqeunces but do not wish to or can
045 * not integrate this with the main sequence at source. For example, if you have some
046 * locally annotated features for SwissProt entries, you could create a DistDataSource
047 * providing just your features and let the DistDataSource API integrate these in software
048 * with a SwissProt sequence db provider.
049 *
050 * DistDataSource instances can provided sequence information and feature information. These
051 * are integrated seperately. To provide sequences, implement hasSequence(), getSequence() and
052 * ids(). ids(false).contains(id) should equal hasSequence(id). Features are provided by implementing
053 * hasFeatures(), and the two getFeatures() methods. In the case where hasFeatures() returns true,
054 * getFeatures() should return a FeatureHolder. If it is false, getFeatures() may raise a
055 * BioException. If these rules are not followed, the results are undefined and may not be
056 * consistent.
057 */
058
059public interface DistDataSource {
060  /**
061   * Find out if this DistDataSource provides the sequence information for a sequence ID.
062   *
063   * @param id  the String id of a sequence
064   * @return true if this DistDataSource provides the primary sequence, false otherwise
065   */
066  public boolean hasSequence(String id) throws BioException;
067  
068  /**
069   * Find out if this DistDataSource can provide features on a sequence with a particular ID.
070   *
071   * @param id  the String id of a sequence
072   * @return true if this DistDataSource provides features for the sequence, false otherwise
073   */
074  public boolean hasFeatures(String id) throws BioException;
075
076  /**
077   * Get all features matching a FeatureFilter provided by this DistDataSource.
078   * You can simulate getFeatures(id, ff, recurse) by using the advanced FeatureFilter
079   * implementations.
080   * @param ff  the FeatureFilter to search with
081   * @return a FeatureHolder with all matching filters
082   *
083   **/
084  public FeatureHolder getFeatures(FeatureFilter ff) throws BioException;
085  
086  /**
087   * Get all features matching a FeatureFilter on a Sequence with an ID and recurse flats.
088   * You can simulate getFeatures(ff) by adding the apropreate FeatureFilter implementations.
089   *
090   * @param id  the ID of the Sequence
091   * @param ff  the FeatureFilter to search with
092   * @param recurse true if we are to recurse the feature hierachy, false otherwise
093   * @return a FeatureHolder containing all feature matching
094   * @throws BioException if the features could not be fetched
095   *
096   */
097  public FeatureHolder getFeatures(String id, FeatureFilter ff, boolean recurse) throws BioException;
098  
099  /**
100   * Get a Sequence object for an ID.
101   *
102   * @param id  the ID of the Sequence to fetch
103   * @return a Seqeunce if hasSequence(id) would return true
104   * @throws BioException if either the ID could not be resolved or if the
105   *         sequence could not be fetched
106   */
107  public Sequence getSequence(String id) throws BioException;
108  
109  /**
110   * <p>Get the complete set of sequence IDs provided by this DistDataSource.</p>
111   *
112   * <p>If the recurse flat is true, the IDs associated with the top level will be returned.
113   * However, if it is false, then IDs should be returned for all levels of an assembly
114   * hierachy including the top level IDs.</p>
115   *
116   * @param topLevel  if true, return top level IDs, otherwise all IDs
117   * @return a Set of String IDs
118   * @throws BioException  if the IDs could not be fetched
119   */
120  public Set ids(boolean topLevel) throws BioException;
121}