lucene-java-3.4.0/lucene/src/java/org/apache/lucene/search/spans/Spans.java

   1 package org.apache.lucene.search.spans;
   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.util.Collection;
  22
  23 /** Expert: an enumeration of span matches.  Used to implement span searching.
  24  * Each span represents a range of term positions within a document.  Matches
  25  * are enumerated in order, by increasing document number, within that by
  26  * increasing start position and finally by increasing end position. */
  27 public abstract class Spans {
  28   /** Move to the next match, returning true iff any such exists. */
  29   public abstract boolean next() throws IOException;
  30
  31   /** Skips to the first match beyond the current, whose document number is
  32    * greater than or equal to <i>target</i>. <p>Returns true iff there is such
  33    * a match.  <p>Behaves as if written: <pre>
  34    *   boolean skipTo(int target) {
  35    *     do {
  36    *       if (!next())
  37    *         return false;
  38    *     } while (target > doc());
  39    *     return true;
  40    *   }
  41    * </pre>
  42    * Most implementations are considerably more efficient than that.
  43    */
  44   public abstract boolean skipTo(int target) throws IOException;
  45
  46   /** Returns the document number of the current match.  Initially invalid. */
  47   public abstract int doc();
  48
  49   /** Returns the start position of the current match.  Initially invalid. */
  50   public abstract int start();
  51
  52   /** Returns the end position of the current match.  Initially invalid. */
  53   public abstract int end();
  54
  55   /**
  56    * Returns the payload data for the current span.
  57    * This is invalid until {@link #next()} is called for
  58    * the first time.
  59    * This method must not be called more than once after each call
  60    * of {@link #next()}. However, most payloads are loaded lazily,
  61    * so if the payload data for the current position is not needed,
  62    * this method may not be called at all for performance reasons. An ordered
  63    * SpanQuery does not lazy load, so if you have payloads in your index and
  64    * you do not want ordered SpanNearQuerys to collect payloads, you can
  65    * disable collection with a constructor option.<br>
  66    * <br>
  67     * Note that the return type is a collection, thus the ordering should not be relied upon.
  68     * <br/>
  69    * @lucene.experimental
  70    *
  71    * @return a List of byte arrays containing the data of this payload, otherwise null if isPayloadAvailable is false
  72    * @throws java.io.IOException
  73     */
  74   // TODO: Remove warning after API has been finalized
  75   public abstract Collection<byte[]> getPayload() throws IOException;
  76
  77   /**
  78    * Checks if a payload can be loaded at this position.
  79    * <p/>
  80    * Payloads can only be loaded once per call to
  81    * {@link #next()}.
  82    *
  83    * @return true if there is a payload available at this position that can be loaded
  84    */
  85   public abstract boolean isPayloadAvailable();
  86
  87 }