Class Spans

java.lang.Object
org.apache.lucene.search.spans.Spans
Direct Known Subclasses:
NearSpansOrdered, NearSpansUnordered, SpanPositionCheckQuery.PositionCheckSpan, TermSpans

public abstract class Spans extends Object
Expert: an enumeration of span matches. Used to implement span searching. Each span represents a range of term positions within a document. Matches are enumerated in order, by increasing document number, within that by increasing start position and finally by increasing end position.
  • Constructor Summary

    Constructors
    Constructor
    Description
     
  • Method Summary

    Modifier and Type
    Method
    Description
    abstract long
    Returns the estimated cost of this spans.
    abstract int
    doc()
    Returns the document number of the current match.
    abstract int
    end()
    Returns the end position of the current match.
    abstract Collection<byte[]>
    Returns the payload data for the current span.
    abstract boolean
    Checks if a payload can be loaded at this position.
    abstract boolean
    Move to the next match, returning true iff any such exists.
    abstract boolean
    skipTo(int target)
    Skips to the first match beyond the current, whose document number is greater than or equal to target.
    abstract int
    Returns the start position of the current match.

    Methods inherited from class java.lang.Object

    clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
  • Constructor Details

    • Spans

      public Spans()
  • Method Details

    • next

      public abstract boolean next() throws IOException
      Move to the next match, returning true iff any such exists.
      Throws:
      IOException
    • skipTo

      public abstract boolean skipTo(int target) throws IOException
      Skips to the first match beyond the current, whose document number is greater than or equal to target.

      The behavior of this method is undefined when called with target ≤ current, or after the iterator has exhausted. Both cases may result in unpredicted behavior.

      Returns true iff there is such a match.

      Behaves as if written:

         boolean skipTo(int target) {
           do {
             if (!next())
               return false;
           } while (target > doc());
           return true;
         }
       
      Most implementations are considerably more efficient than that.
      Throws:
      IOException
    • doc

      public abstract int doc()
      Returns the document number of the current match. Initially invalid.
    • start

      public abstract int start()
      Returns the start position of the current match. Initially invalid.
    • end

      public abstract int end()
      Returns the end position of the current match. Initially invalid.
    • getPayload

      public abstract Collection<byte[]> getPayload() throws IOException
      Returns the payload data for the current span. This is invalid until next() is called for the first time. This method must not be called more than once after each call of next(). However, most payloads are loaded lazily, so if the payload data for the current position is not needed, this method may not be called at all for performance reasons. An ordered SpanQuery does not lazy load, so if you have payloads in your index and you do not want ordered SpanNearQuerys to collect payloads, you can disable collection with a constructor option.

      Note that the return type is a collection, thus the ordering should not be relied upon.
      Returns:
      a List of byte arrays containing the data of this payload, otherwise null if isPayloadAvailable is false
      Throws:
      IOException - if there is a low-level I/O error
    • isPayloadAvailable

      public abstract boolean isPayloadAvailable() throws IOException
      Checks if a payload can be loaded at this position.

      Payloads can only be loaded once per call to next().

      Returns:
      true if there is a payload available at this position that can be loaded
      Throws:
      IOException
    • cost

      public abstract long cost()
      Returns the estimated cost of this spans.

      This is generally an upper bound of the number of documents this iterator might match, but may be a rough heuristic, hardcoded value, or otherwise completely inaccurate.