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 get 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  * GetResponse&lt;Index&gt; response = searchService.getIndexes(
  15  *     GetIndexesRequest.newBuilder());
  16  * for (Index index : response) {
  17  *   index.getName();
  18  *   index.getNamespace();
  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    * get 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    * Gets the indexes specified. The following code fragment shows how
  65    * to get the schemas of each available {@link Index}.
  66    *
  67    * <pre>{@code
  68    *   // Get the SearchService for the default namespace
  69    *   SearchService searchService = SearchServiceFactory.newSearchService();
  70    *
  71    *   // Get the first page of indexes available and retrieve schemas
  72    *   GetResponse<Index> response = searchService.getIndexes(
  73    *       GetIndexesRequest.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 get
  86    * @return a {@link GetResponse}{@code <Index>} containing a list of existing indexes
  87    * @throws GetException if there is a failure in the search service
  88    * getting indexes
  89    */
  90   public GetResponse<Index> getIndexes(GetIndexesRequest request);
  91
  92   /**
  93    * Gets the indexes specified in the request built from the {@code builder}.
  94    *
  95    * @param builder a builder to be used to construct a {@link GetIndexesRequest}
  96    *   specifying which indexes to get
  97    * @return a {@link GetResponse}{@code <Index>} containing a list of existing indexes
  98    */
  99   public GetResponse<Index> getIndexes(GetIndexesRequest.Builder builder);
 100
 101   /**
 102    * Gets the indexes requested asynchronously.
 103    *
 104    * @param request a request specifying which indexes to get
 105    * @return a {@link Future} that will allow getting a
 106    * {@link GetResponse}{@code <Index>} containing a list of existing indexes
 107    */
 108   public Future<GetResponse<Index>> getIndexesAsync(GetIndexesRequest request);
 109
 110   /**
 111    * Gets the indexes asynchronously for those specified in the request built from
 112    * the {@code builder}.
 113    *
 114    * @param builder a builder to be used to construct a {@link GetIndexesRequest}
 115    *   specifying which indexes to get
 116    * @return a {@link Future} that will allow getting a
 117    * {@link GetResponse}{@code <Index>} containing a list of existing indexes
 118    */
 119   public Future<GetResponse<Index>> getIndexesAsync(GetIndexesRequest.Builder builder);
 120 }