001: package org.apache.lucene.search;
002:
003: /**
004: * Licensed to the Apache Software Foundation (ASF) under one or more
005: * contributor license agreements. See the NOTICE file distributed with
006: * this work for additional information regarding copyright ownership.
007: * The ASF licenses this file to You under the Apache License, Version 2.0
008: * (the "License"); you may not use this file except in compliance with
009: * the License. You may obtain a copy of the License at
010: *
011: * http://www.apache.org/licenses/LICENSE-2.0
012: *
013: * Unless required by applicable law or agreed to in writing, software
014: * distributed under the License is distributed on an "AS IS" BASIS,
015: * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
016: * See the License for the specific language governing permissions and
017: * limitations under the License.
018: */
019:
020: import org.apache.lucene.document.Document;
021: import org.apache.lucene.document.FieldSelector;
022: import org.apache.lucene.index.IndexReader;
023: import org.apache.lucene.index.Term;
024: import org.apache.lucene.index.CorruptIndexException;
025:
026: import java.io.IOException; // for javadoc
027:
028: /** The interface for search implementations.
029: *
030: * <p>Searchable is the abstract network protocol for searching.
031: * Implementations provide search over a single index, over multiple
032: * indices, and over indices on remote servers.
033: *
034: * <p>Queries, filters and sort criteria are designed to be compact so that
035: * they may be efficiently passed to a remote index, with only the top-scoring
036: * hits being returned, rather than every non-zero scoring hit.
037: */
038: public interface Searchable extends java.rmi.Remote {
039: /** Lower-level search API.
040: *
041: * <p>{@link HitCollector#collect(int,float)} is called for every non-zero
042: * scoring document.
043: * <br>HitCollector-based access to remote indexes is discouraged.
044: *
045: * <p>Applications should only use this if they need <i>all</i> of the
046: * matching documents. The high-level search API ({@link
047: * Searcher#search(Query)}) is usually more efficient, as it skips
048: * non-high-scoring hits.
049: *
050: * @param weight to match documents
051: * @param filter if non-null, a bitset used to eliminate some documents
052: * @param results to receive hits
053: * @throws BooleanQuery.TooManyClauses
054: */
055: void search(Weight weight, Filter filter, HitCollector results)
056: throws IOException;
057:
058: /** Frees resources associated with this Searcher.
059: * Be careful not to call this method while you are still using objects
060: * like {@link Hits}.
061: */
062: void close() throws IOException;
063:
064: /** Expert: Returns the number of documents containing <code>term</code>.
065: * Called by search code to compute term weights.
066: * @see IndexReader#docFreq(Term)
067: */
068: int docFreq(Term term) throws IOException;
069:
070: /** Expert: For each term in the terms array, calculates the number of
071: * documents containing <code>term</code>. Returns an array with these
072: * document frequencies. Used to minimize number of remote calls.
073: */
074: int[] docFreqs(Term[] terms) throws IOException;
075:
076: /** Expert: Returns one greater than the largest possible document number.
077: * Called by search code to compute term weights.
078: * @see IndexReader#maxDoc()
079: */
080: int maxDoc() throws IOException;
081:
082: /** Expert: Low-level search implementation. Finds the top <code>n</code>
083: * hits for <code>query</code>, applying <code>filter</code> if non-null.
084: *
085: * <p>Called by {@link Hits}.
086: *
087: * <p>Applications should usually call {@link Searcher#search(Query)} or
088: * {@link Searcher#search(Query,Filter)} instead.
089: * @throws BooleanQuery.TooManyClauses
090: */
091: TopDocs search(Weight weight, Filter filter, int n)
092: throws IOException;
093:
094: /** Expert: Returns the stored fields of document <code>i</code>.
095: * Called by {@link HitCollector} implementations.
096: * @see IndexReader#document(int)
097: * @throws CorruptIndexException if the index is corrupt
098: * @throws IOException if there is a low-level IO error
099: */
100: Document doc(int i) throws CorruptIndexException, IOException;
101:
102: /**
103: * Get the {@link org.apache.lucene.document.Document} at the <code>n</code><sup>th</sup> position. The {@link org.apache.lucene.document.FieldSelector}
104: * may be used to determine what {@link org.apache.lucene.document.Field}s to load and how they should be loaded.
105: *
106: * <b>NOTE:</b> If the underlying Reader (more specifically, the underlying <code>FieldsReader</code>) is closed before the lazy {@link org.apache.lucene.document.Field} is
107: * loaded an exception may be thrown. If you want the value of a lazy {@link org.apache.lucene.document.Field} to be available after closing you must
108: * explicitly load it or fetch the Document again with a new loader.
109: *
110: *
111: * @param n Get the document at the <code>n</code><sup>th</sup> position
112: * @param fieldSelector The {@link org.apache.lucene.document.FieldSelector} to use to determine what Fields should be loaded on the Document. May be null, in which case all Fields will be loaded.
113: * @return The stored fields of the {@link org.apache.lucene.document.Document} at the nth position
114: * @throws CorruptIndexException if the index is corrupt
115: * @throws IOException if there is a low-level IO error
116: *
117: * @see IndexReader#document(int, FieldSelector)
118: * @see org.apache.lucene.document.Fieldable
119: * @see org.apache.lucene.document.FieldSelector
120: * @see org.apache.lucene.document.SetBasedFieldSelector
121: * @see org.apache.lucene.document.LoadFirstFieldSelector
122: */
123: Document doc(int n, FieldSelector fieldSelector)
124: throws CorruptIndexException, IOException;
125:
126: /** Expert: called to re-write queries into primitive queries.
127: * @throws BooleanQuery.TooManyClauses
128: */
129: Query rewrite(Query query) throws IOException;
130:
131: /** Expert: low-level implementation method
132: * Returns an Explanation that describes how <code>doc</code> scored against
133: * <code>weight</code>.
134: *
135: * <p>This is intended to be used in developing Similarity implementations,
136: * and, for good performance, should not be displayed with every hit.
137: * Computing an explanation is as expensive as executing the query over the
138: * entire index.
139: * <p>Applications should call {@link Searcher#explain(Query, int)}.
140: * @throws BooleanQuery.TooManyClauses
141: */
142: Explanation explain(Weight weight, int doc) throws IOException;
143:
144: /** Expert: Low-level search implementation with arbitrary sorting. Finds
145: * the top <code>n</code> hits for <code>query</code>, applying
146: * <code>filter</code> if non-null, and sorting the hits by the criteria in
147: * <code>sort</code>.
148: *
149: * <p>Applications should usually call {@link
150: * Searcher#search(Query,Filter,Sort)} instead.
151: * @throws BooleanQuery.TooManyClauses
152: */
153: TopFieldDocs search(Weight weight, Filter filter, int n, Sort sort)
154: throws IOException;
155:
156: }
|