lucene-java-3.4.0/lucene/src/java/org/apache/lucene/search/DocIdSetIterator.java

   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 java.io.IOException;
  21
  22 /**
  23  * This abstract class defines methods to iterate over a set of non-decreasing
  24  * doc ids. Note that this class assumes it iterates on doc Ids, and therefore
  25  * {@link #NO_MORE_DOCS} is set to {@value #NO_MORE_DOCS} in order to be used as
  26  * a sentinel object. Implementations of this class are expected to consider
  27  * {@link Integer#MAX_VALUE} as an invalid value.
  28  */
  29 public abstract class DocIdSetIterator {
  30
  31   /**
  32    * When returned by {@link #nextDoc()}, {@link #advance(int)} and
  33    * {@link #docID()} it means there are no more docs in the iterator.
  34    */
  35   public static final int NO_MORE_DOCS = Integer.MAX_VALUE;
  36
  37   /**
  38    * Returns the following:
  39    * <ul>
  40    * <li>-1 or {@link #NO_MORE_DOCS} if {@link #nextDoc()} or
  41    * {@link #advance(int)} were not called yet.
  42    * <li>{@link #NO_MORE_DOCS} if the iterator has exhausted.
  43    * <li>Otherwise it should return the doc ID it is currently on.
  44    * </ul>
  45    * <p>
  46    *
  47    * @since 2.9
  48    */
  49   public abstract int docID();
  50
  51   /**
  52    * Advances to the next document in the set and returns the doc it is
  53    * currently on, or {@link #NO_MORE_DOCS} if there are no more docs in the
  54    * set.<br>
  55    *
  56    * <b>NOTE:</b> after the iterator has exhausted you should not call this
  57    * method, as it may result in unpredicted behavior.
  58    *
  59    * @since 2.9
  60    */
  61   public abstract int nextDoc() throws IOException;
  62
  63   /**
  64    * Advances to the first beyond (see NOTE below) the current whose document
  65    * number is greater than or equal to <i>target</i>. Returns the current
  66    * document number or {@link #NO_MORE_DOCS} if there are no more docs in the
  67    * set.
  68    * <p>
  69    * Behaves as if written:
  70    *
  71    * <pre>
  72    * int advance(int target) {
  73    *   int doc;
  74    *   while ((doc = nextDoc()) &lt; target) {
  75    *   }
  76    *   return doc;
  77    * }
  78    * </pre>
  79    *
  80    * Some implementations are considerably more efficient than that.
  81    * <p>
  82    * <b>NOTE:</b> when <code> target &le; current</code> implementations may opt
  83    * not to advance beyond their current {@link #docID()}.
  84    * <p>
  85    * <b>NOTE:</b> this method may be called with {@link #NO_MORE_DOCS} for
  86    * efficiency by some Scorers. If your implementation cannot efficiently
  87    * determine that it should exhaust, it is recommended that you check for that
  88    * value in each call to this method.
  89    * <p>
  90    * <b>NOTE:</b> after the iterator has exhausted you should not call this
  91    * method, as it may result in unpredicted behavior.
  92    * <p>
  93    *
  94    * @since 2.9
  95    */
  96   public abstract int advance(int target) throws IOException;
  97
  98 }