Chapter 18. UDDI

Table of Contents

18.1. Overview
18.1.1. Using UDDI
18.2. Operating UDDI Server in JEUS
18.2.1. Creating UDDI DataStore
18.2.2. Deploying JEUS UDDI Server
18.2.3. Configuring UDDI Server
18.2.4. Adding a New User
18.2.5. Starting UDDI Server
18.3. Using UDDI Explorer in JEUS Server
18.3.1. Querying UDDI Registry
18.3.2. Publishing UDDI Registry
18.3.3. Configuring JEUS UDDI Explorer
18.4. Creating UDDI Client
18.4.1. Creating UDDI Client
18.4.2. Compiling UDDI Client
18.4.3. Executing UDDI Client
18.5. How to Use XML Digital Signature
18.5.1. Digital Signature
18.5.2. How to Create XML Signature in UDDI Client
18.5.3. Verifying XML signature in UDDI Client
18.6. How to Use UDDI Subscription
18.6.1. Basic Concept
18.6.2. How to Create UDDI Subscription
18.6.3. UDDI Subscription Example
18.6.4. UDDI Subscription Client Programming
18.6.5. Configurations for Receiving E-Mail Notifications
18.7. How to Use UDDI WSDL Publishing
18.7.1. UDDI WSDL Publishing
18.7.2. Using wsdl2uddi

This chapter describes the basic concept of UDDI and its usage in JEUS. This chapter also covers how a UDDI client can programmatically access a UDDI registry, and how a web-based user interface can easily access the UDDI registry.

UDDI stands for Universal Description, Discovery, and Integration. The UDDI specification defines how to open and search for information about web services. UDDI is implemented using the existing standards, including Extensible Markup Language (XML) and Simple Object Access Protocol (SOAP).

UDDI takes an approach based on the distributed registry for businesses implemented in a general XML format and their service descriptions. The key component of a UDDI project is UDDI business registration, the XML file that describes the business entity, and its web service.

UDDI provides a programming model and schema, and defines their rules by using the registry. All APIs of the UDDI specification are defined in XML, wrapped in a SOAP envelope, and transmitted via HTTP.

UDDI includes shared business registry operations on the web. In most cases, the UDDI business registry is used when the program and programmer locates the service information. Especially for a programmer, it is used to prepare a system that is compatible with a known web service or to specify another user to be able to invoke the web service. The information in the UDDI business registry is used for this purpose.

The UDDI business registry is used at the business level to check if the given partner implements a particular web service interface, or to search for a company in the industry by using the related service. It can also be used to get information about how a partner exported the web service in order to obtain technical information about the service.

UDDI Data Structure

The data structure of UDDI registry is defined by using an XML schema.

UDDI XML schema consists of four constructions that provide useful information about using the partner's web services to engineers. The four constructions are the <businessEntity> structure for service specification, <businessService> structure, <bindingTemplate> structure, and <tModel> structure.

The following is a figure of the data structure of the information layer and the XML tags used to describe and search for web service information.


JEUS UDDI consists of a UDDI registry server, UDDI client library, and web-based user interface. JEUS UDDI supports data structures for UDDI version 2.0 and 3.0, and programming API.

This section describes how to deploy UDDI modules in JEUS and run JEUS UDDI server.

  • Creating JEUS UDDI DataStore

  • Deploying JEUS UDDI server

  • Configuring JEUS UDDI server

The library for JEUS UDDI package is located under the 'JEUS_HOME\lib\system' directory, and the web interface related contexts and modules are provided as an EAR package.

Publishing UDDI data to a UDDI registry requires an authentication from the UDDI registry.

