com.google.appengine.api.prospectivesearch

## Interface ProspectiveSearchService

- Deprecated.
  This API has been deprecated.

      @Deprecated
      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.
  See Also:
    Query Language Overview in the Developer Guide., Handling Matches in the Developer Guide.

- - ### Field Summary

    Fields
    Modifier and Type | Field and Description
    --- | ---
    `static int` | `DEFAULT_LEASE_DURATION_SEC` Deprecated. The default lease duration value of zero means no expiration.
    `static int` | `DEFAULT_LIST_SUBSCRIPTIONS_MAX_RESULTS` Deprecated. Set to the backend service default batch size.
    `static int` | `DEFAULT_LIST_TOPICS_MAX_RESULTS` Deprecated. Set to the backend service default batch size.
    `static int` | `DEFAULT_RESULT_BATCH_SIZE` Deprecated. Set to a small size of 100 to allow quick processing in a TaskQueue task.
    `static java.lang.String` | `DEFAULT_RESULT_RELATIVE_URL` Deprecated. The default URI path to which matches will be POSTed.
    `static java.lang.String` | `DEFAULT_RESULT_TASK_QUEUE_NAME` Deprecated. Uses the default task queue.

  - ### Method Summary

    All Methods Instance Methods Abstract Methods Deprecated Methods
    Modifier and Type | Method and Description
    --- | ---
    `Entity` | `getDocument(HttpServletRequest matchCallbackPost)` Deprecated. Decodes document from `match(Entity, String, String, String, String, int, boolean)` result POST request.
    `Subscription` | `getSubscription(java.lang.String topic, java.lang.String subId)` Deprecated. Get the `Subscription` with the given topic and id.
    `java.util.List<Subscription>` | `listSubscriptions(java.lang.String topic)` Deprecated. Equivalent to:
    `java.util.List<Subscription>` | `listSubscriptions(java.lang.String topic, java.lang.String subIdStart, int maxResults, long expiresBefore)` Deprecated. The listSubscriptions call lists subscriptions that are currently active.
    `java.util.List<java.lang.String>` | `listTopics(java.lang.String topicStart, long maxResults)` Deprecated. List topics in lexicographic order.
    `void` | `match(Entity document, java.lang.String topic)` Deprecated. Equivalent to:
    `void` | `match(Entity document, java.lang.String topic, java.lang.String resultKey)` Deprecated. Equivalent to:
    `void` | `match(Entity document, java.lang.String topic, java.lang.String resultKey, java.lang.String resultRelativeUrl, java.lang.String resultTaskQueueName, int resultBatchSize, boolean resultReturnDocument)` Deprecated. 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)` Deprecated. 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)` Deprecated. Subscriptions are removed from the system using the unsubscribe call.

- - ### Field Detail

    - #### DEFAULT_LEASE_DURATION_SEC

          static final int DEFAULT_LEASE_DURATION_SEC

      Deprecated.
      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

      Deprecated.
      Set to the backend service default batch size.
      See Also:
        Constant Field Values

    - #### DEFAULT_LIST_TOPICS_MAX_RESULTS

          static final int DEFAULT_LIST_TOPICS_MAX_RESULTS

      Deprecated.
      Set to the backend service default batch size.
      See Also:
        Constant Field Values

    - #### DEFAULT_RESULT_BATCH_SIZE

          static final int DEFAULT_RESULT_BATCH_SIZE

      Deprecated.
      Set to a small size of 100 to allow quick processing in a TaskQueue task.
      See Also:
        Constant Field Values

    - #### DEFAULT_RESULT_RELATIVE_URL

          static final java.lang.String DEFAULT_RESULT_RELATIVE_URL

      Deprecated.
      The default URI path to which matches will be POSTed. Your application should install a handler at this location. The _ah prefix ensures that this path can only be accessed by your application and not via public HTTP connections.
      See Also:
        Constant Field Values

    - #### DEFAULT_RESULT_TASK_QUEUE_NAME

          static final java.lang.String DEFAULT_RESULT_TASK_QUEUE_NAME

      Deprecated.
      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)

      Deprecated.
      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.
      Parameters:
        `topic` - the subscription group to which this subscription will be added. Only `match(com.google.appengine.api.datastore.Entity, java.lang.String)` calls with the same topic will match this subscription
        `subId` - the unique string for this subscription; subscribe will overwrite subscriptions with the same subId
        `query` - the query in simple query format
        `leaseDurationSeconds` - time before the subscription is automatically removed or a value of 0 for no expiration
        `schema` - the map of field names to their corresponding types
      Throws:
        `QuerySyntaxException` - if the query is invalid or does not match schema
        `ApiProxy.ApplicationException` - if the backend call failed. See the message detail for the reason

    - #### unsubscribe

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

      Deprecated.
      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` - the subscription group of the subscription
        `subId` - the id of the subscription to remove, as specified during `subscribe(java.lang.String, java.lang.String, long, java.lang.String, java.util.Map<java.lang.String, com.google.appengine.api.prospectivesearch.FieldType>)`
      Throws:
        `java.lang.IllegalArgumentException` - if the given topic does not exist or has no subscription with the given subId
        `ApiProxy.ApplicationException` - if the backend call failed. See the message detail for the reason

    - #### match

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

      Deprecated.
      Equivalent to:

             match(entity, topic, "");

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

    - #### match

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

      Deprecated.
      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, boolean)`

    - #### 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)

      Deprecated.
      The match call is used to present a document for matching against all registered subscriptions of the same topic. A match results message is delivered asynchronously via TaskQueue POST to the given `resultRelativeURL`.
      Parameters:
        `document` - the document to match against registered subscriptions
        `topic` - the subscription group to match
        `resultKey` - a user defined key returned with the results message that can be used to associate the results message with this call
        `resultRelativeUrl` - the relative URL to which the results message will be delivered
        `resultTaskQueueName` - the name of the TaskQueue to use for delivering the results message
        `resultBatchSize` - the maximum number of subscription IDs per results message
      Throws:
        `ApiProxy.ApplicationException` - if the backend call failed. See the message detail for the reason
      See Also:
        Handling Matches in the Developer Guide.

    - #### listSubscriptions

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

      Deprecated.
      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)

      Deprecated.
      The listSubscriptions call lists subscriptions that are currently active.
      Parameters:
        `topic` - the subscription group to list
        `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` - if the backend call failed. See the message detail for the reason

    - #### getSubscription

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

      Deprecated.
      Get the `Subscription` with the given topic and id.
      Parameters:
        `topic` - the subscription group to which the subscription belongs
        `subId` - the id of the subscription
      Returns:
        the subscription
      Throws:
        `java.lang.IllegalArgumentException` - if no such subscription exists
        `ApiProxy.ApplicationException` - if the backend call failed. See the message detail for the reason

    - #### listTopics

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

      Deprecated.
      List topics in lexicographic order.
      Parameters:
        `topicStart` - the topic from which to start listing, or the empty string to start from the beginning
        `maxResults` - the maximum number of topics to return. A good default is 1000
      Returns:
        the list of topic names
      Throws:
        `ApiProxy.ApplicationException` - if the backend call failed. See the message detail for the reason

    - #### getDocument

          Entity getDocument(HttpServletRequest matchCallbackPost)

      Deprecated.
      Decodes document from `match(Entity, String, String, String, String, int, boolean)` 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