# ProspectiveSearchService
Date: 2012-02-24

## com.google.appengine.api.prospectivesearch
Interface ProspectiveSearchService

    public interface ProspectiveSearchService

The Prospective Search App Engine API exposes the real-time and highly scalable Google Prospective Search Infrastructure as an App Engine service. The ProspectiveSearch API allows an app to register a set of queries (in a simple query format) to match against documents that are presented. For every document presented, the matcher will return the ids of all of the matching queries. To allow the app to handle a potentially large number of matched queries, the matched ids are enqueued as tasks on the TaskQueue. The target for these match notifications is defined in the member DEFAULT_RESULT_RELATIVE_URL.

Field Summary
`static int` `DEFAULT_LEASE_DURATION_SEC` The default lease duration value of zero means no expiration.
`static int` `DEFAULT_LIST_SUBSCRIPTIONS_MAX_RESULTS`
`static int` `DEFAULT_LIST_TOPICS_MAX_RESULTS`
`static int` `DEFAULT_RESULT_BATCH_SIZE`
`static java.lang.String` `DEFAULT_RESULT_RELATIVE_URL` The default URI path to which matches will be POSTed.
`static java.lang.String` `DEFAULT_RESULT_TASK_QUEUE_NAME` Uses the default task queue.

Method Summary
`Entity` `getDocument(HttpServletRequest matchCallbackPost)` Decodes document from `#match(Entity, String, String, String, String, int, bool)` result POST request.
`Subscription` `getSubscription(java.lang.String topic, java.lang.String subId)` Get subscription information.
`java.util.List<Subscription>` `listSubscriptions(java.lang.String topic)` Equivalent to: listSubscriptions(topic, "", DEFAULT_LIST_SUBSCRIPTIONS_MAX_RESULTS, 0);
`java.util.List<Subscription>` `listSubscriptions(java.lang.String topic, java.lang.String subIdStart, int maxResults, long expiresBefore)` The listSubscriptions call lists subscriptions that are currently active.
`java.util.List<java.lang.String>` `listTopics(java.lang.String topicStart, long maxResults)` List all topics from a given offset to a given limit.
`void` `match(Entity document, java.lang.String topic)` Equivalent to: match(entity, topic, "");
`void` `match(Entity document, java.lang.String topic, java.lang.String resultKey)` Equivalent to: match(entity, topic, resultKey, DEFAULT_RESULT_RELATIVE_URL, DEFAULT_RESULT_TASK_QUEUE_NAME, DEFAULT_RESULT_BATCH_SIZE, true);
`void` `match(Entity document, java.lang.String topic, java.lang.String resultKey, java.lang.String resultRelativeUrl, java.lang.String resultTaskQueueName, int resultBatchSize, boolean resultReturnDocument)` The match call is used to present a document for matching against all registered subscriptions of the same topic.
`void` `subscribe(java.lang.String topic, java.lang.String subId, long leaseDurationSeconds, java.lang.String query, java.util.Map<java.lang.String,FieldType> schema)` The subscribe call is used to register subscriptions, which comprise of a subscription id and a query.
`void` `unsubscribe(java.lang.String topic, java.lang.String subId)` Subscriptions are removed from the system using the unsubscribe call.

Field Detail

### DEFAULT_LEASE_DURATION_SEC

    static final int DEFAULT_LEASE_DURATION_SEC

  The default lease duration value of zero means no expiration.

  See Also:
    Constant Field Values

### DEFAULT_LIST_SUBSCRIPTIONS_MAX_RESULTS

    static final int DEFAULT_LIST_SUBSCRIPTIONS_MAX_RESULTS

See Also:
  Constant Field Values

### DEFAULT_LIST_TOPICS_MAX_RESULTS

    static final int DEFAULT_LIST_TOPICS_MAX_RESULTS

See Also:
  Constant Field Values

### DEFAULT_RESULT_BATCH_SIZE

    static final int DEFAULT_RESULT_BATCH_SIZE

See Also:
  Constant Field Values

### DEFAULT_RESULT_RELATIVE_URL

    static final java.lang.String DEFAULT_RESULT_RELATIVE_URL

  The default URI path to which matches will be POSTed. Your application should install a handler at this location.

  See Also:
    Constant Field Values

### DEFAULT_RESULT_TASK_QUEUE_NAME

    static final java.lang.String DEFAULT_RESULT_TASK_QUEUE_NAME

  Uses the default task queue. Equivalent to: com.google.appengine.api.taskqueue.QueueFactory.getDefaultQueue().getQueueName()

Method Detail

### subscribe

    void subscribe(java.lang.String topic,
                   java.lang.String subId,
                   long leaseDurationSeconds,
                   java.lang.String query,
                   java.util.Map<java.lang.String,FieldType> schema)

  The subscribe call is used to register subscriptions, which comprise of a subscription id and a query. A delay of a few seconds is expected between subscribe returning successfully and the subscription being registered. If this call returns without throwing an exception the subscription will eventually be registered.

  Parameters:
    `topic` - Specifies the namespace for the subscription. Subscriptions of a particular topic will only be matched against documents of the same topic.
    `subId` - Is a unique string for this subscription; subscribe will overwrite subscriptions with the same subId.
    `query` - Is a query written in the simple query format.
    `leaseDurationSeconds` - Seconds before the subscription is automatically removed or a value of 0 for no expiration.
    `schema` - Map of schema field names to their corresponding types.
  Throws:
    `QuerySyntaxException` - raised when query is invalid or does not match schema.
    `ApiProxy.ApplicationException` - Call failed. See the message detail for the reason.

