UDDI Subscription

Use

The UDDI server provided with AS Java contains an implementation of the subscription API set. This API allows monitoring of activity in a registry by registering to track new, changed and deleted entries for the businessEntity, businessService, bindingTemplate, tModel, related businessEntity, and publisherAssertion entities.

A subscription request establishes criteria for the subscription and specifies how and if the subscriber should be notified of changes matching the specified criteria. You can use any of the existing standard inquiry APIs ( find_xx and get_xx) within a subscription request to define the criteria. The node policy can restrict which inquiry APIs are supported in subscription, as well as the duration of a subscription. Subscribers may create multiple subscriptions and can renew existing subscriptions periodically. Each subscription request is treated independently. You can specify in the subscription request the level of detail provided for the data returned.

Subscription allows subscribers to monitor a particular subset of data within the UDDI server. There are two subscription patterns, asynchronous notification and synchronous change tracking.

Asynchronous Notification

When registry data of interest changes, the UDDI server asynchronously notifies the subscribers via calls to the notify_subscriptionListener API. Subscribers should implement this API as a "subscription listener" service.

For asynchronous notifications requests, the subscription response provides information about new, changed, or deleted entities that have occurred after the subscription has been registered. A node notifies subscribers based upon its identification of data matching the requested subscription criteria. To receive these notifications via HTTP/SOAP, subscribers should implement a service called "subscription listener".

The UDDI server monitors the continuous stream of changes and provides notifications on a periodical basis. The subscription results provided via notifications pertain only to the current state of the entities at the time they are reported. While subscribers can specify a frequency for these notifications, nodes may choose to restrict this as a matter of policy.

Synchronous Change Tracking

Subscribers can manually issue an individual synchronous request using the get_subscriptionResults call. They obtain information about the registry activity depending on their subscription preferences. When you make a synchronous requests for subscription results, the UDDI server finds entries that were last created, changed, or deleted within a specified date range and returns the current state of the registry data matching the subscription criteria. Prior states of the registry data are not available and are not returned.

Prerequisites

You are familiar with the UDDI Subscription API set. More information: http://uddi.org/pubs/uddi_v3.htm

Note
All subscription API sets mentioned are described in the UDDI specification.
You have access to a SOAP client, with which you can connect to the UDDI server to submit SOAP requests and receive responses.
For asynchronous subscriptions:
- You know how to create a service. More information: Providing Web Services
- You know how to publish a service in the UDDI server. More information: Publishing Service Definitions Using the Services Registry

Procedure

Note

Use a SOAP client of your choice to send subscription requests and receive subscription responses.

Creating an Asynchronous Subscription

Create a Web service that receives the notifications provided by the UDDI server.

This HTTP/SOAP service receives the subscription notifications.
Publish the service in the UDDI server that the node is to use to deliver notifications.
Use a SOAP client to register a single bindingTemplate describing the service.
Choose the filter criteria to be used for the subscription and save the subscription request using the save_subscription call.

You should ensure that the subscriptionFilter criterion you use is as restrictive as possible. This way you can reduce the size of the returned result set, making it simpler to analyze.
The service starts receiving subscription notifications from the UDDI server.

You can process the incoming HTTP/SOAP notifications as desired.

Creating a Synchronous Subscription

Choose the filter criteria to be used for the subscription and save the subscription request using the save_subscription call.

You should ensure that the subscriptionFilter criterion you use is as restrictive as possible. This way you can reduce the size of the returned result set, making it simpler to analyze.

In the example below, you subscribe to receive notifications for tModels containing the demo word in their name:

                     <Envelope xmlns="http://schemas.xmlsoap.org/soap/envelope/">
  <Body>
    <save_subscription xmlns="urn:uddi-org:sub_v3">
      <subscription>
        <subscriptionFilter>
          <find_tModel xmlns="urn:uddi-org:api_v3">
            <findQualifiers>
              <findQualifier>uddi:uddi.org:findQualifier:approximateMatch</findQualifier> 
            </findQualifiers>
            <name>%demo%</name>
          </find_tModel>
        </subscriptionFilter>
      </subscription>
    </save_subscription>
  </Body>
</Envelope>

When the UDDI server receives such a request, it saves the subscription and provides a corresponding subscriptionKey in the response:

                     <Envelope xmlns="http://schemas.xmlsoap.org/soap/envelope/">
   <Body>
      <subscriptions xmlns="urn:uddi-org:sub_v3">
         <subscription>
            <subscriptionKey>9319efc0-a019-11dd-c7d0-000475ef542d</subscriptionKey>
            <subscriptionFilter>
               <find_tModel xmlns="urn:uddi-org:api_v3">
                  <findQualifiers>
                     <findQualifier>uddi:uddi.org:findqualifier:approximatematch</findQualifier>
                  </findQualifiers>
                  <name>%demo%</name>
               </find_tModel>
            </subscriptionFilter>
            <expiresAfter>2009-10-22T09:12:39.153Z</expiresAfter>
         </subscription>
      </subscriptions>
   </Body>
</Envelope>

Issue an individual synchronous request using the get_subscriptionResults call.

For example, you want to find which of the tModels containing the demo word in their name have been changed during a specific period. You specify the start and end of this period in the request and provide the subscriptionKey:

                     <Envelope xmlns="http://schemas.xmlsoap.org/soap/envelope/">
  <Body>
    <get_subscriptionResults xmlns="urn:uddi-org:sub_v3">
      <subscriptionKey>9319efc0-a019-11dd-c7d0-000475ef542d</subscriptionKey>
      <coveragePeriod>
        <startPoint>2008-10-21T07:08:30.655Z</startPoint>
        <endPoint>2008-10-23T09:16:30.655Z</endPoint>
      </coveragePeriod>
    </get_subscriptionResults>
  </Body>
</Envelope>

Receive the incoming notification and process it as desired.

In the example here, when the UDDI server receives such a request, it provides a corresponding subscriptionResultsList response:

                     <Envelope xmlns="http://schemas.xmlsoap.org/soap/envelope/">
   <Body>
      <subscriptionResultsList xmlns="urn:uddi-org:sub_v3">
         <coveragePeriod>
            <startPoint>2008-10-21T07:08:30.655Z</startPoint>
            <endPoint>2008-10-23T09:16:30.655Z</endPoint>
         </coveragePeriod>
         <subscription>
            <subscriptionKey>9319efc0-a019-11dd-c7d0-000475ef542d</subscriptionKey>
            <subscriptionFilter>
               <find_tModel xmlns="urn:uddi-org:api_v3">
                  <findQualifiers>
                     <findQualifier>uddi:uddi.org:findqualifier:approximatematch</findQualifier>
                  </findQualifiers>
                  <name>%demo%</name>
               </find_tModel>
            </subscriptionFilter>
            <maxEntities>19</maxEntities>
            <expiresAfter>2009-10-22T09:12:39.153Z</expiresAfter>
         </subscription>
         <tModelList xmlns="urn:uddi-org:api_v3">
            <tModelInfos>
               <tModelInfo tModelKey="uddi:ad515cc0-a019-11dd-a166-000475ef542d">
                  <name>This is a demo tModel</name>
               </tModelInfo>
               <tModelInfo tModelKey="uddi:b8bc5600-a019-11dd-bb39-000475ef542d">
                  <name>this is demo1</name>
               </tModelInfo>
            </tModelInfos>
         </tModelList>
      </subscriptionResultsList>
   </Body>
</Envelope>

Managing a Subscription

You can use additional API calls to manage a subscription:

Get a list of existing subscriptions previously saved by the subscriber with get_subscriptions.
Cancel one or more specified subscriptions using delete_subscription.