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 import gate.creole.annic.apache.lucene.index.IndexReader; // for javadoc
024
025 /** The interface for search implementations.
026 *
027 * <p>Implementations provide search over a single index, over multiple
028 * indices, and over indices on remote servers.
029 */
030 public interface Searchable extends java.rmi.Remote {
031 /** Lower-level search API.
032 *
033 * <p>{@link HitCollector#collect(int,float)} is called for every non-zero
034 * scoring document.
035 *
036 * <p>Applications should only use this if they need <i>all</i> of the
037 * matching documents. The high-level search API ({@link
038 * Searcher#search(Query)}) is usually more efficient, as it skips
039 * non-high-scoring hits.
040 *
041 * @param query to match documents
042 * @param filter if non-null, a bitset used to eliminate some documents
043 * @param results to receive hits
044 */
045 void search(Query query, Filter filter, HitCollector results)
046 throws IOException;
047
048 /** Frees resources associated with this Searcher.
049 * Be careful not to call this method while you are still using objects
050 * like {@link Hits}.
051 */
052 void close() throws IOException;
053
054 /** Expert: Returns the number of documents containing <code>term</code>.
055 * Called by search code to compute term weights.
056 * @see IndexReader#docFreq(Term).
057 */
058 int docFreq(Term term) throws IOException;
059
060 /** Expert: Returns one greater than the largest possible document number.
061 * Called by search code to compute term weights.
062 * @see IndexReader#maxDoc().
063 */
064 int maxDoc() throws IOException;
065
066 /** Expert: Low-level search implementation. Finds the top <code>n</code>
067 * hits for <code>query</code>, applying <code>filter</code> if non-null.
068 *
069 * <p>Called by {@link Hits}.
070 *
071 * <p>Applications should usually call {@link Searcher#search(Query)} or
072 * {@link Searcher#search(Query,Filter)} instead.
073 */
074 TopDocs search(Query query, Filter filter, int n) throws IOException;
075
076 /** Expert: Returns the stored fields of document <code>i</code>.
077 * Called by {@link HitCollector} implementations.
078 * @see IndexReader#document(int).
079 */
080 Document doc(int i) throws IOException;
081
082 /** Expert: called to re-write queries into primitive queries. */
083 Query rewrite(Query query) throws IOException;
084
085 /** Returns an Explanation that describes how <code>doc</code> scored against
086 * <code>query</code>.
087 *
088 * <p>This is intended to be used in developing Similarity implementations,
089 * and, for good performance, should not be displayed with every hit.
090 * Computing an explanation is as expensive as executing the query over the
091 * entire index.
092 */
093 Explanation explain(Query query, int doc) throws IOException;
094
095 /** Expert: Low-level search implementation with arbitrary sorting. Finds
096 * the top <code>n</code> hits for <code>query</code>, applying
097 * <code>filter</code> if non-null, and sorting the hits by the criteria in
098 * <code>sort</code>.
099 *
100 * <p>Applications should usually call {@link
101 * Searcher#search(Query,Filter,Sort)} instead.
102 */
103 TopFieldDocs search(Query query, Filter filter, int n, Sort sort)
104 throws IOException;
105 }
|