java/src/main/com/google/appengine/api/search/SearchService.java

   1 // Copyright 2010 Google Inc. All Rights Reserved.
   2
   3 package com.google.appengine.api.search;
   4
   5 import java.util.concurrent.Future;
   6
   7 /**
   8  * The SearchService is used to list available indexes, which can be
   9  * queried about their metadata or have index/delete/search operations
  10  * performed on them.  For example:
  11  *
  12  * <pre>
  13  * SearchService searchService = SearchServiceFactory.getSearchService();
  14  * List&lt;Index&gt; indexes = searchService.listIndexes();
  15  * for (Index index : indexes) {
  16  *   index.getName();
  17  *   index.getNamespace();
  18  *   index.getConsistency();
  19  *   index.search("query");
  20  * }
  21  * </pre>
  22  *
  23  * SearchService is also responsible for creating new indexes.  For
  24  * example:
  25  *
  26  * <pre>
  27  * SearchService searchService = SearchServiceFactory.getSearchService();
  28  * Index index = searchService.getIndex(IndexSpec.newBuilder().setName("myindex"));
  29  * </pre>
  30  *
  31  */
  32 public interface SearchService {
  33
  34   /**
  35    * Returns an instance of {@link Index} corresponding to the provided
  36    * specification.
  37    *
  38    * @return an instance of {@link Index} corresponding to the given
  39    * {@code spec}
  40    */
  41   public Index getIndex(IndexSpec spec);
  42
  43   /**
  44    * Returns an instance of {@link Index} corresponding to the
  45    * specification built from the given {@code builder}.
  46    *
  47    * @return an instance of {@link Index} corresponding to the given
  48    * {@code spec}
  49    */
  50   public Index getIndex(IndexSpec.Builder builder);
  51
  52   /**
  53    * Returns the namespace associated with this search service. Each
  54    * service instance is assigned one namespace and all operations,
  55    * such as listing documents, indexes inherit it. Also, when you
  56    * fetch an index, the namespace of this service is passed to the
  57    * returned index.
  58    *
  59    * @return the namespace associated with this search service.
  60    */
  61   public String getNamespace();
  62
  63   /**
  64    * Lists the indexes available. The following code fragment shows how
  65    * to list the schemas of each available {@link Index}.
  66    *
  67    * <pre>
  68    *   // Get the SearchService for the default namespace
  69    *   SearchService searchService = SearchServiceFactory.newSearchService();
  70    *
  71    *   // List the first page of indexes available and retrieve schemas
  72    *   ListIndexesResponse response = searchService.listIndexes(
  73    *       ListIndexesRequest.newBuilder().setSchemaFetched(true).build());
  74    *
  75    *   // List out elements of Schema
  76    *   for (Index index : response) {
  77    *     String name = index.getName();
  78    *     Schema schema = index.getSchema();
  79    *     for (String fieldName : schema.getFieldNames()) {
  80    *        List<FieldType> typesForField = schema.getFieldTypes(fieldName);
  81    *     }
  82    *   }
  83    * </pre>
  84    *
  85    * @param request a request specifying which indexes to list
  86    * @return a {@link ListIndexesResponse} containing list of existing indexes
  87    * @throws ListIndexesException if there is a failure in the search service
  88    * listing indexes
  89    */
  90   public ListIndexesResponse listIndexes(ListIndexesRequest request);
  91
  92   /**
  93    * Lists the indexes available asynchronously.
  94    *
  95    * @param request a request specifying which indexes to list
  96    * @return a {@link Future} that will allow getting a
  97    * {@link ListIndexesResponse} containing a list of existing indexes
  98    */
  99   public Future<ListIndexesResponse> listIndexesAsync(ListIndexesRequest request);
 100 }