Subscription  Locate

The Oracle Service Registry advanced subscription demo set demonstrates the Oracle Service Registry application programming interface's capabilities and shows how to use the Subscription API to perform subscription calls to the registry.

The Oracle Service Registry advanced subscription demos cover the subscription aspects of the UDDI Version 3 Specification. They teach how to use the Oracle Service Registry client API to create new subscriptions, get lists of subscriptions, get subscription results, and delete subscriptions.

The Oracle Service Registry basic publishing demo set contains the following demos to assist you in learning the Oracle Service Registry client API:

SaveSubscription Demonstrates how to construct and fill the Save_subscription object, get a Subscription stub for the UDDI registry, and perform the save_subscription call.

GetSubscriptions Demonstrates how to construct and fill the Get_subscriptions object, get a Subscription stub for the UDDI registry, and perform the get_subscriptions call.

GetSubscriptionResults Demonstrates how to construct and fill the Get_subscriptionResults object, get a Subscription stub for the UDDI registry, and perform the get_subscriptionResults call.

DeleteSubscription Demonstrates how to construct and fill the Delete_subscription object, get a Subscription stub for the UDDI registry, and perform the delete_subscription call.

Prerequisites and Preparatory Steps: Code  Locate

We expect that you have already installed the Oracle Service Registry and set the REGISTRY_HOME environment variable to the registry's installation location.

To run the Oracle Service Registry's demos, your registry must be running.

It is necessary to configure the demos. The configuration system has two levels: global and local. The properties defined at the global level may be overwritten at the local level. The global properties are located in the file:

Windows: %REGISTRY_HOME%\demos\env.properties
UNIX: $REGISTRY_HOME/demos/env.properties

The values set during the installation of the Oracle Service Registry work out of box, and their modification affects all demos. If you need to redefine the value of some property for a single demo (that is, at the local level), edit env.properties. This file is located in the same directory as the file run.sh (run.bat). Local level properties for the Subscription demos are loaded from the file:

Windows: %REGISTRY_HOME%\demos\advanced\subscription\env.properties
UNIX: $REGISTRY_HOME/demos/advanced/subscription/env.properties

Table 9. Properties used in demos

NameDefault ValueDescription
uddi.demos.user.john.namedemo_johnfirst user's name
uddi.demos.user.john.passworddemo_johnfirst user's password
uddi.demos.url.subscriptionhttp://localhost:8888/registry/uddi/subscriptionthe subscription web service port URL
uddi.demos.url.securityhttp://localhost:8888/registry/uddi/securitythe security web service port URL

Presentation and Functional Presentation  Locate

This section describes the programming pattern used in all demos using the GetSubscriptionResults demo as an example. You can find this demo's source code in the file:

Windows: %REGISTRY_HOME%\demos\basic\subscription\src\demo\uddi\subscription\GetSubscriptionResults.java
UNIX: $REGISTRY_HOME/demos/basic/subscription/src/demo/uddi/subscription/GetSubscriptionResults.java

Let us start with a description of main method. The first part is used to configure the demo by the user. Then it logs the user into the UDDI registry, creates a Get_subscriptionResults object holding the parameters of the request. This object is transformed in the next step into the SOAP UDDI call get_subscriptionResults. Its results are then displayed and the user is logged off from the UDDI registry.

String user = UserInput.readString("Enter user name",
	                                     DemoProperties.getProperty(USER_JOHN_NAME));
String password = UserInput.readString("Enter password",
                                         DemoProperties.getProperty(USER_JOHN_PASSWORD));
String key = UserInput.readString("Enter subscription key", "");
int shift = UserInput.readInt("Enter start of coverage period in minutes", 60);
System.out.println();

UDDI_Security_PortType security = getSecurityStub();
String authInfo = getAuthInfo(user, password, security);
Get_subscriptionResults get = createGetSubscriptionResults(key, shift, authInfo);
SubscriptionResultsList result = getSubscriptionResults(get);
printSubscriptionResults(result);
discardAuthInfo(authInfo, security);

The method createGetSubscriptionResults takes subscriptionKey as a parameter that identifies the subscription in the UDDI registry, coveragePeriod, and authInfo of the user. The CoveragePeriod is used to identify the time period for which the user is interested in changes matched by the selected Subscription.

