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

   1 // Copyright 2010 Google Inc. All Rights Reserved.
   2
   3 package com.google.appengine.api.search;
   4
   5 import com.google.appengine.api.search.checkers.IndexChecker;
   6
   7 import java.util.concurrent.Future;
   8
   9 /**
  10  * An Index allows synchronous and asynchronous adding and deleting of
  11  * {@link Document Documents} as well as synchronous and asynchronous
  12  * searching for Documents for a given {@link Query}. The following
  13  * code fragment shows how to add documents, then search the index for
  14  * documents matching a query.
  15  *<p>
  16  *<pre>
  17  *  // Get the SearchService for the default namespace
  18  *  SearchService searchService = SearchServiceFactory.getSearchService();
  19  *  // Get the index. If not yet created, create it.
  20  *  Index index = searchService.getIndex(
  21  *      IndexSpec.newBuilder().setIndexName("indexName"));
  22  *
  23  *  // Create a document.
  24  *  Document document = Document.newBuilder()
  25  *      .setId("documentId")
  26  *      .addField(Field.newBuilder().setName("subject").setText("my first email"))
  27  *      .addField(Field.newBuilder().setName("body")
  28  *           .setHTML("&lt;html&gt;some content here&lt;/html&gt;")
  29  *      .build();
  30  *
  31  *  // Put the document.
  32  *  try {
  33  *    index.put(document);
  34  *  } catch (PutException e) {
  35  *    if (StatusCode.TRANSIENT_ERROR.equals(e.getOperationResult().getCode())) {
  36  *      // retry putting document
  37  *    }
  38  *  }
  39  *
  40  *  // Query the index.
  41  *  try {
  42  *    Results&lt;ScoredDocument&gt; results =
  43  *        index.search(Query.newBuilder().build("subject:first body:here"));
  44  *
  45  *    // Iterate through the search results.
  46  *    for (ScoredDocument document : results) {
  47  *      // display results
  48  *    }
  49  *  } catch (SearchException e) {
  50  *    if (StatusCode.TRANSIENT_ERROR.equals(e.getOperationResult().getCode())) {
  51  *      // retry
  52  *    }
  53  *  }
  54  *</pre>
  55  *
  56  */
  57 public interface Index {
  58
  59   /**
  60    * @return the name of the index
  61    */
  62   String getName();
  63
  64   /**
  65    * @return the namespace of the index name
  66    */
  67   String getNamespace();
  68
  69   /**
  70    * @return the consistency mode of this index
  71    * @deprecated As of 1.7.3 Consistency is deprecated since only PER_DOCUMENT
  72    *   mode is supported
  73    */
  74   @Deprecated
  75   Consistency getConsistency();
  76
  77   /**
  78    * @see #delete(String...)
  79    */
  80   Future<Void> deleteAsync(String... documentId);
  81
  82   /**
  83    * @see #delete(String...)
  84    */
  85   Future<Void> deleteAsync(Iterable<String> documentIds);
  86
  87   /**
  88    * @see #deleteSchema()
  89    * @deprecated as of 1.7.4
  90    */
  91   @Deprecated
  92   Future<Void> deleteSchemaAsync();
  93
  94   /**
  95    * @see #put(Document...)
  96    */
  97   Future<PutResponse> putAsync(Document... document);
  98
  99   /**
 100    * @see #put(Document...)
 101    */
 102   Future<PutResponse> putAsync(Document.Builder... document);
 103
 104   /**
 105    * @see #put(Document...)
 106    */
 107   Future<PutResponse> putAsync(Iterable<Document> documents);
 108
 109   /**
 110    * @see #search(String)
 111    */
 112   Future<Results<ScoredDocument>> searchAsync(String query);
 113
 114   /**
 115    * @see #search(Query)
 116    */
 117   Future<Results<ScoredDocument>> searchAsync(Query query);
 118
 119   /**
 120    * @see #getRange(GetRequest)
 121    */
 122   Future<GetResponse<Document>> getRangeAsync(GetRequest request);
 123
 124   /**
 125    * @see #getRange(GetRequest)
 126    */
 127   Future<GetResponse<Document>> getRangeAsync(GetRequest.Builder builder);
 128
 129   /**
 130    * Delete documents for the given document ids from the index if
 131    * they are in the index.
 132    *
 133    * @param  documentIds the ids of documents to delete
 134    * @throws DeleteException if there is a failure in the search
 135    * service deleting documents
 136    * @throws IllegalArgumentException if some document id is invalid
 137    */
 138   void delete(String... documentIds);
 139
 140   /**
 141    * @see #delete(String...)
 142    */
 143   void delete(Iterable<String> documentIds);
 144
 145   /**
 146    * Delete the schema from the index. A possible use may be that there are
 147    * typed fields which are no longer required. Make sure that you re-index
 148    * some or all of your documents to enable search again. A sample of
 149    * documents is required that uses named fields to rebuild the schema.
 150    *
 151    * @throws DeleteException if there is a failure in the search service
 152    *   deleting the schema
 153    * @deprecated as of 1.7.4
 154    */
 155   @Deprecated
 156   void deleteSchema();
 157
 158   /**
 159    * Put the documents into the index, updating any document that is already
 160    * present.
 161    *
 162    * @param  documents the documents to put into the index
 163    * @return an {@link PutResponse} containing the result of
 164    * the put operations indicating success or failure as well as the document
 165    * ids. The search service will allocate document ids for documents which
 166    * have none provided
 167    * @throws PutException if there is a failure in the search
 168    * service putting documents
 169    * @throws IllegalArgumentException if some document is invalid or
 170    * more than {@link IndexChecker#MAXIMUM_DOCS_PER_REQUEST} documents
 171    * requested to be put into the index
 172    */
 173   PutResponse put(Document... documents);
 174
 175   /**
 176    * @see #put(Document...)
 177    */
 178   PutResponse put(Document.Builder... builders);
 179
 180   /**
 181    * @see #put(Document...)
 182    */
 183   PutResponse put(Iterable<Document> documents);
 184
 185   /**
 186    * Gets a {@link Document} for the given document Id.
 187    *
 188    * @param documentId the identifier for the document to retrieve
 189    * @return the associated {@link Document}. can be null
 190    */
 191   Document get(String documentId);
 192
 193   /**
 194    * @see #search(Query)
 195    */
 196   Results<ScoredDocument> search(String query);
 197
 198   /**
 199    * Search the index for documents matching the query. The query
 200    * must specify a query string, and optionally, how many documents
 201    * are requested, how the results are to be sorted, scored and
 202    * which fields are to be returned.
 203    *
 204    * @param  query the fully specified {@link Query} object
 205    * @return a {@link Results} containing
 206    * {@link ScoredDocument ScoredDocuments}
 207    * @throws IllegalArgumentException if the query is invalid
 208    * @throws SearchQueryException if the query string is invalid
 209    * @throws SearchException if there is a failure in the search service
 210    * performing the search
 211    */
 212   Results<ScoredDocument> search(Query query);
 213
 214   /**
 215    * Get an index's documents, in document Id order.
 216    *
 217    * @param  request contains various options restricting which documents are
 218    * returned.
 219    * @return a {@link GetResponse} containing a list of
 220    * documents from the index
 221    * @throws IllegalArgumentException if the get request is invalid
 222    */
 223   GetResponse<Document> getRange(GetRequest request);
 224
 225   /**
 226    * @see #getRange(GetRequest)
 227    */
 228   GetResponse<Document> getRange(GetRequest.Builder builder);
 229
 230   /**
 231    * @return the {@link Schema} describing supported document field names and
 232    * {@link Field.FieldType}s supported for those field names. This schema
 233    * will only be populated if the {@link GetIndexesRequest#isSchemaFetched}
 234    * is set to true on an {@link SearchService#getIndexes} request
 235    */
 236   Schema getSchema();
 237 }