TermDocs.java
01 package gate.creole.annic.apache.lucene.index;
02 
03 /**
04  * Copyright 2004 The Apache Software Foundation
05  *
06  * Licensed under the Apache License, Version 2.0 (the "License");
07  * you may not use this file except in compliance with the License.
08  * You may obtain a copy of the License at
09  *
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;
20 
21 /** TermDocs provides an interface for enumerating <document, frequency>
22  pairs for a term.  <p> The document portion names each document containing
23  the term.  Documents are indicated by number.  The frequency portion gives
24  the number of times the term occurred in each document.  <p> The pairs are
25  ordered by document number.
26 
27  @see IndexReader#termDocs
28  */
29 
30 public interface TermDocs {
31   /** Sets this to the data for a term.
32    * The enumeration is reset to the start of the data for this term.
33    */
34   void seek(Term termthrows IOException;
35 
36   /** Sets this to the data for the current term in a {@link TermEnum}.
37    * This may be optimized in some implementations.
38    */
39   void seek(TermEnum termEnumthrows IOException;
40 
41   /** Returns the current document number.  <p> This is invalid until {@link
42    #next()} is called for the first time.*/
43   int doc();
44 
45   /** Returns the frequency of the term within the current document.  <p> This
46    is invalid until {@link #next()} is called for the first time.*/
47   int freq();
48 
49   /** Moves to the next pair in the enumeration.  <p> Returns true iff there is
50    such a next pair in the enumeration. */
51   boolean next() throws IOException;
52 
53   /** Attempts to read multiple entries from the enumeration, up to length of
54    <i>docs</i>.  Document numbers are stored in <i>docs</i>, and term
55    * frequencies are stored in <i>freqs</i>.  The <i>freqs</i> array must be as
56    * long as the <i>docs</i> array.
57    *
58    <p>Returns the number of entries read.  Zero is only returned when the
59    * stream has been exhausted.  */
60   int read(int[] docs, int[] freqsthrows IOException;
61 
62   /** Skips entries to the first beyond the current whose document number is
63    * greater than or equal to <i>target</i><p>Returns true iff there is such
64    * an entry.  <p>Behaves as if written: <pre>
65    *   boolean skipTo(int target) {
66    *     do {
67    *       if (!next())
68    *        return false;
69    *     } while (target > doc());
70    *     return true;
71    *   }
72    </pre>
73    * Some implementations are considerably more efficient than that.
74    */
75   boolean skipTo(int targetthrows IOException;
76 
77   /** Frees associated resources. */
78   void close() throws IOException;
79 }
80