public static Get_subscriptionResults createGetSubscriptionResults(String subscriptionKey,
  int coveragePeriod, String authInfo) throws InvalidParameterException {
    Get_subscriptionResults getSubscriptionResults = new Get_subscriptionResults();
    getSubscriptionResults.setSubscriptionKey(subscriptionKey);

    // calculate coverage period
    long coveragePeriodShiftInMs = coveragePeriod * 60 * 1000;
    long endPoint = System.currentTimeMillis();
    long startPoint = endPoint - coveragePeriodShiftInMs;
    getSubscriptionResults.setCoveragePeriod(new CoveragePeriod(new Date(startPoint),
                                                                          new Date(endPoint)));
    getSubscriptionResults.setAuthInfo(authInfo);

    return getSubscriptionResults;
}

The helper method, getSubscriptionStub(), returns the UDDI Subscription stub of the web service listening at the URL specified by the URL_SUBSCRIPTION property.

public static UDDI_Subscription_PortType getSubscriptionStub() throws SOAPException {
     String url = DemoProperties.getProperty(URL_SUBSCRIPTION,
                                               "http://localhost:8888/registry/uddi/subscription");
     System.out.print("Using Subscription at url " + url + " ..");
     UDDI_Subscription_PortType subscriptionStub = UDDISubscriptionStub.getInstance(url);
     System.out.println(" done");
     return subscriptionStub;
}

The UDDI API call get_subscriptionResults is performed in the method getSubscriptionResults():

public static SubscriptionResultsList getSubscriptionResults(Get_subscriptionResults save)
  throws UDDIException, SOAPException {
    UDDI_Subscription_PortType subscriptionStub = getSubscriptionStub();
    System.out.print("Get in progress ...");
    SubscriptionResultsList result = subscriptionStub.get_subscriptionResults(save);
    System.out.println(" done");
    return result;
}

Building and Running Demos  Locate

