1 package org.apache.lucene.index;
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;
23 * TermPositions provides an interface for enumerating the <document,
24 * frequency, <position>* > tuples for a term. <p> The document and
25 * frequency are the same as for a TermDocs. The positions portion lists the ordinal
26 * positions of each occurrence of a term in a document.
28 * @see IndexReader#termPositions()
31 public interface TermPositions
34 /** Returns next position in the current document. It is an error to call
35 this more than {@link #freq()} times
36 without calling {@link #next()}<p> This is
37 invalid until {@link #next()} is called for
40 int nextPosition() throws IOException;
43 * Returns the length of the payload at the current term position.
44 * This is invalid until {@link #nextPosition()} is called for
46 * @return length of the current payload in number of bytes
48 int getPayloadLength();
51 * Returns the payload data at the current term position.
52 * This is invalid until {@link #nextPosition()} is called for
54 * This method must not be called more than once after each call
55 * of {@link #nextPosition()}. However, payloads are loaded lazily,
56 * so if the payload data for the current position is not needed,
57 * this method may not be called at all for performance reasons.<br>
59 * @param data the array into which the data of this payload is to be
60 * stored, if it is big enough; otherwise, a new byte[] array
61 * is allocated for this purpose.
62 * @param offset the offset in the array into which the data of this payload
64 * @return a byte[] array containing the data of this payload
67 byte[] getPayload(byte[] data, int offset) throws IOException;
70 * Checks if a payload can be loaded at this position.
72 * Payloads can only be loaded once per call to
73 * {@link #nextPosition()}.
75 * @return true if there is a payload available at this position that can be loaded
77 public boolean isPayloadAvailable();