KickJava   Java API By Example, From Geeks To Geeks.

Java > Open Source Codes > org > apache > lucene > search > Searchable


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