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 org.apache.lucene.document.Document;
import org.apache.lucene.document.FieldSelector;
import org.apache.lucene.index.IndexReader;
import org.apache.lucene.index.Term;
import org.apache.lucene.index.CorruptIndexException;

import java.io.IOException;       // for javadoc

/** The interface for search implementations.
 *
 * 
Searchable is the abstract network protocol for searching. 
 * Implementations provide search over a single index, over multiple
 * indices, and over indices on remote servers.
 *
 * 
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 non-zero scoring hit.
 */
public interface Searchable extends java.rmi.Remote {
  /** Lower-level search API.
   *
   * 
{@link HitCollector#collect(int,float)} is called for every non-zero
   * scoring document.
   * 
HitCollector-based access to remote indexes is discouraged.
   *
   * 
Applications should only use this if they need all of the
   * matching documents.  The high-level search API ({@link
   * Searcher#search(Query)}) is usually more efficient, as it skips
   * non-high-scoring hits.
   *
   * @param weight to match documents
   * @param filter if non-null, a bitset used to eliminate some documents
   * @param results to receive hits
   * @throws BooleanQuery.TooManyClauses
   */
  void search(Weight weight, Filter filter, HitCollector results)
  throws IOException;


  /** Frees resources associated with this Searcher.
   * Be careful not to call this method while you are still using objects
   * like {@link Hits}.
   */
  void close() throws IOException;

  /** Expert: Returns the number of documents containing term.
   * Called by search code to compute term weights.
   * @see IndexReader#docFreq(Term)
   */
  int docFreq(Term term) throws IOException;

  /** Expert: For each term in the terms array, calculates the number of
   * documents containing 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.
   * Called by search code to compute term weights.
   * @see IndexReader#maxDoc()
   */
  int maxDoc() throws IOException;

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

  /** Expert: Returns the stored fields of document i.
   * Called by {@link HitCollector} implementations.
   * @see 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 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.
   * 
   * 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 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 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 doc scored against
   * weight.
   *
   * 
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.
   * 
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 n hits for query, applying
   * filter if non-null, and sorting the hits by the criteria in
   * sort.
   *
   * 
Applications should usually call {@link
   * Searcher#search(Query,Filter,Sort)} instead.
   * @throws BooleanQuery.TooManyClauses
   */
  TopFieldDocs search(Weight weight, Filter filter, int n, Sort sort)
  throws IOException;

}