lucene-java-3.5.0/lucene/src/java/org/apache/lucene/index/TermDocs.java

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