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.search;
023
024import java.util.Map;
025import java.util.Set;
026
027import org.biojava.bio.BioException;
028import org.biojava.bio.seq.db.SequenceDB;
029import org.biojava.bio.symbol.SymbolList;
030
031/**
032 * Objects of this type represent one particular installation (not
033 * just implementation) of a sequence similarity searcher such as
034 * BLASTP.  Objects of this type must be immutable such that all
035 * parameters affecting the outcome of a search must be passed as an
036 * argument to the search() method.
037 *
038 * @author <A href="mailto:Gerald.Loeffler@vienna.at">Gerald
039 * Loeffler</A> for the <A href="http://www.imp.univie.ac.at">IMP</A>
040 *
041 */
042public interface SeqSimilaritySearcher
043{
044    /**
045     * Return a set of all databases that can be searched with this
046     * sequence similarity searcher. This method reflects the fact
047     * that objects of this type represent a particular installation
048     * of a searcher which has access to only a limited number of
049     * databases.
050     *
051     * @return an unmodifiable Set of SequenceDB objects. Never
052     * returns null but may return an empty set.
053     */
054    Set getSearchableDBs();
055  
056    /**
057     * Using this sequence similarity searcher, search with the given
058     * sequence against the given sequence database. It is a
059     * precondition that the sequence and the sequence database be
060     * compatible with each other and with this sequence similarity
061     * searcher, otherwise an IllegalArgumentException is thrown.
062     *
063     * <p> Particular implementations of a searcher will differ in the
064     * number and kind of parameters that can be used to customize a
065     * search. All these parameters must be passed as an argument to
066     * this method, i.e. these parameters are not part of the state of
067     * this searcher.
068     *
069     * <p> This method performs a synchronous search, i.e. it will
070     * block until the search result becomes available.
071     *
072     * @param querySeq the sequence with which to search.  May not be
073     * null otherwise an IllegalArgumentException is thrown.
074     * @param db the sequence database against which the similarity
075     * search will be performed.  May not be null otherwise an
076     * IllegalArgumentException is thrown. Must also be an element of
077     * the set of searchable dbs returned by getSearchableDBs().
078     * @param searchParameters parameters that customize the
079     * search. Null must always be a legal value for this argument and
080     * results in a default search being performed. If this map
081     * contains keys and/or values that are not supported by a
082     * particular implementation of this interface, an
083     * IllegalArgumentException is thrown.
084     *
085     * @return the sequence similarity search result that encapsulates
086     * the result of the search. Never returns null.
087     *
088     * @exception BioException if the actual search fails for some
089     * reason. If, however, the search can not even be started,
090     * because a precondition is not met, an IllegalArgumentException
091     * is thrown.
092     */
093    SeqSimilaritySearchResult search(SymbolList querySeq,
094                                     SequenceDB db,
095                                     Map        searchParameters) 
096        throws BioException;
097}