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