There are two levels of publisher authentication for the UDDI registry.

  1. Authenticating a user via userID/password

    JEUS UDDI registry has a default authenticator module named 'jeus.webservices.uddi.auth.DefaultAuthenticator'. This module simply checks the userID.

    JEUS UDDI registry provides an additional authentication module named 'jeus.webservices.uddi.auth.XMLDocAuthenticator'. It is an XML document based authentication, and the user can add or modify the uddi-user.xml file in the 'JEUS_HOME\lib\application' directory.

    Refer to the following example.

    <?xml version="1.0" encoding="UTF-8"?>
    <uddi-users>
        <user userid="administrator" password="jeusadmin" />
        <user userid="tmaxsoft" password="password" />
        <user userid="jeus" password="password" />
        <user userid="webservices" password="password" />
    </uddi-users>

    Users can develop their own custom authentication modules, and UDDI registry can utilize external authentication mechanisms. Additional JEUS UDDI authentication modules can be developed by JEUS UDDI users who can decide on an authentication method for a particular environment.

    The following code shows how to develop a custom JEUS UDDI authentication module.

    import jeus.webservices.uddi.auth.BaseAuthenticator;
    import org.apache.juddi.error.RegistryException;
    
    public class SampleAuthenticator implements BaseAuthenticator {
    
        public SampleAuthenticator() {
        }
    
        public String authenticate(String userID, String credential) 
            throws RegistryException {
            // TODO Part implemented by developer.
            return userID;
        }
    }
  2. Registering an authenticated user as a UDDI registry user

    The registration can be made by either using UDDI web user interface or directly registering with the UDDI DataStore. In this section, the method of directly registering with the UDDI DataStore will be described. For more information about registering through UDDI web user interface, refer to "18.3. Using UDDI Explorer in JEUS Server".

    To directly register with the UDDI DataStore, it must be checked whether the publisher (UDDI registry user) is defined in the UDDI DataStore. The publisher is defined when there is a row that identifies the publisher in the PUBLISHER table of the UDDI database, and the user can be defined by using SQL.

    The following example shows how to define a new publisher named 'jeus'.

    INSERT INTO PUBLISHER (PUBLISHER_ID,PUBLISHER_NAME,ADMIN)
    VALUES ('jeus','JEUS','false');


JEUS UDDI Explorer is a web application that allows a user to register, update, query, and delete the UDDI data in a UDDI registry.

The following are the features that JEUS UDDI Explorer provides.

  • Querying private UDDI registry.

  • Publishing to a private UDDI registry.

  • Configuring the JEUS UDDI Explorer.

This section describes how to use the JEUS UDDI Explorer's Web UI.

In order to publish to a UDDI registry, the user must first log in to the UDDI registry with a user ID and password. After the user logs in, the JEUS UDDI Explorer shows the registered Businesses and Technical Models that have been registered by the user. Click on the ‘[+]’ symbol from the left menu tree to expand the list of registered services and other information. The details are shown on the right panel.

Basic businesses and technical models can be added by using [Add Provider] and [Add TModel] respectively. An existing registry can be deleted or edited with [Delete] or [Edit] respectively.


Adding a business

A business item is added in the following order.

Adding a service

Service is added in the following order.

Adding a tModel

The following are the steps for adding a tModel.

Adding a bindingTemplate

The following are the steps for adding a bindingTemplate.

JEUS UDDI client library provides Java interface for the UDDI registry. Through the library, a user can search for or publish a web service. It is the Java client library that provides APIs for interacting with a UDDI registry.

This section describes how to create, compile, and execute the UDDI client by using the JEUS UDDI client library. The example UDDI client shown in this chapter is using UDDI v2.0, and the client that uses UDDI v3.0 can also be used in a similar way.

