LuceneService (Apache Geode 1.8.0)
Date: 2018-11-29

org.apache.geode.cache.lucene

## Interface LuceneService

-     public interface LuceneService

  The LuceneService provides the capability to create Lucene indexes and execute lucene queries on data stored in Geode regions. The Lucene indexes are automatically maintained by Geode whenever entries are updated in the associated regions.

  To obtain an instance of LuceneService, use `LuceneServiceProvider.get(GemFireCache cache)`.

  Lucene indexes can be created using gfsh, xml, or the java API. Below is an example of creating a Lucene index with the java API. The Lucene index should be created on each member that has the region that is being indexed.

       {
         @code
             luceneService.createIndexFactory()
              .addField("name")
              .addField("zipcode")
              .addField("email", new KeywordAnalyzer())
              .create(indexName, regionName);
       }

  You can also specify what `Analyzer` to use for each field. In the example above, email is being tokenized with the KeywordAnalyzer so it is treated as a single word. The default analyzer if none is specified is the `StandardAnalyzer`.

  Indexes should be created on all peers that host the region being indexed. Clients do not need to define the index, they can directly execute queries using this service.

  Queries on this service can return either the region keys, values, or both that match a Lucene query expression. To execute a query, start with the `createLuceneQueryFactory()` method.

       {
         @code
         LuceneQuery query = luceneService.createLuceneQueryFactory().setLimit(200).create(indexName,
             regionName, "name:John AND zipcode:97006", defaultField);
         Collection results = query.findValues();
       }

  The Lucene index data is colocated with the region that is indexed. This means that the index data will be partitioned, copied, or persisted using the same configuration options you provide for the region that is indexed. Queries will automatically be distributed in parallel to cover all partitions of a partitioned region.

  Indexes are maintained asynchronously, so changes to regions may not be immediately reflected in the index. This means that queries executed using this service may return stale results. Use the `waitUntilFlushed(String, String, long, TimeUnit)` method if you need to wait for your changes to be indexed before executing a query, however this method should be used sparingly because it is an expensive operation.

  Currently, only partitioned regions are supported. Creating an index on a region with `DataPolicy.REPLICATE` will fail.

- - ### Field Summary

    Fields
    Modifier and Type | Field and Description
    --- | ---
    `static java.lang.String` | `REGION_VALUE_FIELD` A special field name that indicates that the entire region value should be indexed.

  - ### Method Summary

    All Methods Instance Methods Abstract Methods
    Modifier and Type | Method and Description
    --- | ---
    `LuceneIndexFactory` | `createIndexFactory()` Get a factory for creating a Lucene index on this member.
    `LuceneQueryFactory` | `createLuceneQueryFactory()` Create a factory for building a Lucene query.
    `void` | `destroyIndex(java.lang.String indexName, java.lang.String regionPath)` Destroy the Lucene index
    `void` | `destroyIndexes(java.lang.String regionPath)` Destroy all the Lucene indexes for the region
    `java.util.Collection<LuceneIndex>` | `getAllIndexes()` get all the Lucene indexes.
    `Cache` | `getCache()` returns the cache to which the LuceneService belongs
    `LuceneIndex` | `getIndex(java.lang.String indexName, java.lang.String regionPath)` Get the Lucene index object specified by region name and index name
    `boolean` | `isIndexingInProgress(java.lang.String indexName, java.lang.String regionPath)` Returns if the indexing process is in progress Before executing a lucene query, it can be checked if the indexing operation is in progress.
    `boolean` | `waitUntilFlushed(java.lang.String indexName, java.lang.String regionPath, long timeout, java.util.concurrent.TimeUnit unit)` Wait until the current entries in cache are indexed.

- - ### Field Detail

    - #### REGION_VALUE_FIELD

          static final java.lang.String REGION_VALUE_FIELD

      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.
      See Also:
        Constant Field Values

  - ### Method Detail

    - #### createIndexFactory

          LuceneIndexFactory createIndexFactory()

      Get a factory for creating a Lucene index on this member.

    - #### destroyIndex

          void destroyIndex(java.lang.String indexName,
                            java.lang.String regionPath)

      Destroy the Lucene index
      Parameters:
        `indexName` - the name of the index to destroy
        `regionPath` - the path of the region whose index to destroy

    - #### destroyIndexes

          void destroyIndexes(java.lang.String regionPath)

      Destroy all the Lucene indexes for the region
      Parameters:
        `regionPath` - The path of the region on which to destroy the indexes

    - #### getIndex

          LuceneIndex getIndex(java.lang.String indexName,
                               java.lang.String regionPath)

      Get the Lucene index object specified by region name and index name
      Parameters:
        `indexName` - index name
        `regionPath` - region name
      Returns:
        LuceneIndex object

    - #### getAllIndexes

          java.util.Collection<LuceneIndex> getAllIndexes()

      get all the Lucene indexes.
      Returns:
        all index objects in a Collection

    - #### createLuceneQueryFactory

          LuceneQueryFactory createLuceneQueryFactory()

      Create a factory for building a Lucene query.

    - #### getCache

          Cache getCache()

      returns the cache to which the LuceneService belongs

    - #### waitUntilFlushed

          boolean waitUntilFlushed(java.lang.String indexName,
                                   java.lang.String regionPath,
                                   long timeout,
                                   java.util.concurrent.TimeUnit unit)
                            throws java.lang.InterruptedException

      Wait until the current entries in cache are indexed. Lucene indexes are maintained asynchronously. This means that updates to the region will not be immediately reflected in the Lucene index. This method will either timeout or wait until any data put into the region before this method call is flushed to the lucene index. This method is an expensive operation, so using it before every query is highly discouraged.
      Parameters:
        `indexName` - index name
        `regionPath` - region name
        `timeout` - max wait time
        `unit` - Time unit associated with the max wait time
      Returns:
        true if entries are flushed within timeout, false if the timeout has elapsed
      Throws:
        `java.lang.InterruptedException`

    - #### isIndexingInProgress

          boolean isIndexingInProgress(java.lang.String indexName,
                                       java.lang.String regionPath)

      Returns if the indexing process is in progress Before executing a lucene query, it can be checked if the indexing operation is in progress. Queries executed during the indexing process will get a `LuceneIndexCreationInProgressException`
      Parameters:
        `indexName` - index name
        `regionPath` - region name
      Returns:
        true if the indexing operation is in progress otherwise false.