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    * @deprecated as of 1.7.3. Use {@link #deleteAsync(String...)} instead
  80    */
  81   @Deprecated
  82   Future<Void> removeAsync(String... documentId);
  83
  84   /**
  85    * @see #delete(String...)
  86    * @deprecated as of 1.7.3. Use {@link #deleteAsync(Iterable<String>)} instead
  87    */
  88   @Deprecated
  89   Future<Void> removeAsync(Iterable<String> documentIds);
  90
  91   /**
  92    * @see #delete(String...)
  93    */
  94   Future<Void> deleteAsync(String... documentId);
  95
  96   /**
  97    * @see #delete(String...)
  98    */
  99   Future<Void> deleteAsync(Iterable<String> documentIds);
 100
 101   /**
 102    * @see #deleteSchema()
 103    * @deprecated as of 1.7.4
 104    */
 105   @Deprecated
 106   Future<Void> deleteSchemaAsync();
 107
 108   /**
 109    * @see #put(Document...)
 110    * @deprecated as of 1.7.3. Use {@link #putAsync(Document...)} instead
 111    */
 112   @Deprecated
 113   Future<AddResponse> addAsync(Document... document);
 114
 115   /**
 116    * @see #put(Document...)
 117    * @deprecated as of 1.7.3. Use {@link #putAsync(Document.Builder...)} instead
 118    */
 119   @Deprecated
 120   Future<AddResponse> addAsync(Document.Builder... document);
 121
 122   /**
 123    * @see #put(Document...)
 124    * @deprecated as of 1.7.3. Use {@link #putAsync(Iterable<Document>)} instead
 125    */
 126   @Deprecated
 127   Future<AddResponse> addAsync(Iterable<Document> documents);
 128
 129   /**
 130    * @see #put(Document...)
 131    */
 132   Future<PutResponse> putAsync(Document... document);
 133
 134   /**
 135    * @see #put(Document...)
 136    */
 137   Future<PutResponse> putAsync(Document.Builder... document);
 138
 139   /**
 140    * @see #put(Document...)
 141    */
 142   Future<PutResponse> putAsync(Iterable<Document> documents);
 143
 144   /**
 145    * @see #search(String)
 146    */
 147   Future<Results<ScoredDocument>> searchAsync(String query);
 148
 149   /**
 150    * @see #search(Query)
 151    */
 152   Future<Results<ScoredDocument>> searchAsync(Query query);
 153
 154   /**
 155    * @see #listDocuments(ListRequest)
 156    * @deprecated as of 1.7.3. Use {@link #getRangeAsync(GetRequest)}
 157    */
 158   @Deprecated
 159   Future<ListResponse<Document>> listDocumentsAsync(ListRequest request);
 160
 161   /**
 162    * @see #getRange(GetRequest)
 163    */
 164   Future<GetResponse<Document>> getRangeAsync(GetRequest request);
 165
 166   /**
 167    * @see #getRange(GetRequest)
 168    */
 169   Future<GetResponse<Document>> getRangeAsync(GetRequest.Builder builder);
 170
 171   /**
 172    * Delete documents for the given document ids from the index if
 173    * they are in the index.
 174    *
 175    * @param  documentIds the ids of documents to remove
 176    * @throws RemoveException if there is a failure in the search
 177    * service deleting documents
 178    * @throws IllegalArgumentException if some document id is invalid
 179    * @deprecated as of 1.7.3. Use {@link #delete(String...)} instead
 180    */
 181   @Deprecated
 182   void remove(String... documentIds);
 183
 184   /**
 185    * @see #delete(String...)
 186    * @deprecated as of 1.7.3. Use {@link #delete(Iterable<String>)} instead
 187    */
 188   @Deprecated
 189   void remove(Iterable<String> documentIds);
 190
 191   /**
 192    * Delete documents for the given document ids from the index if
 193    * they are in the index.
 194    *
 195    * @param  documentIds the ids of documents to delete
 196    * @throws DeleteException if there is a failure in the search
 197    * service deleting documents
 198    * @throws IllegalArgumentException if some document id is invalid
 199    */
 200   void delete(String... documentIds);
 201
 202   /**
 203    * @see #delete(String...)
 204    */
 205   void delete(Iterable<String> documentIds);
 206
 207   /**
 208    * Delete the schema from the index. A possible use may be that there are
 209    * typed fields which are no longer required. Make sure that you re-index
 210    * some or all of your documents to enable search again. A sample of
 211    * documents is required that uses named fields to rebuild the schema.
 212    *
 213    * @throws DeleteException if there is a failure in the search service
 214    *   deleting the schema
 215    * @deprecated as of 1.7.4
 216    */
 217   @Deprecated
 218   void deleteSchema();
 219
 220   /**
 221    * Add the documents to the index, updating any document that is already
 222    * present.
 223    *
 224    * @param  documents the documents to add to the index
 225    * @return an {@link AddResponse} containing the result of
 226    * the add operations indicating success or failure as well as the document
 227    * ids. The search service will allocate document ids for documents which
 228    * have none provided
 229    * @throws AddException if there is a failure in the search
 230    * service adding documents
 231    * @throws IllegalArgumentException if some document is invalid or
 232    * more than {@link IndexChecker#MAXIMUM_DOCS_PER_REQUEST} documents
 233    * requested to be added
 234    * @deprecated as of 1.7.3. Use {@link #put(Document...)} instead
 235    */
 236   @Deprecated
 237   AddResponse add(Document... documents);
 238
 239   /**
 240    * @see #put(Document...)
 241    * @deprecated as of 1.7.3. Use {@link #put(Document.Builder...)} instead
 242    */
 243   @Deprecated
 244   AddResponse add(Document.Builder... builders);
 245
 246   /**
 247    * @see #put(Document...)
 248    * @deprecated as of 1.7.3. Use {@link #put(Iterable<Document>)} instead
 249    */
 250   @Deprecated
 251   AddResponse add(Iterable<Document> documents);
 252
 253   /**
 254    * Put the documents into the index, updating any document that is already
 255    * present.
 256    *
 257    * @param  documents the documents to put into the index
 258    * @return an {@link AddResponse} containing the result of
 259    * the put operations indicating success or failure as well as the document
 260    * ids. The search service will allocate document ids for documents which
 261    * have none provided
 262    * @throws PutException if there is a failure in the search
 263    * service putting documents
 264    * @throws IllegalArgumentException if some document is invalid or
 265    * more than {@link IndexChecker#MAXIMUM_DOCS_PER_REQUEST} documents
 266    * requested to be put into the index
 267    */
 268   PutResponse put(Document... documents);
 269
 270   /**
 271    * @see #put(Document...)
 272    */
 273   PutResponse put(Document.Builder... builders);
 274
 275   /**
 276    * @see #put(Document...)
 277    */
 278   PutResponse put(Iterable<Document> documents);
 279
 280   /**
 281    * Gets a {@link Document} for the given document Id.
 282    *
 283    * @param documentId the identifier for the document to retrieve
 284    * @return the associated {@link Document}. can be null
 285    */
 286   Document get(String documentId);
 287
 288   /**
 289    * @see #search(Query)
 290    */
 291   Results<ScoredDocument> search(String query);
 292
 293   /**
 294    * Search the index for documents matching the query. The query
 295    * must specify a query string, and optionally, how many documents
 296    * are requested, how the results are to be sorted, scored and
 297    * which fields are to be returned.
 298    *
 299    * @param  query the fully specified {@link Query} object
 300    * @return a {@link Results} containing
 301    * {@link ScoredDocument ScoredDocuments}
 302    * @throws IllegalArgumentException if the query is invalid
 303    * @throws SearchQueryException if the query string is invalid
 304    * @throws SearchException if there is a failure in the search service
 305    * performing the search
 306    */
 307   Results<ScoredDocument> search(Query query);
 308
 309   /**
 310    * Lists the index's documents, in document Id order.
 311    *
 312    * @param  request contains various options restricting which documents are
 313    * returned.
 314    * @return a {@link ListResponse} containing a list of
 315    * documents from the index
 316    * @throws IllegalArgumentException if the list request is invalid
 317    * @deprecated as of 1.7.3. Use {@link #getRange(GetRequest)} instead.
 318    */
 319   @Deprecated
 320   ListResponse<Document> listDocuments(ListRequest request);
 321
 322   /**
 323    * Get an index's documents, in document Id order.
 324    *
 325    * @param  request contains various options restricting which documents are
 326    * returned.
 327    * @return a {@link GetResponse} containing a list of
 328    * documents from the index
 329    * @throws IllegalArgumentException if the get request is invalid
 330    */
 331   GetResponse<Document> getRange(GetRequest request);
 332
 333   /**
 334    * @see #getRange(GetRequest)
 335    */
 336   GetResponse<Document> getRange(GetRequest.Builder builder);
 337
 338   /**
 339    * @return the {@link Schema} describing supported document field names and
 340    * {@link Field.FieldType}s supported for those field names. This schema
 341    * will only be populated if the {@link GetIndexesRequest#isSchemaFetched}
 342    * is set to true on an {@link SearchService#getIndexes} request
 343    */
 344   Schema getSchema();
 345 }