The following describes how to create a UDDI client

  • UDDI Client Class

    UDDI Client class is the main class of UDDI client application. It contains all methods needed to connect to a UDDI registry, and to handle any query jobs and query results.

    The following example shows how to instantiate a client and reference a UDDI registry. In the following example application, a UDDIClient is used to communicate with the UDDI registry.

    UDDIClient client = new UDDIClient();
    client.setInquiryURL("http://localhost:8088/uddi/inquiry");
    client.setPublishURL("http://localhost:8088/uddi/publish");

  • Querying for a business in a UDDI registry

    Vector inNames = new Vector();
    inNames.add(new Name("test_Biz"));
    
    BusinessList list = client.find_business(null, inNames, null, null, null, null, 0);

    The fine_business method has multiple parameters. The second parameter is a search keyword and the seventh parameter specifies the maximum number of return values that satisfy the conditions. When set to ‘0’, it returns all results that meet the conditions.

    For more detailed search, an identifier, category, URL, tModel, etc. can be entered as search criterias.

    After receiving a list of Businesses as the result, the following example shows how to output all Business names.

    BusinessInfos infos = list.getBusinessInfos();
    Vector businesses = infos.getBusinessInfoVector();
    
    if (businesses != null) {
        for (int i = 0; i < businesses.size(); i++) {
            BusinessInfo info = (BusinessInfo)businesses.elementAt(i);
            Vector outNames = info.getNameVector();
            for (int j = 0; j < outNames.size(); j++) {
                Name name = (Name)outNames.elementAt(j);
                System.out.println(name.getValue());
            }
        }
    }
  • Publishing businesses to a UDDI registry

    In order to publish a new UDDI data to a UDDI registry, the user must be authenticated by the UDDI registry. The following code shows how to obtain an authentication from the UDDI registry.

    AuthToken authToken = client.get_authToken(“userID”, “password”);

    Next step is to instantiate a new BusinessEntity and publish it to the UDDI registry. In this example, only the business name is defined.

    BusinessEntity businessEntity = new BusinessEntity();
    businessEntity.setBusinessKey("");
    businessEntity.addName(new Name("TmaxSoft", "en"));
    
    Vector businessVector = new Vector();
    businessVector.add(businessEntity);
    
    BusinessDetail detail = client.save_business(
        authToken.getAuthInfoString(), businessVector);
  • Removing businesses from a UDDI registry

    Vector inNames = new Vector();
    inNames.add(new Name("TmaxSoft"));
    
    BusinessList list = client.find_business(null, inNames, null, null, null, null, 0);

    After receiving a list of Businesses by using the previous code, the following example shows how to remove a specific Business from the registry.

    Refer to the following example.

    Vector businessInfoVector = list.getBusinessInfos().getBusinessInfoVector();
    for (int i = 0; i < businessInfoVector.size(); i++) {
        BusinessInfo info = (BusinessInfo)businessInfoVector.elementAt(i);
        DispositionReport dispositionReport = client.delete_business(
            authToken.getAuthInfoString(), info.getBusinessKey());
    }

This section describes the concept of XML digital signature and verification method.

XML signature is calculated for higher level elements that are stored in a UDDI registry as a result of invoking a published API.

The following elements are used for each API invocation.

APIelement
save_businessbusinessEntity
save_servicebusinessService
save_bindingbindingTemplate
save_tModeltModel

set_publisherAssertions

add_publisherAssertions

publisherAssertion

JEUS UDDI client signs high level UDDI entity by using java.security.PrivateKey and java.security.cert.X509Certificate objects of java.security.*.

The following example shows how to obtain the PrivateKey and X509Certificate objects.

import java.security.KeyStore;
import java.security.PrivateKey;
import java.security.cert.X509Certificate;
...

String keystoreType = "JKS";
String privateKeyAlias = "...";
String privateKeyPasswd = "...";
String certificateAlias = "...";
...
KeyStore keyStore = KeyStore.getInstance(keystoreType);
keyStore.load(...);

PrivateKey privateKey = (PrivateKey)keyStore.getKey(
    privateKeyAlias, privateKeyPasswd.toCharArray());
X509Certificate certificate = 
    (X509Certificate)keyStore.getCertificate(certificateAlias);

JEUS UDDI client programming method that supports XML signature by using the obtained PrivateKey and X509Certificate objects is the same as the existing JEUS UDDI client programming method. For more information, refer to "18.4. Creating UDDI Client".

The published UDDI entity is signed by using the following methods of the jeus.uddi.v3. client.UDDIClient class.

public BindingDetail save_binding(
       String authInfo, bindingTemplate bindingTemplate,
       PrivateKey privateKey, X509Certificate certificate)
public BusinessDetail save_business(
       String authInfo, BusinessEntity businessEntity,
       PrivateKey privateKey, X509Certificate certificate)
public ServiceDetail save_service(
       String authInfo, BusinessService businessService,
       PrivateKey privateKey, X509Certificate certificate)
public TModelDetail save_tModel(
       String authInfo, TModel tModel,
       PrivateKey privateKey, X509Certificate certificate)
