Save This Page
Home » lucene-3.0.1-src » org.apache » lucene » search » spans » [javadoc | source]
    1   package org.apache.lucene.search.spans;
    2   
    3   /**
    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
   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   import java.util.Collection;
   22   
   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;
   30   
   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) {
   35      *     do {
   36      *       if (!next())
   37      * 	     return false;
   38      *     } while (target > doc());
   39      *     return true;
   40      *   }
   41      * </pre>
   42      * Most implementations are considerably more efficient than that.
   43      */
   44     public abstract boolean skipTo(int target) throws IOException;
   45   
   46     /** Returns the document number of the current match.  Initially invalid. */
   47     public abstract int doc();
   48   
   49     /** Returns the start position of the current match.  Initially invalid. */
   50     public abstract int start();
   51   
   52     /** Returns the end position of the current match.  Initially invalid. */
   53     public abstract int end();
   54     
   55     /**
   56      * Returns the payload data for the current span.
   57      * This is invalid until {@link #next()} is called for
   58      * the first time.
   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>
   66      * <br>
   67       * Note that the return type is a collection, thus the ordering should not be relied upon.
   68       * <br/>
   69      * <p><font color="#FF0000">
   70      * WARNING: The status of the <b>Payloads</b> feature is experimental.
   71      * The APIs introduced here might change in the future and will not be
   72      * supported anymore in such a case.</font>
   73      *
   74      * @return a List of byte arrays containing the data of this payload, otherwise null if isPayloadAvailable is false
   75      * @throws java.io.IOException
   76       */
   77     // TODO: Remove warning after API has been finalized
   78     public abstract Collection<byte[]> getPayload() throws IOException;
   79   
   80     /**
   81      * Checks if a payload can be loaded at this position.
   82      * <p/>
   83      * Payloads can only be loaded once per call to
   84      * {@link #next()}.
   85      *
   86      * @return true if there is a payload available at this position that can be loaded
   87      */
   88     public abstract boolean isPayloadAvailable();
   89   
   90   }

Save This Page
Home » lucene-3.0.1-src » org.apache » lucene » search » spans » [javadoc | source]