java/src/main/com/google/appengine/api/prospectivesearch/ProspectiveSearchService.java

   1 // Copyright 2011 Google Inc. All rights reserved.
   2
   3 package com.google.appengine.api.prospectivesearch;
   4
   5 import com.google.appengine.api.datastore.Entity;
   6 import com.google.appengine.api.taskqueue.QueueFactory;
   7
   8 import java.util.List;
   9 import java.util.Map;
  10
  11 import javax.servlet.http.HttpServletRequest;
  12
  13 /**
  14  * The Prospective Search App Engine API exposes the real-time and
  15  * highly scalable Google Prospective Search Infrastructure as an App
  16  * Engine service. The ProspectiveSearch API allows an app to register
  17  * a set of queries (in a simple query format) to match against
  18  * documents that are presented. For every document presented, the
  19  * matcher will return the ids of all of the matching queries. To
  20  * allow the app to handle a potentially large number of matched
  21  * queries, the matched ids are enqueued as tasks on the TaskQueue.
  22  * The target for these match notifications is defined in the member
  23  * DEFAULT_RESULT_RELATIVE_URL.
  24  *
  25  * @see <a href="http://developers.google.com/appengine/docs/java/prospectivesearch/overview#Query_Language_Overview">Query
  26  * Language Overview</a> in the Developer Guide.
  27  * @see <a href="http://developers.google.com/appengine/docs/java/prospectivesearch/overview#Handling_Matches">Handling
  28  * Matches</a> in the Developer Guide.
  29  *
  30  */
  31 public interface ProspectiveSearchService {
  32
  33   /**
  34    * The default lease duration value of zero means no expiration.
  35    */
  36   public static final int DEFAULT_LEASE_DURATION_SEC = 0;
  37
  38   /**
  39    * Set to the backend service default batch size.
  40    */
  41   public static final int DEFAULT_LIST_SUBSCRIPTIONS_MAX_RESULTS = 1000;
  42
  43   /**
  44    * Set to the backend service default batch size.
  45    */
  46   public static final int DEFAULT_LIST_TOPICS_MAX_RESULTS = 1000;
  47
  48   /**
  49    * Set to a small size of 100 to allow quick processing in a
  50    * TaskQueue task.
  51    */
  52   public static final int DEFAULT_RESULT_BATCH_SIZE = 100;
  53
  54   /**
  55    * The default URI path to which matches will be POSTed.  Your
  56    * application should install a handler at this location.  The _ah
  57    * prefix ensures that this path can only be accessed by your
  58    * application and not via public HTTP connections.
  59    */
  60   public static final String DEFAULT_RESULT_RELATIVE_URL = "/_ah/prospective_search";
  61
  62   /**
  63    * Uses the default task queue.  Equivalent to:
  64    *
  65    * <pre>
  66    * com.google.appengine.api.taskqueue.QueueFactory.getDefaultQueue().getQueueName()
  67    * </pre>
  68    *
  69    */
  70   public static final String DEFAULT_RESULT_TASK_QUEUE_NAME =
  71       QueueFactory.getDefaultQueue().getQueueName();
  72
  73   /**
  74    * The subscribe call is used to register subscriptions, which
  75    * comprise of a subscription id and a query. A delay of a few
  76    * seconds is expected between subscribe returning successfully and
  77    * the subscription being registered.
  78    *
  79    * @param topic the subscription group to which this subscription
  80    *     will be added. Only {@link #match} calls with the same topic
  81    *     will match this subscription
  82    * @param subId the unique string for this subscription; subscribe
  83    *     will overwrite subscriptions with the same subId
  84    * @param query the query in simple query format
  85    * @param leaseDurationSeconds time before the subscription is
  86    *     automatically removed or a value of 0 for no expiration
  87    * @param schema the map of field names to their corresponding
  88    *     types
  89    * @throws QuerySyntaxException if the query is invalid or does not
  90    *     match schema
  91    * @throws ApiProxy.ApplicationException if the backend call failed.
  92    *     See the message detail for the reason
  93    */
  94   void subscribe(String topic,
  95       String subId,
  96       long leaseDurationSeconds,
  97       String query,
  98       Map<String, FieldType> schema);
  99
 100   /**
 101    * Subscriptions are removed from the system using the unsubscribe
 102    * call. A successful unsubscribe call guarantees that the
 103    * subscription will eventually be removed. A delay of a few seconds
 104    * is expected between the unsubscribe returning successfully and
 105    * the subscription being removed. Once the last subscription for a
 106    * given topic is removed, the topic also no longer exists.
 107    *
 108    * @param topic the subscription group of the subscription
 109    * @param subId the id of the subscription to remove, as specified
 110    *     during {@link #subscribe}
 111    * @throws IllegalArgumentException if the given topic does not
 112    *     exist or has no subscription with the given subId
 113    * @throws ApiProxy.ApplicationException if the backend call failed.
 114    *     See the message detail for the reason
 115    */
 116   void unsubscribe(String topic, String subId);
 117
 118   /**
 119    * Equivalent to:
 120    *
 121    * <pre>
 122    *   match(entity, topic, "");
 123    * </pre>
 124    *
 125    * @see #match(Entity, String, String)
 126    */
 127   void match(Entity document, String topic);
 128
 129   /**
 130    * Equivalent to:
 131    *
 132    * <pre>
 133    *   match(entity, topic, resultKey,
 134    *         DEFAULT_RESULT_RELATIVE_URL,
 135    *         DEFAULT_RESULT_TASK_QUEUE_NAME,
 136    *         DEFAULT_RESULT_BATCH_SIZE,
 137    *         true);
 138    * </pre>
 139    *
 140    * @see #match(Entity, String, String, String, String, int, boolean)
 141    */
 142   void match(Entity document, String topic, String resultKey);
 143
 144   /**
 145    * The match call is used to present a document for matching against
 146    * all registered subscriptions of the same topic.  A match results
 147    * message is delivered asynchronously via TaskQueue POST to the
 148    * given {@code resultRelativeURL}.
 149    *
 150    * @see <a href="http://developers.google.com/appengine/docs/java/prospectivesearch/overview#Handling_Matches">Handling
 151    * Matches</a> in the Developer Guide.
 152    * @param document the document to match against registered subscriptions
 153    * @param topic the subscription group to match
 154    * @param resultKey a user defined key returned with the results
 155    *     message that can be used to associate the results message
 156    *     with this call
 157    * @param resultRelativeUrl the relative URL to which the results
 158    *     message will be delivered
 159    * @param resultTaskQueueName the name of the TaskQueue to use for
 160    *     delivering the results message
 161    * @param resultBatchSize the maximum number of subscription IDs per
 162    *     results message
 163    * @throws ApiProxy.ApplicationException if the backend call failed.
 164    *     See the message detail for the reason
 165    */
 166   void match(Entity document,
 167       String topic,
 168       String resultKey,
 169       String resultRelativeUrl,
 170       String resultTaskQueueName,
 171       int resultBatchSize,
 172       boolean resultReturnDocument);
 173
 174   /**
 175    * Equivalent to:
 176    * <pre>
 177    *   listSubscriptions(topic, "",
 178    *                     DEFAULT_LIST_SUBSCRIPTIONS_MAX_RESULTS,
 179    *                     0);
 180    * </pre>
 181    * @see #listSubscriptions(String, String, int, long)
 182    */
 183   List<Subscription> listSubscriptions(String topic);
 184
 185   /**
 186    * The listSubscriptions call lists subscriptions that are currently
 187    * active.
 188    *
 189    * @param topic the subscription group to list
 190    * @param subIdStart subscriptions which are lexicographically
 191    *     greater or equal to the given value should be returned.
 192    *     NOTE: The empty string precedes all others
 193    * @param maxResults sets the maximum number of subscriptions that
 194    *     should be returned
 195    * @param expiresBefore limits the returned subscriptions to those
 196    *     that expire before the given time in seconds since epoch, or
 197    *     0 for no expiration
 198    * @return a list of subscriptions
 199    * @throws ApiProxy.ApplicationException if the backend call failed.
 200    *     See the message detail for the reason
 201    */
 202   List<Subscription> listSubscriptions(String topic,
 203       String subIdStart,
 204       int maxResults,
 205       long expiresBefore);
 206
 207   /**
 208    * Get the {@link Subscription} with the given topic and id.
 209    *
 210    * @param topic the subscription group to which the subscription
 211    *     belongs
 212    * @param subId the id of the subscription
 213    * @return the subscription
 214    * @throws IllegalArgumentException if no such subscription exists
 215    * @throws ApiProxy.ApplicationException if the backend call failed.  See the
 216    *     message detail for the reason
 217    */
 218   Subscription getSubscription(String topic, String subId);
 219
 220   /**
 221    * List topics in lexicographic order.
 222    *
 223    * @param topicStart the topic from which to start listing, or the
 224    *     empty string to start from the beginning
 225    * @param maxResults the maximum number of topics to return.  A good
 226    *     default is 1000
 227    * @return the list of topic names
 228    * @throws ApiProxy.ApplicationException if the backend call failed.
 229    *     See the message detail for the reason
 230    */
 231   List<String> listTopics(String topicStart, long maxResults);
 232
 233   /**
 234    * Decodes document from {@link #match(Entity, String, String,
 235    * String, String, int, boolean)} result POST request.
 236    *
 237    * @param matchCallbackPost the received POST request
 238    * @return the Entity that matched a subscription as the result of a
 239    *     match call, or null if it cannot be decoded
 240    * @throws com.google.common.util.Base64DecoderException if the
 241    *     document could not be decoded
 242    */
 243   Entity getDocument(HttpServletRequest matchCallbackPost);
 244 }