1 package org.apache.lucene.search.spans;
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
11 * http://www.apache.org/licenses/LICENSE-2.0
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.
20 import java.io.IOException;
21 import java.util.Collection;
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;
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) {
38 * } while (target > doc());
42 * Most implementations are considerably more efficient than that.
44 public abstract boolean skipTo(int target) throws IOException;
46 /** Returns the document number of the current match. Initially invalid. */
47 public abstract int doc();
49 /** Returns the start position of the current match. Initially invalid. */
50 public abstract int start();
52 /** Returns the end position of the current match. Initially invalid. */
53 public abstract int end();
56 * Returns the payload data for the current span.
57 * This is invalid until {@link #next()} is called for
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>
67 * Note that the return type is a collection, thus the ordering should not be relied upon.
69 * @lucene.experimental
71 * @return a List of byte arrays containing the data of this payload, otherwise null if isPayloadAvailable is false
72 * @throws java.io.IOException
74 // TODO: Remove warning after API has been finalized
75 public abstract Collection<byte[]> getPayload() throws IOException;
78 * Checks if a payload can be loaded at this position.
80 * Payloads can only be loaded once per call to
83 * @return true if there is a payload available at this position that can be loaded
85 public abstract boolean isPayloadAvailable();