package io.ebean;

import io.ebeanservice.docstore.api.DocQueryRequest;
import io.ebeanservice.docstore.api.RawDoc;
import javax.annotation.Nullable;

import java.io.IOException;
import java.util.List;
import java.util.Map;
import java.util.function.Consumer;
import java.util.function.Predicate;

Document storage operations.
/**
 * Document storage operations.
 */
public interface DocumentStore {

  
Update the associated document store using the result of the query.

This will execute the query against the database creating a document for each
bean graph and sending this to the document store.


Note that the select and fetch paths of the query is set for you to match the
document structure needed based on @DocStore and @DocStoreEmbedded
so what this query requires is the predicates only.


This query will be executed using findEach so it is safe to use a query
that will fetch a lot of beans. The default bulkBatchSize is used.

Params:
query – The query that selects object to send to the document store./**
   * Update the associated document store using the result of the query.
   * <p>
   * This will execute the query against the database creating a document for each
   * bean graph and sending this to the document store.
   * </p>
   * <p>
   * Note that the select and fetch paths of the query is set for you to match the
   * document structure needed based on <code>@DocStore</code> and <code>@DocStoreEmbedded</code>
   * so what this query requires is the predicates only.
   * </p>
   * <p>
   * This query will be executed using findEach so it is safe to use a query
   * that will fetch a lot of beans. The default bulkBatchSize is used.
   * </p>
   *
   * @param query The query that selects object to send to the document store.
   */
  <T> void indexByQuery(Query<T> query);

  
Update the associated document store index using the result of the query additionally specifying a
bulkBatchSize to use for sending the messages to ElasticSearch.
Params:
query –         The query that selects object to send to the document store.
bulkBatchSize – The batch size to use when bulk sending to the document store./**
   * Update the associated document store index using the result of the query additionally specifying a
   * bulkBatchSize to use for sending the messages to ElasticSearch.
   *
   * @param query         The query that selects object to send to the document store.
   * @param bulkBatchSize The batch size to use when bulk sending to the document store.
   */
  <T> void indexByQuery(Query<T> query, int bulkBatchSize);

  
Update the document store for all beans of this type.

This is the same as indexByQuery where the query has no predicates and so fetches all rows.

/**
   * Update the document store for all beans of this type.
   * <p>
   * This is the same as indexByQuery where the query has no predicates and so fetches all rows.
   * </p>
   */
  void indexAll(Class<?> beanType);

  
Return the bean by fetching it's content from the document store.
If the document is not found null is returned.

Typically this is called indirectly by findOne() on the query.


Customer customer =
  server.find(Customer.class)
    .setUseDocStore(true)
    .setId(42)
    .findOne();

/**
   * Return the bean by fetching it's content from the document store.
   * If the document is not found null is returned.
   * <p>
   * Typically this is called indirectly by findOne() on the query.
   * </p>
   * <pre>{@code
   *
   * Customer customer =
   *   server.find(Customer.class)
   *     .setUseDocStore(true)
   *     .setId(42)
   *     .findOne();
   *
   * }</pre>
   */
  @Nullable
  <T> T find(DocQueryRequest<T> request);

  
Execute the find list query. This request is prepared to execute secondary queries.

Typically this is called indirectly by findList() on the query that has setUseDocStore(true).


List<Customer> newCustomers =
 server.find(Customer.class)
   .setUseDocStore(true)
   .where().eq("status, Customer.Status.NEW)
   .findList();

/**
   * Execute the find list query. This request is prepared to execute secondary queries.
   * <p>
   * Typically this is called indirectly by findList() on the query that has setUseDocStore(true).
   * </p>
   * <pre>{@code
   *
   * List<Customer> newCustomers =
   *  server.find(Customer.class)
   *    .setUseDocStore(true)
   *    .where().eq("status, Customer.Status.NEW)
   *    .findList();
   *
   * }</pre>
   */
  <T> List<T> findList(DocQueryRequest<T> request);

  
Execute the query against the document store returning the paged list.

The query should have firstRow or maxRows set prior to calling this method.


Typically this is called indirectly by findPagedList() on the query that has setUseDocStore(true).


PagedList<Customer> newCustomers =
 server.find(Customer.class)
   .setUseDocStore(true)
   .where().eq("status, Customer.Status.NEW)
   .setMaxRows(50)
   .findPagedList();

/**
   * Execute the query against the document store returning the paged list.
   * <p>
   * The query should have <code>firstRow</code> or <code>maxRows</code> set prior to calling this method.
   * </p>
   * <p>
   * Typically this is called indirectly by findPagedList() on the query that has setUseDocStore(true).
   * </p>
   * <pre>{@code
   *
   * PagedList<Customer> newCustomers =
   *  server.find(Customer.class)
   *    .setUseDocStore(true)
   *    .where().eq("status, Customer.Status.NEW)
   *    .setMaxRows(50)
   *    .findPagedList();
   *
   * }</pre>
   */
  <T> PagedList<T> findPagedList(DocQueryRequest<T> request);

  
Execute the query against the document store with the expectation of a large set of results
that are processed in a scrolling resultSet fashion.

For example, with the ElasticSearch doc store this uses SCROLL.


Typically this is called indirectly by findEach() on the query that has setUseDocStore(true).


 server.find(Order.class)
   .setUseDocStore(true)
   .where()... // perhaps add predicates
   .findEach((Order order) -> {
     // process the bean ...
   });

/**
   * Execute the query against the document store with the expectation of a large set of results
   * that are processed in a scrolling resultSet fashion.
   * <p>
   * For example, with the ElasticSearch doc store this uses SCROLL.
   * </p>
   * <p>
   * Typically this is called indirectly by findEach() on the query that has setUseDocStore(true).
   * </p>
   * <pre>{@code
   *
   *  server.find(Order.class)
   *    .setUseDocStore(true)
   *    .where()... // perhaps add predicates
   *    .findEach((Order order) -> {
   *      // process the bean ...
   *    });
   *
   * }</pre>
   */
  <T> void findEach(DocQueryRequest<T> query, Consumer<T> consumer);

  
Execute the query against the document store with the expectation of a large set of results
that are processed in a scrolling resultSet fashion.

Unlike findEach() this provides the opportunity to stop iterating through the large query.


For example, with the ElasticSearch doc store this uses SCROLL.


Typically this is called indirectly by findEachWhile() on the query that has setUseDocStore(true).


 server.find(Order.class)
   .setUseDocStore(true)
   .where()... // perhaps add predicates
   .findEachWhile(new Predicate<Order>() {
     @Override
     public void accept(Order bean) {
       // process the bean
       // return true to continue, false to stop
       // boolean shouldContinue = ...
       return shouldContinue;
     }
   });

/**
   * Execute the query against the document store with the expectation of a large set of results
   * that are processed in a scrolling resultSet fashion.
   * <p>
   * Unlike findEach() this provides the opportunity to stop iterating through the large query.
   * </p>
   * <p>
   * For example, with the ElasticSearch doc store this uses SCROLL.
   * </p>
   * <p>
   * Typically this is called indirectly by findEachWhile() on the query that has setUseDocStore(true).
   * </p>
   * <pre>{@code
   *
   *  server.find(Order.class)
   *    .setUseDocStore(true)
   *    .where()... // perhaps add predicates
   *    .findEachWhile(new Predicate<Order>() {
   *      @Override
   *      public void accept(Order bean) {
   *        // process the bean
   *
   *        // return true to continue, false to stop
   *        // boolean shouldContinue = ...
   *        return shouldContinue;
   *      }
   *    });
   *
   * }</pre>
   */
  <T> void findEachWhile(DocQueryRequest<T> query, Predicate<T> consumer);

  
Find each processing raw documents.
Params:
indexNameType – The full index name and type
rawQuery –      The query to execute
consumer –      Consumer to process each document/**
   * Find each processing raw documents.
   *
   * @param indexNameType The full index name and type
   * @param rawQuery      The query to execute
   * @param consumer      Consumer to process each document
   */
  void findEach(String indexNameType, String rawQuery, Consumer<RawDoc> consumer);

  
Find each processing raw documents stopping when the predicate returns false.
Params:
indexNameType – The full index name and type
rawQuery –      The query to execute
consumer –      Consumer to process each document until false is returned/**
   * Find each processing raw documents stopping when the predicate returns false.
   *
   * @param indexNameType The full index name and type
   * @param rawQuery      The query to execute
   * @param consumer      Consumer to process each document until false is returned
   */
  void findEachWhile(String indexNameType, String rawQuery, Predicate<RawDoc> consumer);

  
Process the queue entries sending updates to the document store or queuing them for later processing.
/**
   * Process the queue entries sending updates to the document store or queuing them for later processing.
   */
  long process(List<DocStoreQueueEntry> queueEntries) throws IOException;

  
Drop the index from the document store (similar to DDL drop table).

  DocumentStore documentStore = server.docStore();
  documentStore.dropIndex("product_copy");

/**
   * Drop the index from the document store (similar to DDL drop table).
   * <pre>{@code
   *
   *   DocumentStore documentStore = server.docStore();
   *
   *   documentStore.dropIndex("product_copy");
   *
   * }</pre>
   */
  void dropIndex(String indexName);

  
Create an index given a mapping file as a resource in the classPath (similar to DDL create table).

  DocumentStore documentStore = server.docStore();
  // uses product_copy.mapping.json resource
  // ... to define mappings for the index
  documentStore.createIndex("product_copy", null);

Params:
indexName – the name of the new index
alias –     the alias of the index/**
   * Create an index given a mapping file as a resource in the classPath (similar to DDL create table).
   * <pre>{@code
   *
   *   DocumentStore documentStore = server.docStore();
   *
   *   // uses product_copy.mapping.json resource
   *   // ... to define mappings for the index
   *
   *   documentStore.createIndex("product_copy", null);
   *
   * }</pre>
   *
   * @param indexName the name of the new index
   * @param alias     the alias of the index
   */
  void createIndex(String indexName, String alias);

  
Modify the settings on an index.

For example, this can be used be used to set elasticSearch refresh_interval
on an index before a bulk update.


  // refresh_interval -1 ... disable refresh while bulk loading
  Map<String,Object> settings = new LinkedHashMap<>();
  settings.put("refresh_interval", "-1");
  documentStore.indexSettings("product", settings);


  // refresh_interval 1s ... restore after bulk loading
  Map<String,Object> settings = new LinkedHashMap<>();
  settings.put("refresh_interval", "1s");
  documentStore.indexSettings("product", settings);

Params:
indexName – the name of the index to update settings on
settings –  the settings to set on the index/**
   * Modify the settings on an index.
   * <p>
   * For example, this can be used be used to set elasticSearch refresh_interval
   * on an index before a bulk update.
   * </p>
   * <pre>{@code
   *
   *   // refresh_interval -1 ... disable refresh while bulk loading
   *
   *   Map<String,Object> settings = new LinkedHashMap<>();
   *   settings.put("refresh_interval", "-1");
   *
   *   documentStore.indexSettings("product", settings);
   *
   * }</pre>
   * <pre>{@code
   *
   *   // refresh_interval 1s ... restore after bulk loading
   *
   *   Map<String,Object> settings = new LinkedHashMap<>();
   *   settings.put("refresh_interval", "1s");
   *
   *   documentStore.indexSettings("product", settings);
   *
   * }</pre>
   *
   * @param indexName the name of the index to update settings on
   * @param settings  the settings to set on the index
   */
  void indexSettings(String indexName, Map<String, Object> settings);

  
Copy the index to a new index.

This copy process does not use the database but instead will copy from the source index to a destination index.


 long copyCount = documentStore.copyIndex(Product.class, "product_copy");

Params:
beanType – The bean type of the source index
newIndex – The name of the index to copy to
Returns:
the number of documents copied to the new index/**
   * Copy the index to a new index.
   * <p>
   * This copy process does not use the database but instead will copy from the source index to a destination index.
   * </p>
   * <pre>{@code
   *
   *  long copyCount = documentStore.copyIndex(Product.class, "product_copy");
   *
   * }</pre>
   *
   * @param beanType The bean type of the source index
   * @param newIndex The name of the index to copy to
   * @return the number of documents copied to the new index
   */
  long copyIndex(Class<?> beanType, String newIndex);

  
Copy entries from an index to a new index but limiting to documents that have been
modified since the sinceEpochMillis time.

To support this the document needs to have a @WhenModified property.


 long copyCount = documentStore.copyIndex(Product.class, "product_copy", sinceMillis);

Params:
beanType – The bean type of the source index
newIndex – The name of the index to copy to
Returns:
the number of documents copied to the new index/**
   * Copy entries from an index to a new index but limiting to documents that have been
   * modified since the sinceEpochMillis time.
   * <p>
   * To support this the document needs to have a <code>@WhenModified</code> property.
   * </p>
   * <pre>{@code
   *
   *  long copyCount = documentStore.copyIndex(Product.class, "product_copy", sinceMillis);
   *
   * }</pre>
   *
   * @param beanType The bean type of the source index
   * @param newIndex The name of the index to copy to
   * @return the number of documents copied to the new index
   */
  long copyIndex(Class<?> beanType, String newIndex, long sinceEpochMillis);

  
Copy from a source index to a new index taking only the documents
matching the given query.

 // predicates to select the source documents to copy
 Query<Product> query = server.find(Product.class)
   .where()
     .ge("whenModified", new Timestamp(since))
     .ge("name", "A")
     .lt("name", "D")
     .query();
 // copy from the source index to "product_copy" index
 long copyCount = documentStore.copyIndex(query, "product_copy", 1000);

Params:
query –         The query to select the source documents to copy
newIndex –      The target index to copy the documents to
bulkBatchSize – The ElasticSearch bulk batch size, if 0 uses the default.
Returns:
The number of documents copied to the new index./**
   * Copy from a source index to a new index taking only the documents
   * matching the given query.
   * <pre>{@code
   *
   *  // predicates to select the source documents to copy
   *  Query<Product> query = server.find(Product.class)
   *    .where()
   *      .ge("whenModified", new Timestamp(since))
   *      .ge("name", "A")
   *      .lt("name", "D")
   *      .query();
   *
   *  // copy from the source index to "product_copy" index
   *  long copyCount = documentStore.copyIndex(query, "product_copy", 1000);
   *
   * }</pre>
   *
   * @param query         The query to select the source documents to copy
   * @param newIndex      The target index to copy the documents to
   * @param bulkBatchSize The ElasticSearch bulk batch size, if 0 uses the default.
   * @return The number of documents copied to the new index.
   */
  long copyIndex(Query<?> query, String newIndex, int bulkBatchSize);
}