/* 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.
 */

parcel Lucy;

/** Base class for searching collections of documents.
 *
 * Abstract base class for objects which search.  Core subclasses include
 * [](cfish:IndexSearcher) and
 * [](cfish:PolySearcher).
 */

public class Lucy::Search::Searcher inherits Clownfish::Obj {

    Schema      *schema;
    QueryParser *qparser;

    /** Abstract initializer.
     *
     * @param schema A Schema.
     */
    public inert Searcher*
    init(Searcher *self, Schema *schema);

    public void
    Destroy(Searcher *self);

    /** Return the maximum number of docs in the collection represented by the
     * Searcher, which is also the highest possible internal doc id.
     * Documents which have been marked as deleted but not yet purged are
     * included in this count.
     */
    public abstract int32_t
    Doc_Max(Searcher *self);

    /** Return the number of documents which contain the term in the given
     * field.
     *
     * @param field Field name.
     * @param term The term to look up.
     */
    public abstract uint32_t
    Doc_Freq(Searcher *self, String *field, Obj *term);

    /** If the supplied object is a Query, return it; if it's a query string,
     * create a QueryParser and parse it to produce a query against all
     * indexed fields.
     */
    public incremented Query*
    Glean_Query(Searcher *self, Obj *query = NULL);

    /** Return a Hits object containing the top results.
     *
     * @param query Either a Query object or a query string.
     * @param offset The number of most-relevant hits to discard, typically
     * used when "paging" through hits N at a time.  Setting
     * `offset` to 20 and `num_wanted` to 10 retrieves
     * hits 21-30, assuming that 30 hits can be found.
     * @param num_wanted The number of hits you would like to see after
     * `offset` is taken into account.
     * @param sort_spec A [](cfish:SortSpec), which will affect
     * how results are ranked and returned.
     */
    public incremented Hits*
    Hits(Searcher *self, Obj *query, uint32_t offset = 0,
         uint32_t num_wanted = 10, SortSpec *sort_spec = NULL);

    /** Iterate over hits, feeding them into a
     * [](cfish:Collector).
     *
     * @param query A Query.
     * @param collector A Collector.
     */
    public abstract void
    Collect(Searcher *self, Query *query, Collector *collector);

    /** Return a TopDocs object with up to num_wanted hits.
     */
    abstract incremented TopDocs*
    Top_Docs(Searcher *self, Query *query, uint32_t num_wanted,
             SortSpec *sort_spec = NULL);

    /** Retrieve a document.  Throws an error if the doc id is out of range.
     *
     * @param doc_id A document id.
     */
    public abstract incremented HitDoc*
    Fetch_Doc(Searcher *self, int32_t doc_id);

    /** Return the DocVector identified by the supplied doc id.  Throws an
     * error if the doc id is out of range.
     */
    abstract incremented DocVector*
    Fetch_Doc_Vec(Searcher *self, int32_t doc_id);

    /** Accessor for the object's `schema` member.
     */
    public Schema*
    Get_Schema(Searcher *self);

    /** Release external resources.
     */
    void
    Close(Searcher *self);
}