Lucene example source code file (TermPositions.java)

This example Lucene source code file (TermPositions.java) is included in the DevDaily.com "Java Source Code Warehouse" project. The intent of this project is to help you "Learn Java by Example" ^TM.

Java - Lucene tags/keywords

io, ioexception, ioexception, termdocs, termdocs, termpositions, termpositions

The Lucene TermPositions.java source code

package org.apache.lucene.index;

/**
 * Licensed to the Apache Software Foundation (ASF) under one or more
 * contributor license agreements.  See the NOTICE file distributed with
 * this work for additional information regarding copyright ownership.
 * The ASF licenses this file to You under the Apache License, Version 2.0
 * (the "License"); you may not use this file except in compliance with
 * the License.  You may obtain a copy of the License at
 *
 *     http://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
 */

import java.io.IOException;

/**
 * TermPositions provides an interface for enumerating the <document,
 * frequency, <position>* > tuples for a term.  <p> The document and
 * frequency are the same as for a TermDocs.  The positions portion lists the ordinal
 * positions of each occurrence of a term in a document.
 *
 * @see IndexReader#termPositions()
 */

public interface TermPositions
    extends TermDocs
{
    /** Returns next position in the current document.  It is an error to call
    this more than {@link #freq()} times
    without calling {@link #next()}<p> This is
    invalid until {@link #next()} is called for
    the first time.
    */
    int nextPosition() throws IOException;
    
    /** 
     * Returns the length of the payload at the current term position.
     * This is invalid until {@link #nextPosition()} is called for
     * the first time.<br>
     * @return length of the current payload in number of bytes
     */
    int getPayloadLength();
    
    /** 
     * Returns the payload data at the current term position.
     * This is invalid until {@link #nextPosition()} is called for
     * the first time.
     * This method must not be called more than once after each call
     * of {@link #nextPosition()}. However, 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.<br>
     * 
     * @param data the array into which the data of this payload is to be
     *             stored, if it is big enough; otherwise, a new byte[] array
     *             is allocated for this purpose. 
     * @param offset the offset in the array into which the data of this payload
     *               is to be stored.
     * @return a byte[] array containing the data of this payload
     * @throws IOException
     */
    byte[] getPayload(byte[] data, int offset) throws IOException;

  /**
   * Checks if a payload can be loaded at this position.
   * <p>
   * Payloads can only be loaded once per call to 
   * {@link #nextPosition()}.
   * 
   * @return true if there is a payload available at this position that can be loaded
   */
    public boolean isPayloadAvailable();

}