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()
  22  *          .setIndexName("indexName")
  23  *          .setConsistency(Consistency.PER_DOCUMENT));
  24  *
  25  *  // Create a document.
  26  *  Document document = Document.newBuilder()
  27  *      .setId("documentId")
  28  *      .addField(Field.newBuilder().setName("subject").setText("my first email"))
  29  *      .addField(Field.newBuilder().setName("body")
  30  *           .setHTML("&lt;html&gt;some content here&lt;/html&gt;")
  31  *      .build();
  32  *
  33  *  // Add the document.
  34  *  try {
  35  *    index.add(document);
  36  *  } catch (AddException e) {
  37  *    if (StatusCode.TRANSIENT_ERROR.equals(e.getOperationResult().getCode())) {
  38  *      // retry adding document
  39  *    }
  40  *  }
  41  *
  42  *  // Query the index.
  43  *  try {
  44  *    Results&lt;ScoredDocument&gt; results =
  45  *        index.search(Query.newBuilder().build("subject:first body:here"));
  46  *
  47  *    // Iterate through the search results.
  48  *    for (ScoredDocument document : results) {
  49  *      // display results
  50  *    }
  51  *  } catch (SearchException e) {
  52  *    if (StatusCode.TRANSIENT_ERROR.equals(e.getOperationResult().getCode())) {
  53  *      // retry
  54  *    }
  55  *  }
  56  *</pre>
  57  *
  58  */
  59 public interface Index {
  60
  61   /**
  62    * @return the name of the index
  63    */
  64   String getName();
  65
  66   /**
  67    * @return the namespace of the index name
  68    */
  69   String getNamespace();
  70
  71   /**
  72    * @return the consistency mode of this index
  73    */
  74   Consistency getConsistency();
  75
  76   /**
  77    * @see {@link #remove(String...)}
  78    */
  79   Future<Void> removeAsync(String... documentId);
  80
  81   /**
  82    * @see {@link #remove(String...)}
  83    */
  84   Future<Void> removeAsync(Iterable<String> documentIds);
  85
  86   /**
  87    * @see {@link #add(Document...)}
  88    */
  89   Future<AddResponse> addAsync(Document... document);
  90
  91   /**
  92    * @see {@link #add(Document...)}
  93    */
  94   Future<AddResponse> addAsync(Iterable<Document> documents);
  95
  96   /**
  97    * @see use {@link #search(String)}
  98    */
  99   Future<Results<ScoredDocument>> searchAsync(String query);
 100
 101   /**
 102    * @see {@link #search(Query)}
 103    */
 104   Future<Results<ScoredDocument>> searchAsync(Query query);
 105
 106   /**
 107    * @see {@link #listDocuments(ListRequest)}
 108    */
 109   Future<ListResponse<Document>> listDocumentsAsync(ListRequest request);
 110
 111   /**
 112    * Delete documents for the given document ids from the index if
 113    * they are in the index.
 114    *
 115    * @param  documentIds the ids of documents to remove
 116    * @throws RemoveException if there is a failure in the search
 117    * service deleting documents
 118    * @throws IllegalArgumentException if some document id is invalid
 119    */
 120   void remove(String... documentIds);
 121
 122   /**
 123    * @see {@link #remove(String...)}
 124    */
 125   void remove(Iterable<String> documentIds);
 126
 127   /**
 128    * Add the documents to the index, updating any document that is already
 129    * present.
 130    *
 131    * @param  documents the documents to add to the index
 132    * @return an {@link AddResponse} containing the result of
 133    * the add operations indicating success or failure as well as the document
 134    * ids. The search service will allocate document ids for documents which
 135    * have none provided
 136    * @throws AddException if there is a failure in the search
 137    * service adding documents
 138    * @throws IllegalArgumentException if some document is invalid or
 139    * more than {@link IndexChecker#MAXIMUM_DOCS_PER_REQUEST} documents
 140    * requested to be added
 141    */
 142   AddResponse add(Document... documents);
 143
 144   /**
 145    * @see {@link #add(Document...)}
 146    */
 147   AddResponse add(Iterable<Document> documents);
 148
 149   /**
 150    * Gets a {@link Document} for the given document Id.
 151    *
 152    * @param documentId the identifier for the document to retrieve
 153    * @return the associated {@link Document}. can be null
 154    */
 155   Document get(String documentId);
 156
 157   /**
 158    * @see {@link #search(Query)}
 159    */
 160   Results<ScoredDocument> search(String query);
 161
 162   /**
 163    * Search the index for documents matching the query. The query
 164    * must specify a query string, and optionally, how many documents
 165    * are requested, how the results are to be sorted, scored and
 166    * which fields are to be returned.
 167    *
 168    * @param  query the fully specified {@link Query} object
 169    * @return a {@link Results} containing
 170    * {@link ScoredDocument ScoredDocuments}
 171    * @throws IllegalArgumentException if the query is invalid
 172    * @throws SearchQueryException if the query string is invalid
 173    * @throws SearchException if there is a failure in the search service
 174    * performing the search
 175    */
 176   Results<ScoredDocument> search(Query query);
 177
 178   /**
 179    * Lists the index's documents, in document Id order.
 180    *
 181    * @param  request contains various options restricting which documents are
 182    * returned.
 183    * @return a {@link ListResponse&lt;Document&gt;} containing a list of
 184    * documents from the index
 185    * @throws IllegalArgumentException if the list request is invalid
 186    */
 187   ListResponse<Document> listDocuments(ListRequest request);
 188
 189   /**
 190    * @return the {@link Schema} describing supported document field names and
 191    * {@link Field.FieldType}s supported for those field names. This schema
 192    * will only be populated if the {@link ListIndexesRequest#isSchemaFetched}
 193    * is set to true on an {@link SearchService#listIndexes} request
 194    */
 195   Schema getSchema();
 196 }