subscription

Contents
casp101
Contents
Use the Subscription resource to create or retrieve subscriptions. A
subscription
is a request to be notified of activity on any of the following:
  • Model types/attributes. Registers watches for model creation/deletion of type and attribute changes on those types.
    ModelType subscriptions watch for new models.
  • Models/attributes. Registers watches on specified models and related attribute changes.
  • Alarms/attributes. Registers watches for alarm creation/clearing and attribute changes.
  • Base URL
    http://<hostname><:portnumber>/spectrum/restful/subscription
POST Subscription
POST subscription creates a subscription. Subscriptions are
pull
or
push
. A
pull
subscription requires that the client poll the subscription ID whereas a
push
subscription requires that the client provide a URL to which notifications can be POSTed. Notifications contain change information in XML or JSON format.
Push subscriptions are useful when the integration client is another OneClick server.
  • URL
    http://<hostname><:portnumber>/spectrum/restful/subscription
  • HTTP Method
    POST
  • Body
    Uses Request.xsd:subscription-request. The Request.xsd is located in <
    $SPECROOT
    >/RestfulExamples/src/xsd
    For specific examples of Subscription XML, see the following:
    • In <
      $SPECROOT
      >/RestfulExamples/xml/Alarms:
      • PullAlarmsSubscription.xml
    • In <
      $SPECROOT
      >/RestfulExamples/xml/Models
      • PullAttrWatchForAllDevices.xml
    • In <
      $SPECROOT
      >/RestfulExamples/xml/MTypes:
      • PullWatchForNewMTypes.xml
      • PushWatchForNewMTypes.xml
      • PushWatchForNewMTypesBatchMode.xml
      • PushWatchForNewMTypesNoExpiration.xml
  • Body Content
    application/xml, application
  • Header
    application/xml, application/json
  • Output
    XML or JSON listing the subscription-id
Body Parameters
The following parameters are used in the subscription request body XML.
  • For pull subscriptions:
    • max-notifications
      Specifies the number of notification items.
      Default:
      100
    • max-queue-size
      Specifies the number of notifications to queue.
      Default:
      10000
    • pull-interval
      Specifies the frequency of polling in milliseconds.
      Subscriptions expire if not polled.
      Minimum:
      5000
If you expect a high frequency of notifications, you can accommodate plenty of notifications in the queue by increasing the
max-queue-size
. Simultaneously, to avoid a full queue, increase the
max-notifications
to pull more notifications in every poll. To empty the queue at a faster rate, reduce the
pull-interval
.
  • For push subscriptions:
    • destination-url
      Specifies the URL where notifications are POSTed.
      A test notification servlet has been if prints results to the
      CA Spectrum
      tomcat log. This servlet is installed with
      CA Spectrum
      , and no additional configuration is required. To use the servlet, set the destination-url to:
      http://<hostname><:portnumber>/spectrum/restful/TestNotifications
      Each time a notification is received it is printed to the
      CA Spectrum
      tomcat log, as follows:
      • For Windows: <
        $SPECROOT
        >/tomcat/logs
      • For Solaris and Linux: <
        $SPECROOT
        >/tomcat/logs/catalina.out
    • username
      Specifies the user name required by the destination URL.
    • password
      Specifies the password required by the destination URL.
    • batch-notifications
      • max-notifications
        Specifies the number of notifications in a batch. If this number is reached, notification is sent immediately.
        Default:
        100
      • max-time
        Specifies the time in milliseconds to wait before sending notifications. If this number is reached, notifications are sent immediately.
        Default:
        1000
    • heartbeat-interval
      Specifies the interval in milliseconds that the subscription is validated. The subscription servlet sends a message every hearbeat-interval to the receiving servlet (designated by the destination-url) to indicate that the subscription is active. If the receiving servlet stops receiving the heartbeat message, it knows that the subscription has stopped (for example, if the OneClick server stops or restarts). If the receiving servlet becomes unavailable, notifications stop.
      The TestNotifications servlet does not print the heartbeat message.
Example
The following is an example subscription registration snippet:
<rs:destination-url>http://<hostname><:portnumber>/spectrum/restful/TestNotifications</rs:destination-url> <rs:username><user></rs:username> <rs:password><password></rs:password>
The following is an example Java call:
Java GenericPoster noun=Models file= RestfulExamples/xml/Models/PullAttrWatchForAllDevices.xml server=localhost username=jdoe password=spectrum port=8080
GET Subscription
Use GET subscription to return XML describing all the changes of interest based on the initial subscription request.
GET subscription applies to the pull model only.
  • URL
    http://<hostnumber><:portnumber>/spectrum/restful/subscription/<subscription_ID>
  • HTTP Method
    GET
  • Body
    None
  • Body Content
    application/xml, application
  • Header
    application/xml, application/json
URL Parameters
  • subscription_ID
    Specifies the subscription ID. This value is returned from the original subscription request (POST subscription) or GET subscription/requests. It is used to obtain the set of changes since the last request.
GET subscription/requests
Use GET subscription/requests to return a string of the current, active subscriptions. This request is used primarily for debugging or verification purposes to see if a particular model, type or attribute is registered for notification.
To pull the actual model, model type, and attribute changes, see GET subscription.
  • URL
    http://<hostname><:portnumber>/spectrum/restful/subscription/requests
  • HTTP Method
    GET
  • Body
    None
  • Body Content
    application/xml, application
  • Header
    application/xml, application/json
  • Output
    HTML page listing the subscription-id and other subscription-related information for each current, active subscription
DELETE subscription
DELETE subscription deletes the specified subscription.
  • URL
    http://<hostname><:portnumber>/spectrum/restful/subscription/<subscription_ID>
  • HTTP Method
    DELETE
  • Body
    None
  • Body Content
    application/xml, application
  • Header
    application/xml, application/json
URL Parameters