/*
 * 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.
 */
package org.apache.geode.cache.lucene;

import java.util.Collection;
import java.util.Map;

import org.apache.lucene.analysis.Analyzer;

import org.apache.geode.annotations.Experimental;
import org.apache.geode.cache.GemFireCache;
import org.apache.geode.cache.lucene.internal.LuceneIndexCreationProfile;

/**
 * LuceneService instance is a singleton for each cache.
 * 
 * It provides handle for managing the {@link LuceneIndex} and create the {@link LuceneQuery} via
 * {@link LuceneQueryFactory}
 * 
 * </p>
 * Example: <br>
 * 
 * <pre>
 * At client and server JVM, initializing cache will create the LuceneServiceImpl object, 
 * which is a singleton at each JVM. 
 * 
 * At each server JVM, for data region to create index, create the index on fields with default analyzer:
 * LuceneIndex index = luceneService.createIndex(indexName, regionName, "field1", "field2", "field3"); 
 * or create index on fields with specified analyzer:
 * LuceneIndex index = luceneService.createIndex(indexName, regionName, analyzerPerField);
 * 
 * We can also create index via cache.xml or gfsh.
 * 
 * At client side, create query and run the search:
 * 
 * LuceneQuery query = luceneService.createLuceneQueryFactory().setLimit(200).setPageSize(20)
 * .setResultTypes(SCORE, VALUE, KEY).setFieldProjection("field1", "field2")
 * .create(indexName, regionName, querystring, analyzer);
 * 
 * The querystring is using lucene's queryparser syntax, such as "field1:zhou* AND field2:gzhou@pivotal.io"
 *  
 * PageableLuceneQueryResults results = query.search();
 * 
 * If pagination is not specified:
 * List list = results.getNextPage(); // return all results in one getNextPage() call
 * or if paging is specified:
 * if (results.hasNextPage()) {
 *   List page = results.nextPage(); // return resules page by page
 * }
 * 
 * The item of the list is either the domain object or instance of {@link LuceneResultStruct}
 * </pre>
 * 
 *
 */
@Experimental
public interface LuceneService {

  /**
   * A special field name that indicates that the entire region value should be indexed. This will
   * only work if the region value is a String or Number, in which case a lucene document will be
   * created with a single field with this name.
   */
  String REGION_VALUE_FIELD = "__REGION_VALUE_FIELD";

  /**
   * Create a lucene index using default analyzer.
   * 
   * @param fields The fields of the object to index. Only fields listed here will be stored in the
   *        index. Fields should map to PDX fieldNames if the object is serialized with PDX, or to
   *        java fields on the object otherwise. The special field name
   *        {{@link #REGION_VALUE_FIELD}} indicates that the entire value should be stored as a
   *        single field in the index.
   */
  public void createIndex(String indexName, String regionPath, String... fields);

  /**
   * Create a lucene index using specified analyzer per field
   * 
   * @param indexName index name
   * @param regionPath region name
   * @param analyzerPerField A map of fields to analyzers. See
   *        {{@link #createIndex(String, String, String...)}} for details on valid values for
   *        fields. Each field will be tokenized using the provided Analyzer.
   */
  public void createIndex(String indexName, String regionPath,
      Map<String, Analyzer> analyzerPerField);

  /**
   * Destroy the lucene index
   * 
   * @param index index object
   * @deprecated TODO This feature is not yet implemented
   */
  @Deprecated
  public void destroyIndex(LuceneIndex index);

  /**
   * Get the lucene index object specified by region name and index name
   * 
   * @param indexName index name
   * @param regionPath region name
   * @return LuceneIndex object
   */
  public LuceneIndex getIndex(String indexName, String regionPath);

  /**
   * get all the lucene indexes.
   * 
   * @return all index objects in a Collection
   */
  public Collection<LuceneIndex> getAllIndexes();

  /**
   * create LuceneQueryFactory
   * 
   * @return LuceneQueryFactory object
   */
  public LuceneQueryFactory createLuceneQueryFactory();

}