This section shows how to build and run the Oracle Service Registry Advanced Subscription demo set. Let us continue with our GetSubscriptionResults demo.

  1. Be sure that the demos are properly configured and the Oracle Service Registry is up and running.

  2. Change your working directory to:

    Windows: %REGISTRY_HOME%\demos\advanced\subscription
    UNIX: $REGISTRY_HOME/demos/advanced/subscription

  3. Build all demos using:

    Windows: run.bat make
    UNIX: ./run.sh make

    [Note]Note

    When compiling demos on Windows platforms, you may see the following text:

    A subdirectory or file ..\..\common\.\build\classes already exists.

    This is expected and does not indicate a problem.

  4. To get a list of all available demos, run

    Windows: run.bat help
    UNIX: ./run.sh help

  5. The selected demo can be executed via the run with the name of the demo as parameter. For example, to run the GetSubscriptionResults demo, invoke

    Windows: run.bat GetSubscriptionResults
    UNIX: ./run.sh GetSubscriptionResults
  6. The Oracle Service Registry Subscription demos show a complete use case for the Subscription API. The SaveSubscription demo creates a new subscription for the user John Demo. This subscription monitors changes to the business entity named Marketing.

    Running SaveSubscription demo...
    Saving subscription where
    Enter user name [demo_john]:
    Enter password [demo_john]:
    Enter business name to watch [Marketing]:
    Enter subscription validity in days [2]:
    Enter limit of subscription results [5]:
    
    Using Security at url https://mycomp.com:8443/registry/uddi/security .. done
    Logging in .. done
    businessName = Marketing
    limit = 5
    valid = 2
    Using Subscription at url https://mycomp.com:8443/registry/uddi/subscription .. done
    Save in progress ... done
    
    Subscription 1 : uddi:4f0d7450-a578-11d8-91cd-5c1d367091cd
    <subscription brief="false" xmlns="urn:uddi-org:sub_v3">
        <subscriptionKey>uddi:4f0d7450-a578-11d8-91cd-5c1d367091cd</subscriptionKey>
        <subscriptionFilter>
            <find_business xmlns="urn:uddi-org:api_v3">
                <name>Marketing</name>
            </find_business>
        </subscriptionFilter>
        <maxEntities>5</maxEntities>
        <expiresAfter>2004-05-14T11:28:30.721+02:00</expiresAfter>
    </subscription>
    
    ********************************************************
    Logging out .. done

    If you want to list your available subscriptions, run the GetSubscriptions demo:

    Finding subscriptions where
    Enter user name [demo_john]:
    Enter password [demo_john]:
    
    Using Security at url https://mycomp.com:8443/registry/uddi/security .. done
    Logging in .. done
    Using Subscription at url https://mycomp.com:8443/registry/uddi/subscription .. done
    Get in progress ... done
    
    Subscription 1 : uddi:4f0d7450-a578-11d8-91cd-5c1d367091cd
    <subscription brief="false" xmlns="urn:uddi-org:sub_v3">
        <subscriptionKey>uddi:4f0d7450-a578-11d8-91cd-5c1d367091cd</subscriptionKey>
        <subscriptionFilter>
            <find_business xmlns="urn:uddi-org:api_v3">
                <name>Marketing</name>
            </find_business>
        </subscriptionFilter>
        <maxEntities>5</maxEntities>
        <expiresAfter>2004-05-14T11:28:30.721+02:00</expiresAfter>
    </subscription>
    
    ********************************************************
    Logging out .. done

    Now we need to generate some traffic on UDDI registry, that matches the subscription filter, that we have defined. You can use SaveBusiness demo from Oracle Service Registry Basic Publishing demos to save business entity named Marketing.

    Running SaveBusiness demo...
    Saving business entity where
    Enter (optional) businessKey []:
    Enter count of names [1]:
    Enter language code []:
    Enter name in language  [Marketing]:
    Enter description [Saved by SaveBusiness demo]:
    
    Using Security at url https://mycomp.com:8443/registry/uddi/security .. done
    Logging in .. done
    businessKey =
    lang = null, name = Marketing
    description = Saved by SaveBusiness demo
    Using Publishing at url https://mycomp.com:8443/registry/uddi/publishing .. done
    Save in progress ... done
    
    Business 1 : uddi:8097cc00-a578-11d8-91cd-5c1d367091cd
    <businessEntity businessKey="uddi:8097cc00-a578-11d8-91cd-5c1d367091cd" xmlns="urn:uddi-org:api_v3">
        <name> Marketing</name>
        <description> Saved by SaveBusiness demo</description>
    </businessEntity>

    Then we want to get the results of the subscription. It is necessary to specify correct subscription key and sufficient coverage period.

    Running GetSubscriptionResults demo...
    Finding subscription results where
    Enter user name [demo_john]:
    Enter password [demo_john]:
    Enter subscription key []: uddi:4f0d7450-a578-11d8-91cd-5c1d367091cd
    Enter start of coverage period in minutes [60]:
    
    Using Security at url https://mycomp.com:8443/registry/uddi/security .. done
    Logging in .. done
    Using Subscription at url https://mycomp.com:8443/registry/uddi/subscription .. done
    Get in progress ... done
    Subscription uddi:4f0d7450-a578-11d8-91cd-5c1d367091cd
    Coverage period=Fri May 14 08:30:28 CEST 2004 - Fri May 14 09:30:28 CEST 2004
    
    Subscription results:
    <subscriptionResultsList xmlns="urn:uddi-org:sub_v3">
        <chunkToken>0</chunkToken>
        <coveragePeriod>
            < startPoint>2004-05-14T08:30:28.565+02:00</startPoint>
            < endPoint>2004-05-14T09:30:28.824+02:00</endPoint>
        </coveragePeriod>
        < subscription brief="false">
            < subscriptionKey> uddi:4f0d7450-a578-11d8-91cd-5c1d367091cd</subscriptionKey>
            < subscriptionFilter>
                < find_business xmlns="urn:uddi-org:api_v3">
                     < name> Marketing</name>
                </find_business>
            </subscriptionFilter>
            < maxEntities>5</maxEntities>
            < expiresAfter>2004-05-14T11:28:30.721+02:00</expiresAfter>
        </subscription>
        < businessList>
            < businessInfos>
                < businessInfo businessKey="uddi:8097cc00-a578-11d8-91cd-5c1d367091cd">
                     < name> Marketing</name>
                     < description> Saved by SaveBusiness demo</description>
                </businessInfo>
            </businessInfos>
        </businessList>
    </subscriptionResultsList>
    
    ********************************************************

    If we do not need the subscription anymore, we can delete it with DeleteSubscription demo.

    Enter subscription key []: uddi:4f0d7450-a578-11d8-91cd-5c1d367091cd
    
    Using Security at url https://mycomp.com:8443/registry/uddi/security .. done
    Logging in .. done
    subscriptionKey = uddi:4f0d7450-a578-11d8-91cd-5c1d367091cd
    Using Subscription at url https://mycomp.com:8443/registry/uddi/subscription .. done
    Delete in progress ... done
    Logging out .. done