Table of Contents
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.
-
Business entity (businessEntity)
Represents the business or organization that provides the web service. It includes the web service provider's company name, contact detail, and other business information. Identifiers for the business, such as Dun & Bradstreet D-U-N-S® Number, are also included.
-
Business service (businessService)
Represents a group of web services provided by a business entity. It is a logical child of one business entity.
-
Service binding (bindingTemplate)
Describes a technical model needed for using a particular web service. The entity also provides service related binding information and references for technical specification implemented by the service. It also provides various files and pointers to URL based discovery mechanism.
-
Represents a technical model for reusable concepts, including web service type, protocol used by the web service, and classification system. The model includes all types of concepts such as standards exchanged between businesses and web service interface definitions. If a WSDL document was described by implementing a new web service, the WSDL definitions are saved in the technical model.
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.
JEUS UDDI server requires a relational database for data persistence. It supports any relational database that supports ANSI standard SQL.
JEUS UDDI DataStore uses JDBC, and the configuration is very simple.
First, create a new UDDI database by using the database script provided with the JEUS UDDI server package (Database script is located under the 'JEUS_HOME/lib/systemapps/uddi/conf' directory). In order to configure the DataStore, uddiDB datasource must be configured on JEUS server.
Refer to the sample configuration file under the 'JEUS_HOME/lib/systemapps/uddi/conf' directory for more information.
Once UDDI database has been successfully configured, JEUS UDDI server must be deployed.
JEUS UDDI server EAR package is created under the 'JEUS_HOME/lib/systemapps/uddi' directory upon the installation of JEUS server (jeusuddi_v2c.ear and jeusuddi_v3c.ear). Deploying JEUS UDDI server is similar to deploying other EAR applications. In the following example, it is assumed that the UDDI is deployed under a context named 'uddi.'
[Example 19.1] <<jeus-web-dd.xml>>
<jeus-web-dd>
<res-ref>
<jndi-info>
<ref-name>jdbc/uddiDB</ref-name>
<export-name>UDDIDB</export-name>
</jndi-info>
</res-ref>
</jeus-web-dd>
[Example 19.2] <<web.xml>>
<web-app>
. . .
<resource-ref>
<res-ref-name>jdbc/uddiDB</res-ref-name>
. . .
</resource-ref>
</web-app>
The default datasource name for JNDI datasource is
'jdbc/uddiDB'. The export-name, configured on the server, that is used
to connect to the database is 'UDDIDB'. Modify the name in the
configuration file to use a different name.
Configure the JEUS UDDI server in the 'uddi.properties' file. The file is located under the 'JEUS_HOME\lib\application' directory. If this file does not exist, it is automatically created during deployment.
The following is a description of the properties in the 'uddi.properties' file.
[Table 19.1] uddi.properties
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.
-
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; } } -
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 "19.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');[Table 19.2] Columns in PUBLISHER table
Column Name Description PUBLISHER_ID Used for publisher authentication. (This value must be identical to the one used for external authentication). PUBLISHER_NAME Name of the Publisher (or a registered name in UDDI). ADMIN Option to grant administrator access rights to the publisher (true or false).
Start up JEUS Server. The following is the format of the JEUS UDDI server URL.
http://hostname:port/context/
By default, the context path of the JEUS UDDI server is '/uddi.' Assuming that the port number of the JEUS HTTP Listener is set to 8088, the URL becomes the following.
http://localhost:8088/uddi/
The following page is displayed when the previous URL is accessed through a browser.
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.
Any Business, Service, and Technical Model can be searched in the JEUS UDDI Explorer by using the UDDI Search.
Select a UDDI Registry operator by using UDDI Registry, and then select an entity type in the 'Search For a' section. After selecting a UDDI Registry and entity type(Business, Service, or Technical Model), enter any search word in the Name text field (‘%’ is used as a wildcard). The filters, 'exact name' or 'case sensitive', can be used for the search.
After entering the name, click on [submit] to start searching. The selected UDDI Registry shows a list of businesses, services, or technical models that start with the specified name.
JEUS UDDI Explorer displays the details of the searched entities as in the following.
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.
-
Click on [Add Provider] on the RegisteredInfo screen. The next screen, called 'Provider', displays the newly added business called 'New Provider'. On this screen, click [Edit] to modify various information about the Provider including the name.
Enter "JEUS Web Services" in the Name field, and click [Update].
-
On the [Detail], [Contact], [Identifier], [Category] and[Discovery URL] tabs of the 'Provider' screen, additional information, such as business description, User contact, Discovery URL, category, etc., can be configured. Enter "eBiz using Webservices” in the 'Description' field.
Adding a service
Service is added in the following order.
-
Click on [Add Service] from the [Service] tab of the 'Provider' screen. Since a service is always linked to a business, a service linked to the business is generated by clicking [Add Service], and then the 'Service' screen appears.
-
As for the 'Provider' screen, each tab on the 'Service' screen enables the user to modify and view various information.
Adding a tModel
The following are the steps for adding a tModel.
-
Go back to the 'RegisteredInfo' screen, and click [Add TModel]. The TModel screen appears and displays the newly added technical model with the default name of 'New TModel'.
-
On the TModel screen, additional information, including a description of the technical model, overview URL, category, and identifier, can be entered. Enter "tModel for eBiz” in the Name field.
-
Go to the [Overview Document] tab on the TModel screen, and click [Add OverviewDoc]. The screen shows the Overview Doc information of the technical model.
Enter "http://localhost:8088/ws/tmodel.wsdl" in the OverviewURL field.
-
Click [Add], and save it as a technical model.
Adding a bindingTemplate
The following are the steps for adding a bindingTemplate.
-
Click [+] on any business from the left menu tree. Click on a service of the business to display the service details on the right panel.
-
To add a bindingTemplate, click [Add Binding] from the 'Binding' tab to go to the binding screen.
-
The access point address can be modified from the [Detail] tab of the binding screen. Enter "http://localhost:8088/uddi" in the Address field.
-
Go to the 'Instance Info' tab and click [Add Instance Info]. Click [Search] to go to the screen where a user can search for opened tModels. On the search screen, enter the full name of the tModel or the first part of the name in the 'Search for TModel Names Containing' field. Enter "tModel" in the field.
-
After selecting tModel for eBiz from the left menu tree, click [Add Instance Info] to save the binding Template.
JEUS UDDI Explorer is used to register a user for the JEUS UDDI registry.
First, log on as an administrator, and click 'User' from the menu. JEUS UDDI Explorer will show the following screen. On the screen, the administrator can add a new user, and modify or delete user information.
click [Add User] to go to the screen for registering a new user.
A 'Username' and 'Fullname' fields are required. The 'Username' is the user ID used to log into JEUS UDDI Explorer and to publish UDDI Data. After entering the required values, click [Add] to complete the user registration.
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()); }
To compile a UDDI client source code, first go to the directory of the client source file. Execute the following command in the 'JEUS_HOME/samples/webservice/uddi/client' directory.
JEUS_HOME/samples/webservice/uddi/client$ ant build
To execute a UDDI client, go to the directory of the client source code.
In this example, the following command is executed in the 'JEUS_HOME/samples/webservice/uddi/client' directory.
JEUS_HOME/samples/webservice/uddi/client$ ant
The result is displayed in the following format.
##### Running FindBusinessSample ##### Found Business name: test_Biz ##### Done #####
This section describes the concept of XML digital signature and verification method.
A big improvement in UDDI v3 specification is the support for digital signature. Digitally signing a UDDI entity ensures data integrity and authenticity through UDDI. An inquirer of a UDDI registry can modify the query to request for only signed data. Also, when verifying data from the UDDI registry, this guarantees that the data is exactly as intended by the publisher.
The publisher of the UDDI registry can be sure that the data will not be transmitted by the wrong person who claims to have the UDDI entity. In addition, data integrity is guaranteed if the publisher has the signed data.
Digital signature improves UDDI data quality, and allows data protection and non-repudiation that are required for high reliability in the web service environment.
UDDI v3 specification supports XML digital signature for the following higher level UDDI entities by using XML signature syntax and processing method (http://www.w3.org/TR/xmldsig-core/).
-
businessEntity
-
businessService
-
bindingTemplate
-
tModel
-
publisherAssertion
UDDI v3 specification defines XML signature and verification as the role of the client. Accordingly, JEUS environment supports client-side XML signature and verification, and it is assumed that the UDDI client described in this document is JEUS UDDI client.
Note
For more information about XML digital signature, refer to "Appendix I, Support For Digital Signatures" in the UDDI v3 specification.
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.
| API | element |
|---|---|
| save_business | businessEntity |
| save_service | businessService |
| save_binding | bindingTemplate |
| save_tModel | tModel |
| 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 "19.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.
XML signature verification is performed for the high level elements that are returned from the inquiry API call.
The following elements are used for each API invocation.
| API | element |
|---|---|
| get_businessDetail | businessEntity |
| get_serviceDetail | businessService |
| get_bindingDetail | bindingTemplate |
| get_tModelDetail | tModel |
| find-relatedBusinesses API | publisherAssertion |
Typically, a UDDI registry does not perform client-side signature verification.
JEUS UDDI client does not provide a separate method for signature verification. Signature verification is automatically performed when a response to the inquiry API call includes a signature element. If the signature is invalid, the java.sercurity.SignatureException is thrown.
This section describes the concept, creation, and client programming of UDDI subscriptions, and how to set UDDI server to receive e-mails.
New subscription API of UDDI v3 specification supports a notification function in a synchronous or asynchronous method.
Subscription API provides a method to track a UDDI registry. Using the method, a subscriber can establish a subscription based on a special query or entity of interest. Based on the subscription, modifications made to the UDDI registry can be tracked through a synchronous query for UDDI information or an asynchronous notification received by the subscriber from the registry.
UDDI subscription is useful in the following cases:
-
Notification about a new business or service that is registered in UDDI registry.
-
Detecting changes to the existing business or service.
Creating a subscription and monitoring the result requires the following steps.
-
A service must be created to receive an asynchronous notification from a UDDI registry. (This step can be skipped if a subscriber only uses a synchronous query.) The subscriber can choose to get a subscription result either through e-mail or through HTTP/SOAP web service implemented by the subscriber.
-
Select a filter condition for using the subscription. More restrictive condition should be selected to facilitate the analysis of the results. In general, a subscriber must ensure that the subscriptionFilter condition is as restrictive as possible.
-
Save the subscription query by using the ‘save_subscription’ API.
-
If needed, process the notification through HTTP/SOAP protocol or e-mail.
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.
-
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> -
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>
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>
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"); . . .
The mail server configuration is required for JEUS UDDI server to notify the subscription result to a subscriber via e-mail. The setting is specified in the 'uddi. properties' configuration file on the JEUS UDDI server.
. . . uddi.subscription.mail.smtp.host=... uddi.subscription.mail.smtp.port=... uddi.subscription.mail.smtp.from=... . . .
This section describes how to use the UDDI WSDL publishing.
OASIS, an organization that drives the e-business standard, is working on some technical Notes related to UDDI v2 and v3 specifications and others. One of them is on UDDI WSDL Publishing (Using WSDL in a UDDI Registry, Version 2.0.2).
WSDL can supplement the UDDI standards by providing abstract interfaces and protocol binding of any network services. The document, "Using WSDL in a UDDI Registry" from OASIS, introduces a recommended approach for mapping WSDL descriptions to UDDI data structures.
For more information, refer to OASIS TC Using WSDL in a UDDI Registry, Version 2.0.2.
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.
| Parameter | Description |
|---|---|
| UDDIVersion (compulsory) | one of v2 or v3. |
| WSDLURI (compulsory) | URI of the actual WSDL. |
| wsdl-options | Used 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. |
| options | Used 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.
