1 package org.apache.lucene.search;
2
3 /**
4 * Licensed to the Apache Software Foundation (ASF) under one or more
5 * contributor license agreements. See the NOTICE file distributed with
6 * this work for additional information regarding copyright ownership.
7 * The ASF licenses this file to You under the Apache License, Version 2.0
8 * (the "License"); you may not use this file except in compliance with
9 * the License. You may obtain a copy of the License at
10 *
11 * http://www.apache.org/licenses/LICENSE-2.0
12 *
13 * Unless required by applicable law or agreed to in writing, software
14 * distributed under the License is distributed on an "AS IS" BASIS,
15 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
16 * See the License for the specific language governing permissions and
17 * limitations under the License.
18 */
19
20 import org.apache.lucene.document.Document;
21 import org.apache.lucene.document.FieldSelector;
22 import org.apache.lucene.index.IndexReader;
23 import org.apache.lucene.index.Term;
24 import org.apache.lucene.index.CorruptIndexException;
25
26 import java.io.IOException; // for javadoc
27
28 /** The interface for search implementations.
29 *
30 * <p>Searchable is the abstract network protocol for searching.
31 * Implementations provide search over a single index, over multiple
32 * indices, and over indices on remote servers.
33 *
34 * <p>Queries, filters and sort criteria are designed to be compact so that
35 * they may be efficiently passed to a remote index, with only the top-scoring
36 * hits being returned, rather than every matching hit.
37 */
38 public interface Searchable extends java.rmi.Remote {
39 /** Lower-level search API.
40 *
41 * <p>{@link HitCollector#collect(int,float)} is called for every non-zero
42 * scoring document.
43 * <br>HitCollector-based access to remote indexes is discouraged.
44 *
45 * <p>Applications should only use this if they need <i>all</i> of the
46 * matching documents. The high-level search API ({@link
47 * Searcher#search(Query)}) is usually more efficient, as it skips
48 * non-high-scoring hits.
49 *
50 * @param weight to match documents
51 * @param filter if non-null, used to permit documents to be collected.
52 * @param results to receive hits
53 * @throws BooleanQuery.TooManyClauses
54 */
55 void search(Weight weight, Filter filter, HitCollector results)
56 throws IOException;
57
58
59 /** Frees resources associated with this Searcher.
60 * Be careful not to call this method while you are still using objects
61 * like {@link Hits}.
62 */
63 void close() throws IOException;
64
65 /** Expert: Returns the number of documents containing <code>term</code>.
66 * Called by search code to compute term weights.
67 * @see IndexReader#docFreq(Term)
68 */
69 int docFreq(Term term) throws IOException;
70
71 /** Expert: For each term in the terms array, calculates the number of
72 * documents containing <code>term</code>. Returns an array with these
73 * document frequencies. Used to minimize number of remote calls.
74 */
75 int[] docFreqs(Term[] terms) throws IOException;
76
77 /** Expert: Returns one greater than the largest possible document number.
78 * Called by search code to compute term weights.
79 * @see IndexReader#maxDoc()
80 */
81 int maxDoc() throws IOException;
82
83 /** Expert: Low-level search implementation. Finds the top <code>n</code>
84 * hits for <code>query</code>, applying <code>filter</code> if non-null.
85 *
86 * <p>Called by {@link Hits}.
87 *
88 * <p>Applications should usually call {@link Searcher#search(Query)} or
89 * {@link Searcher#search(Query,Filter)} instead.
90 * @throws BooleanQuery.TooManyClauses
91 */
92 TopDocs search(Weight weight, Filter filter, int n) throws IOException;
93
94 /** Expert: Returns the stored fields of document <code>i</code>.
95 * Called by {@link HitCollector} implementations.
96 * @see IndexReader#document(int)
97 * @throws CorruptIndexException if the index is corrupt
98 * @throws IOException if there is a low-level IO error
99 */
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) throws CorruptIndexException, IOException;
124
125 /** Expert: called to re-write queries into primitive queries.
126 * @throws BooleanQuery.TooManyClauses
127 */
128 Query rewrite(Query query) throws IOException;
129
130 /** Expert: low-level implementation method
131 * Returns an Explanation that describes how <code>doc</code> scored against
132 * <code>weight</code>.
133 *
134 * <p>This is intended to be used in developing Similarity implementations,
135 * and, for good performance, should not be displayed with every hit.
136 * Computing an explanation is as expensive as executing the query over the
137 * entire index.
138 * <p>Applications should call {@link Searcher#explain(Query, int)}.
139 * @throws BooleanQuery.TooManyClauses
140 */
141 Explanation explain(Weight weight, int doc) throws IOException;
142
143 /** Expert: Low-level search implementation with arbitrary sorting. Finds
144 * the top <code>n</code> hits for <code>query</code>, applying
145 * <code>filter</code> if non-null, and sorting the hits by the criteria in
146 * <code>sort</code>.
147 *
148 * <p>Applications should usually call {@link
149 * Searcher#search(Query,Filter,Sort)} instead.
150 * @throws BooleanQuery.TooManyClauses
151 */
152 TopFieldDocs search(Weight weight, Filter filter, int n, Sort sort)
153 throws IOException;
154
155 }
Save This Page