Searchable.java
001 package gate.creole.annic.apache.lucene.search;
002 
003 /**
004  * Copyright 2004 The Apache Software Foundation
005  *
006  * Licensed under the Apache License, Version 2.0 (the "License");
007  * you may not use this file except in compliance with the License.
008  * You may obtain a copy of the License at
009  *
010  *     http://www.apache.org/licenses/LICENSE-2.0
011  *
012  * Unless required by applicable law or agreed to in writing, software
013  * distributed under the License is distributed on an "AS IS" BASIS,
014  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
015  * See the License for the specific language governing permissions and
016  * limitations under the License.
017  */
018 
019 import java.io.IOException;
020 
021 import gate.creole.annic.apache.lucene.document.Document;
022 import gate.creole.annic.apache.lucene.index.Term;
023 
024 /** The interface for search implementations.
025  *
026  <p>Implementations provide search over a single index, over multiple
027  * indices, and over indices on remote servers.
028  */
029 public interface Searchable extends java.rmi.Remote {
030   /** Lower-level search API.
031    *
032    <p>{@link HitCollector#collect(int,float)} is called for every non-zero
033    * scoring document.
034    *
035    <p>Applications should only use this if they need <i>all</i> of the
036    * matching documents.  The high-level search API ({@link
037    * Searcher#search(Query)}) is usually more efficient, as it skips
038    * non-high-scoring hits.
039    *
040    @param query to match documents
041    @param filter if non-null, a bitset used to eliminate some documents
042    @param results to receive hits
043    */
044   void search(Query query, Filter filter, HitCollector results)
045     throws IOException;
046 
047   /** Frees resources associated with this Searcher.
048    * Be careful not to call this method while you are still using objects
049    * like {@link Hits}.
050    */
051   void close() throws IOException;
052 
053   /** Expert: Returns the number of documents containing <code>term</code>.
054    * Called by search code to compute term weights.
055    @see gate.creole.annic.apache.lucene.index.IndexReader#docFreq(Term).
056    */
057   int docFreq(Term termthrows IOException;
058 
059   /** Expert: Returns one greater than the largest possible document number.
060    * Called by search code to compute term weights.
061    @see gate.creole.annic.apache.lucene.index.IndexReader#maxDoc().
062    */
063   int maxDoc() throws IOException;
064 
065   /** Expert: Low-level search implementation.  Finds the top <code>n</code>
066    * hits for <code>query</code>, applying <code>filter</code> if non-null.
067    *
068    <p>Called by {@link Hits}.
069    *
070    <p>Applications should usually call {@link Searcher#search(Query)} or
071    {@link Searcher#search(Query,Filter)} instead.
072    */
073   TopDocs search(Query query, Filter filter, int nthrows IOException;
074 
075   /** Expert: Returns the stored fields of document <code>i</code>.
076    * Called by {@link HitCollector} implementations.
077    @see gate.creole.annic.apache.lucene.index.IndexReader#document(int).
078    */
079   Document doc(int ithrows IOException;
080 
081   /** Expert: called to re-write queries into primitive queries. */
082   Query rewrite(Query querythrows IOException;
083 
084   /** Returns an Explanation that describes how <code>doc</code> scored against
085    <code>query</code>.
086    *
087    <p>This is intended to be used in developing Similarity implementations,
088    * and, for good performance, should not be displayed with every hit.
089    * Computing an explanation is as expensive as executing the query over the
090    * entire index.
091    */
092   Explanation explain(Query query, int docthrows IOException;
093 
094   /** Expert: Low-level search implementation with arbitrary sorting.  Finds
095    * the top <code>n</code> hits for <code>query</code>, applying
096    <code>filter</code> if non-null, and sorting the hits by the criteria in
097    <code>sort</code>.
098    *
099    <p>Applications should usually call {@link
100    * Searcher#search(Query,Filter,Sort)} instead.
101    */
102   TopFieldDocs search(Query query, Filter filter, int n, Sort sort)
103     throws IOException;
104 }