Lucene example source code file (Searchable.java)

This example Lucene source code file (Searchable.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

closeable, corruptindexexception, corruptindexexception, deprecated, document, document, explanation, fieldselector, filter, filter, io, ioexception, ioexception, searchable, topdocs

The Lucene Searchable.java source code

package org.apache.lucene.search;

/**
 * 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;
import java.io.Closeable;

import org.apache.lucene.document.Document;
import org.apache.lucene.document.FieldSelector;
import org.apache.lucene.index.CorruptIndexException;
import org.apache.lucene.index.Term;

/**
 * The interface for search implementations.
 * 
 * <p>
 * Searchable is the abstract network protocol for searching. Implementations
 * provide search over a single index, over multiple indices, and over indices
 * on remote servers.
 * 
 * <p>
 * Queries, filters and sort criteria are designed to be compact so that they
 * may be efficiently passed to a remote index, with only the top-scoring hits
 * being returned, rather than every matching hit.
 * 
 * <b>NOTE: this interface is kept public for convenience. Since it is not
 * expected to be implemented directly, it may be changed unexpectedly between
 * releases.
 *
 * @deprecated In 4.0 this interface is removed/absorbed
 * into IndexSearcher
 */
@Deprecated
public interface Searchable extends Closeable {
  
  /**
   * Lower-level search API.
   * 
   * <p>
   * {@link Collector#collect(int)} is called for every document. <br>
   * Collector-based access to remote indexes is discouraged.
   * 
   * <p>
   * Applications should only use this if they need <i>all of the matching
   * documents. The high-level search API ({@link Searcher#search(Query,int)}) is
   * usually more efficient, as it skips non-high-scoring hits.
   * 
   * @param weight
   *          to match documents
   * @param filter
   *          if non-null, used to permit documents to be collected.
   * @param collector
   *          to receive hits
   * @throws BooleanQuery.TooManyClauses
   */
  void search(Weight weight, Filter filter, Collector collector) throws IOException;

  /** Frees resources associated with this Searcher.
   * Be careful not to call this method while you are still using objects
   * that reference this Searchable.
   */
  void close() throws IOException;

  /** Expert: Returns the number of documents containing <code>term.
   * 
   * @see org.apache.lucene.index.IndexReader#docFreq(Term)
   */
  int docFreq(Term term) throws IOException;

  /** Expert: For each term in the terms array, calculates the number of
   * documents containing <code>term. Returns an array with these
   * document frequencies. Used to minimize number of remote calls.
   */
  int[] docFreqs(Term[] terms) throws IOException;

  /** Expert: Returns one greater than the largest possible document number.
   * 
   * @see org.apache.lucene.index.IndexReader#maxDoc()
   */
  int maxDoc() throws IOException;

  /** Expert: Low-level search implementation.  Finds the top <code>n
   * hits for <code>query, applying filter if non-null.
   *
   * <p>Applications should usually call {@link Searcher#search(Query,int)} or
   * {@link Searcher#search(Query,Filter,int)} instead.
   * @throws BooleanQuery.TooManyClauses
   */
  TopDocs search(Weight weight, Filter filter, int n) throws IOException;

  /**
   * Returns the stored fields of document <code>i.
   * 
   * @see org.apache.lucene.index.IndexReader#document(int)
   * @throws CorruptIndexException if the index is corrupt
   * @throws IOException if there is a low-level IO error
   */
  Document doc(int i) throws CorruptIndexException, IOException;

  /**
   * Get the {@link org.apache.lucene.document.Document} at the <code>nth position. The {@link org.apache.lucene.document.FieldSelector}
   * may be used to determine what {@link org.apache.lucene.document.Field}s to load and how they should be loaded.
   * 
   * <b>NOTE: If the underlying Reader (more specifically, the underlying FieldsReader) is closed before the lazy {@link org.apache.lucene.document.Field} is
   * loaded an exception may be thrown.  If you want the value of a lazy {@link org.apache.lucene.document.Field} to be available after closing you must
   * explicitly load it or fetch the Document again with a new loader.
   * 
   *  
   * @param n Get the document at the <code>nth position
   * @param fieldSelector The {@link org.apache.lucene.document.FieldSelector} to use to determine what Fields should be loaded on the Document.  May be null, in which case all Fields will be loaded.
   * @return The stored fields of the {@link org.apache.lucene.document.Document} at the nth position
   * @throws CorruptIndexException if the index is corrupt
   * @throws IOException if there is a low-level IO error
   * 
   * @see org.apache.lucene.index.IndexReader#document(int, FieldSelector)
   * @see org.apache.lucene.document.Fieldable
   * @see org.apache.lucene.document.FieldSelector
   * @see org.apache.lucene.document.SetBasedFieldSelector
   * @see org.apache.lucene.document.LoadFirstFieldSelector
   */
  Document doc(int n, FieldSelector fieldSelector) throws CorruptIndexException, IOException;
  
  /** Expert: called to re-write queries into primitive queries.
   * @throws BooleanQuery.TooManyClauses
   */
  Query rewrite(Query query) throws IOException;

  /** Expert: low-level implementation method
   * Returns an Explanation that describes how <code>doc scored against
   * <code>weight.
   *
   * <p>This is intended to be used in developing Similarity implementations,
   * and, for good performance, should not be displayed with every hit.
   * Computing an explanation is as expensive as executing the query over the
   * entire index.
   * <p>Applications should call {@link Searcher#explain(Query, int)}.
   * @throws BooleanQuery.TooManyClauses
   */
  Explanation explain(Weight weight, int doc) throws IOException;

  /** Expert: Low-level search implementation with arbitrary sorting.  Finds
   * the top <code>n hits for query, applying
   * <code>filter if non-null, and sorting the hits by the criteria in
   * <code>sort.
   *
   * <p>Applications should usually call {@link
   * Searcher#search(Query,Filter,int,Sort)} instead.
   * 
   * @throws BooleanQuery.TooManyClauses
   */
  TopFieldDocs search(Weight weight, Filter filter, int n, Sort sort)
  throws IOException;

}