01: package org.apache.lucene.index;
02:
03: /**
04: * Licensed to the Apache Software Foundation (ASF) under one or more
05: * contributor license agreements. See the NOTICE file distributed with
06: * this work for additional information regarding copyright ownership.
07: * The ASF licenses this file to You under the Apache License, Version 2.0
08: * (the "License"); you may not use this file except in compliance with
09: * 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: * 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.
27: *
28: * @see IndexReader#termPositions()
29: */
30:
31: public interface TermPositions extends TermDocs {
32: /** Returns next position in the current document. It is an error to call
33: this more than {@link #freq()} times
34: without calling {@link #next()}<p> This is
35: invalid until {@link #next()} is called for
36: the first time.
37: */
38: int nextPosition() throws IOException;
39:
40: /**
41: * Returns the length of the payload at the current term position.
42: * This is invalid until {@link #nextPosition()} is called for
43: * the first time.<br>
44: * @return length of the current payload in number of bytes
45: */
46: int getPayloadLength();
47:
48: /**
49: * Returns the payload data at the current term position.
50: * This is invalid until {@link #nextPosition()} is called for
51: * the first time.
52: * This method must not be called more than once after each call
53: * of {@link #nextPosition()}. However, payloads are loaded lazily,
54: * so if the payload data for the current position is not needed,
55: * this method may not be called at all for performance reasons.<br>
56: *
57: * @param data the array into which the data of this payload is to be
58: * stored, if it is big enough; otherwise, a new byte[] array
59: * is allocated for this purpose.
60: * @param offset the offset in the array into which the data of this payload
61: * is to be stored.
62: * @return a byte[] array containing the data of this payload
63: * @throws IOException
64: */
65: byte[] getPayload(byte[] data, int offset) throws IOException;
66:
67: /**
68: * Checks if a payload can be loaded at this position.
69: * <p>
70: * Payloads can only be loaded once per call to
71: * {@link #nextPosition()}.
72: *
73: * @return true if there is a payload available at this position that can be loaded
74: */
75: public boolean isPayloadAvailable();
76:
77: }
|