### unsubscribe

    void unsubscribe(java.lang.String topic,
                     java.lang.String subId)

  Subscriptions are removed from the system using the unsubscribe call. A successful unsubscribe call guarantees that the subscription will eventually be removed. A delay of a few seconds is expected between the unsubscribe returning successfully and the subscription being removed. Once the last subscription for a given topic is removed, the topic also no longer exists.

  Parameters:
    `topic` - Must be the same as the topic of the subscription to be removed.
    `subId` - Is the id of the subscription to remove.
  Throws:
    `java.lang.IllegalArgumentException` - if the given topic does not exist or has no subscription with the given subId.
    `ApiProxy.ApplicationException` - Call failed. See the message detail for the reason.

### match

    void match(Entity document,
               java.lang.String topic)

  Equivalent to: match(entity, topic, "");

  See Also:
    `match(Entity, String, String)`

### match

    void match(Entity document,
               java.lang.String topic,
               java.lang.String resultKey)

  Equivalent to: match(entity, topic, resultKey, DEFAULT_RESULT_RELATIVE_URL, DEFAULT_RESULT_TASK_QUEUE_NAME, DEFAULT_RESULT_BATCH_SIZE, true);

  See Also:
    `#match(Entity, String, String, String, String, int, bool)`

### match

    void match(Entity document,
               java.lang.String topic,
               java.lang.String resultKey,
               java.lang.String resultRelativeUrl,
               java.lang.String resultTaskQueueName,
               int resultBatchSize,
               boolean resultReturnDocument)

  The match call is used to present a document for matching against all registered subscriptions of the same topic. The set of subscriptions matched are enqueued in batches as tasks on the TaskQueue.

  Parameters:
    `document` - To match.
    `topic` - Specifies the namespace for the subscriptions to match. Subscriptions of a particular topic will only be matched against documents of the same topic.
    `resultKey` - is a user defined key returned with the results that can be used to associate the result batch with a particular document.
    `resultRelativeUrl` - is the relative url on which to generate the http POST event that delivers the result batch.
    `resultTaskQueue` - The TaskQueue to use for delivering results.
    `resultBatchSize` - specifies the maximum number of subscription ids to put inside one result batch.
  Throws:
    `ApiProxy.ApplicationException` - Call failed. See the message detail for the reason.

### listSubscriptions

    java.util.List<Subscription> listSubscriptions(java.lang.String topic)

  Equivalent to: listSubscriptions(topic, "", DEFAULT_LIST_SUBSCRIPTIONS_MAX_RESULTS, 0);

  See Also:
    `listSubscriptions(String, String, int, long)`

### listSubscriptions

    java.util.List<Subscription> listSubscriptions(java.lang.String topic,
                                                   java.lang.String subIdStart,
                                                   int maxResults,
                                                   long expiresBefore)

  The listSubscriptions call lists subscriptions that are currently active.

  Parameters:
    `topic` - The topic specified should be the same as that used in the subscribe call.
    `subIdStart` - Subscriptions which are lexicographically greater or equal to the given value should be returned. NOTE: The empty string precedes all others.
    `maxResults` - Sets the maximum number of subscriptions that should be returned.
    `expiresBefore` - Limits the returned subscriptions to those that expire before the given time in seconds since epoch, or 0 for no expiration.
  Returns:
    A list of subscriptions.
  Throws:
    `ApiProxy.ApplicationException` - Call failed. See the message detail for the reason.

### getSubscription

    Subscription getSubscription(java.lang.String topic,
                                 java.lang.String subId)

  Get subscription information.

  Parameters:
    `topic` - The associated topic.
    `subId` - The subscription ID to lookup.
  Returns:
    The requested Subscription or `null` if the specified subscription does not exist.
  Throws:
    `IllegalArgumentExcpetion` - Subscription with specified id does not exist.
    `ApiProxy.ApplicationException` - Call failed. See the message detail for the reason.

### listTopics

    java.util.List<java.lang.String> listTopics(java.lang.String topicStart,
                                                long maxResults)

  List all topics from a given offset to a given limit. Topics will be returned in lexicographic order from the first or given start.

  Parameters:
    `topicStart` - The topic from which to start listing.
    `maxResults` - The maximum number of topics to return. A good default is 1000.
  Returns:
    A list of topic names.
  Throws:
    `ApiProxy.ApplicationException` - Call failed. See the message detail for the reason.

### getDocument

    Entity getDocument(HttpServletRequest matchCallbackPost)

  Decodes document from `#match(Entity, String, String, String, String, int, bool)` result POST request.

  Parameters:
    `matchCallbackPost` - The received POST request.
  Returns:
    The Entity that matched a subscription as the result of a match call, or null if it cannot be decoded.