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
024
025/**
026 * <code>SearchContentHandler</code> is a notification interface for
027 * objects which listen to search stream parsers. This is applicable
028 * to all types of search results which are represented by flat files
029 * created by external programs e.g. Fasta, (T)BlastN/PX, EMBOSS
030 * programs. This is not limited to sequence similarity searches, but
031 * includes any format consisting of a header followed by hits, each
032 * of which may, or may not, have subhits.
033 *
034 * @author Keith James
035 * @since 1.1
036 */
037public interface SearchContentHandler
038{
039    /**
040     * <code>getMoreSearches</code> returns the state of the
041     * <code>SearchContentHandler</code> with respect to further
042     * searches from its data source. Used for handling streams of
043     * search results.
044     *
045     * @return a <code>boolean</code> value.
046     */
047    public boolean getMoreSearches();
048
049    /**
050     * <code>setMoreSearches</code> sets the state of the
051     * <code>SearchContentHandler</code>'s expectation of receiving
052     * more results. Used for handling streams of search results.
053     *
054     * @param value a <code>boolean</code> value.
055     */
056    public void setMoreSearches(boolean value);
057
058    /**
059     * The <code>startSearch</code> method indicates the start of
060     * useful search information.
061     */
062    public void startSearch();
063
064    /**
065     * The <code>endSearch</code> method indicates the end of useful
066     * search information.
067     */
068    public void endSearch();
069
070    /**
071     * The <code>startHeader</code> method indicates the start of a
072     * formatted header. This usually contains information relevant to
073     * the search as a whole.
074     */
075    public void startHeader();
076
077    /**
078     * The <code>endHeader</code> method indicates the end of a
079     * formatted header.
080     */
081    public void endHeader();
082
083    /**
084     * The <code>startHit</code> method indicates the start of a
085     * formatted hit. This could be a single line, or a block of
086     * lines.
087     */
088    public void startHit();
089
090    /**
091     * The <code>endHit</code> method indicates the end of a formatted
092     * hit.
093     */
094    public void endHit();
095
096    /**
097     * The <code>startSubHit</code> method indicates the start of a
098     * formatted subhit. There may be zero or more of these per hit.
099     */
100    public void startSubHit();
101
102    /**
103     * The <code>endSubHit</code> method indicates the end of a
104     * formatted subhit.
105     */
106    public void endSubHit();
107
108    /**
109     * The <code>addSearchProperty</code> method adds a key/value pair
110     * containing some property of the overall search result.
111     *
112     * @param key an <code>Object</code>.
113     * @param value an <code>Object</code>.
114     */
115    public void addSearchProperty(Object key, Object value);
116
117    /**
118     * The <code>addHitProperty</code> method adds a key/value pair
119     * containing some property of a particular hit.
120     *
121     * @param key an <code>Object</code>.
122     * @param value an <code>Object</code>.
123     */
124    public void addHitProperty(Object key, Object value);
125
126    /**
127     * The <code>addSubHitProperty</code> method adds a key/value pair
128     * containing some property of a particular subhit.
129     *
130     * @param key an <code>Object</code>.
131     * @param value an <code>Object</code>.
132     */
133    public void addSubHitProperty(Object key, Object value);
134
135    /**
136     * <code>setQueryID</code> identifies the query sequence by a
137     * name, ID or URN.
138     *
139     * @param queryID a <code>String</code> which should be an unique
140     * identifer for the sequence.
141     */
142    public void setQueryID(String queryID);
143
144    /**
145     * <code>setDatabaseID</code> identifies the database searched by
146     * a name, ID or URN.
147     *
148     * @param databaseID a <code>String</code> which should be an unique
149     * identifier for the database searched.
150     */
151    public void setDatabaseID(String databaseID);
152}