public PublisherAssertions set_publisherAssertions(
       String authInfo, PublisherAssertion publisherAssertion,
       PrivateKey privateKey, X509Certificate certificate)

The UDDI entity that needs to be signed must contain an entity key. If the UDDI entity is published without an entity key, the UDDI registry assigns a new entity key for the UDDI entity. As a result, the signature for the UDDI entity becomes invalid. To avoid this problem, the publisher is responsible for publishing a UDDI entity with an entity key.

For instance, a businessService has to contain a serviceKey and businessKey. If the businessService includes a bindingTemplate, the bindingTemplate must contain the bindingKey and serviceKey.

This section describes the concept, creation, and client programming of UDDI subscriptions, and how to set UDDI server to receive e-mails.

This section describes an asynchronous notification and a synchronous query example.

Asynchronous Notification

The following example shows how to run subscription in a simple asynchronous notification format.

  1. Create a subscription to track modifications to the business object.

    To do this, a subscriber needs to register a service that has a bindingTemplate to the UDDI registry which will send the notification. In order to receive the notification via 'notify_subscriptionListener' service or e-mail, the endpoint must be marked in the bindingTemplate.

    <save_binding xmlns="urn:uddi-org:api_v3">
        <authInfo>myAuthCode</authInfo>
        <bindingTemplate bindingKey="" serviceKey="uddi:myservicekey">
           <description>notify_subscriptionListener binding for
               my subscription.
           </description>
           <accessPoint URLType="https">
               https://www.myCompany.com/services/notify_subscriptionListener
           </accessPoint>
           <tModelInstanceDetails>
               <tModelInstanceInfo
                   tModelKey="uddi:uddi.org:v3_subscriptionlistener"/>
           </tModelInstanceDetails>
        </bindingTemplate>
    </save_binding>
    <save_binding xmlns="urn:uddi-org:api_v3">
        <authInfo>myAuthCode</authInfo>
        <bindingTemplate  bindingKey="" serviceKey="uddi:myservicekey">
           <description>
               E-mail binding for my subscription.
           </description>
           <accessPoint URLType="email">
               mailto:mySubscriberEmail@xyz.com
           </accessPoint>
        </bindingTemplate>
    </save_binding>

    (Source: http://uddi.org/pubs/uddi-v3.0.2-20041019.htm)

  2. Create and save the subscription to periodically send a notification (in the example, every five days). In the example, the 'brief' attribute is used to only allow the entity key to be used on the result.

    <save_subscription xmlns="urn:uddi-org:sub_v3">
        <authInfo>myAuthCode</authInfo>
        <subscriptions>
            <subscription brief="true">
                <subscriptionFilter>
                    <find_service xmlns="urn:uddi-org:api_v3" >
                        <findQualifiers>
                            <findQualifier>
                                uddi:uddi.org:findqualifier:sql99:like
                            </findQualifier>
                        </findQualifiers>
                        <categoryBag>
                            <keyedReference
                                tModeKey="uddi:uddi.org:ubr:taxonomy:naics"
                                keyName="Motor Vehicle Parts"
                                keyValue="42112_"/>
                        </categoryBag>
                    </find_service>
                </subscriptionFilter>
                    <bindingKey>
                         bindingKeyOfTheClientsNotifySubscriptionListenerService
                    </bindingKey>
                    <notificationInterval>P5D</notificationInterval>
                    <maxEntities>1000</maxEntities>
            </subscription>
        </subscriptions>
    </save_subscription>

    (Source: http://uddi.org/pubs/uddi-v3.0.2-20041019.htm)

The following is the notification result of invoking a client that implements the 'notify_subscription- Listener' API.

<notify_subscriptionListener>
    <subscriptionResultsList>
        <coveragePeriod>
            <startPoint>20020101T00:00:00</startPoint>
            <endPoint>20020131T00:00:00</endPoint>
        </coveragePeriod> 
        <subscription brief="true">
            <subscriptionFilter>
                <find_service xmlns="urn:uddi-org:api_v3" >
                    <findQualifiers>
                        <findQualifier>
                            uddi:uddi.org:findqualifier:sql99:like
                        </findQualifier>
                    </findQualifiers>
                    <categoryBag>
                        <keyedReference
                            tModeKey="uddi:uddi.org:ubr:taxonomy:naics"
                            keyName="Motor Vehicle Parts"
                            keyValue="42112_"/>
                    </categoryBag>
                </find_service>
                </subscriptionFilter>
                <bindingKey>
                    bindingKeyOfTheClientsNotifySubscriptionListenerService
                </bindingKey>
                <notificationInterval>P5D</notificationInterval>
                <maxEntities>1000</maxEntities>
                <expiresAfter>20030101T00:00:00</expiresAfter>
        </subscription>
        <keyBag>
            <deleted>false</deleted>
            <serviceKey>matchingKey1</serviceKey>
            <serviceKey>matchingKey2</serviceKey>
            <serviceKey>matchingKey3</serviceKey>
            <serviceKey>matchingKey4</serviceKey>
        </keyBag>
        <keyBag>
            <deleted>true</deleted>
            <serviceKey>matchingKey5</serviceKey>
            <serviceKey>matchingKey6</serviceKey>
        </keyBag>
    </subscriptionResultsList>
</notify_subscriptionListener>

(Source: http://uddi.org/pubs/uddi-v3.0.2-20041019.htm)

The subscription whose 'brief' attribute is set to 'true' notifies the result only through the entity key. The entity key is included in the <keyBag> element. The <keyBag> element includes the already deleted entity keys which are notified with the <deleted> element set to 'true'.

Synchronous Query

It is possible to synchronously obtain a subscription result by using the API. A subscription for a synchronous query is stored in the same way as in the asynchronous notification example. The only difference is that the <bindingKey> element for the subscription listener is not required to save a subscription for a synchronous query.

The following is a typical example of using the 'get_subscriptionResults' API.

<get_subscriptionResults>
    <authInfo>myAuthCode</authInfo>
    <subscriptionKey>mySubscriptionKey</subscriptionKey>
    <coveragePeriod>
        <startPoint>20020101T00:00:00</startPoint>
    </coveragePeriod>
</get_subscriptionResults>

(Source: http://uddi.org/pubs/uddi-v3.0.2-20041019.htm)

The response to the previous query is sent synchronously in the <subscriptionResultList> format.

<subscriptionResultsList>
    <chunkToken>"nodeGeneratedToken"</chunkToken>
    <coveragePeriod>
        <startPoint>20020101T00:00:00</startPoint>
    </coveragePeriod>
    <subscription  brief="true">
        <subscriptionFilter>
            <find_service xmlns="urn:uddi-org:api_v3">
                <findQualifiers>
                    <findQualifier>
                        uddi:uddi.org:findqualifier:sql99:like
                    </findQualifier>
                </findQualifiers>
                <categoryBag>
                    <keyedReference
                        tModeKey="uddi:uddi.org:ubr:taxonomy:naics"
                        keyName="Motor Vehicle Parts"
                        keyValue="42112_"/>
                </categoryBag>
            </find_service>
        </subscriptionFilter>
        <bindingKey>
            bindingKeyOfTheClientsNotifySubscriptionListenerService
        </bindingKey>
        <notificationInterval>P5D</notificationInterval>
        <maxEntities>1000</maxEntities>
        <expiresAfter>20030101T00:00:00</expiresAfter>
    </subscription>
    <keyBag>
        <deleted>false</deleted>
        <serviceKey>matchingKey1</serviceKey>
        <serviceKey>matchingKey2</serviceKey>
        <serviceKey>matchingKey3</serviceKey>
        <serviceKey>matchingKey4</serviceKey>
    </keyBag>
</subscriptionResultsList>

(Source: http://uddi.org/pubs/uddi-v3.0.2-20041019.htm)

To support the subscription API, JEUS UDDI client provides the following methods in the jeus.uddi.v3.client.UDDIClient class.

public subscriptions save_subscription(
    String authInfo, Subscription subscription)
public void delete_subscription(
    String authInfo, String subscriptionKey)
public Subscriptions get_subscriptions(String authInfo)
public SubscriptionResultsList get_subscriptionResults(
    String authInfo, String subscriptionKey,
    CoveragePeriod coveragePeriod, String chunkToken)

Subscription client programming is basically the same as the existing JEUS UDDI client programming. A subscription filter condition must be as restrictive as possible.

The following is an example of a simple JEUS UDDI subscription client program.

UDDIClient client;
. . .

AuthToken authToken = client.get_authToken(user, password);

// Make a subscription
Subscription subscription = new Subscription();

// Make a subscriptionFilter
FindBusiness findBusiness = new FindBusiness();
findBusiness.addName(new Name("biz"));
subscription.setSubscriptionFilter(
new SubscriptionFilter(findBusiness));

// execute save_subscription request
Subscriptions subscriptions = client.save_subscription(
    authToken.getAuthInfoString(), subscription);

Subscription savedSubscription = subscriptions.getSubscription(0);
String subscriptionKey =
    savedSubscription.getSubscriptionKeyString();
. . .

A subscription key, which is obtained from the registered subscription, is used to delete the subscription by using the 'delete_subscription' API, or to get result of a synchronous request by using the 'get_subscriptionResults' API. The 'get_subscriptions' API is used to search for all subscriptions that are registered by the subscriber.

When the subscriber registers a subscription, the 'brief' attribute must be set to 'true' if the subscriber wants the registered subscription result to only use an entity key.

. . .
// Make a Subscription
Subscription subscription = new Subscription();
Subscription.setBrief(true);
. . .

If the subscriber wants to receive an asynchronous notification, the <bindingKey> element for the subscription listener must be configured in the subscription as well as the notification interval. The notification interval is defined in the XML schema as the xsd:duration type with the format 'PnYnMnDTnHnMnS'.

. . .
// Make a Subscription
Subscription subscription = new Subscription();
subscription.setBindingKey(
    bindingKeyOfTheClientsNotifySubscriptionListenerService);
subscription.setNotificationInterval("P5D");
. . .

This section describes how to use the UDDI WSDL publishing.

This section describes the wsdl2uddi tool provided by JEUS, and how to use it to publish WSDL to UDDI.

wsdl2uddi

JEUS UDDI WSDL Publishing provides the wsdl2uddi tool that automates such mapping. To use the tool, execute the following command in the console.

$ wsdl2uddi

The following describes how to use the tool.

Usage: wsdl2uddi UDDIVersion WSDLURI [wsdl-options] -uddiInquiry
UDDIInquiryURI -uddiPublish UDDIPublish -uddiUsername UDDIUsername
-uddiPassword UDDIPassword [options]

* wsdl-options
    -wsdlUsername                username to access the WSDL-URI
    -wsdlPassword                password to access the WSDL-URI

* options
    -level LEVEL                 specify log level.
                                 LEVEL : SEVERE, WARNING, INFO, FINE, FINER, FINEST
    -verbose                     same as -level FINE

The following describes each parameter.

ParameterDescription
UDDIVersion (compulsory)one of v2 or v3.
WSDLURI (compulsory)URI of the actual WSDL.
wsdl-optionsUsed to set the username and password when accessing a security configured WSDL.
UDDIInquiryURI (compulsory)Inquiry URI of the actual UDDI.
UDDIPublishURI (compulsory)Publish URI value of the actual UDDI.
UDDIUsername (compulsory)Username required to access the UDDI.
UDDIPassword (compulsory)Password required to access the UDDI.
optionsUsed to specify a log level.

Publishing a random WSDL to UDDI

The wsdl2uddi command line tool is used to publish a WSDL to UDDI.

$ wsdl2uddi v2 BasicAuthServiceTestService.wsdl -uddiInquiry
http://localhost:8088/uddi/inquiry -uddiPublish
http://localhost:8088/uddi/publish -uddiUsername jeus -uddiPassword jeus
[2006.12.12 17:22:47][2][] [client-10] [WSVC-5240] Analyzing WSDL :
BasicAuthServiceTestService.wsdl

When the previous command is executed, the wsdl2uddi tool automatically interprets the WSDL and publishes it to UDDI according to an appropriate binding rule.

The following is the published WSDL shown in UDDI.