Accessing Information in a UDDI Registry

In this section, you will examine how information in a UDDI registry can be accessed from Java.

As a Java developer, you do not really want to have to build SOAP messages to communicate with a UDDI registry. What you want is a Java-based API that hides away the SOAP manipulation. In the rest of this section on registries, you will examine three alternatives:

• UDDI4J— IBM's Java implementation of the UDDI API

• IBM WSTK Client API— A higher-level API that abstracts some of the UDDI complexity

• JAXR— The Java API for XML Registries being developed through the JCP

Manipulating Service Information using UDDI4J

Before you start manipulating data in a registry, you must choose which registry you will use:

• A public production registry— This is a “live” business registry, such as those hosted by IBM and Microsoft. You should only manipulate “real” business data in these registries. You can search such a registry freely, but if you want to publish data, you will be required to obtain a login and password.

• A public test registry— This is a generally available resource for testing the registration and discovery of Web Services. As with production registries, public test registries are hosted by IBM and Microsoft. If you want to publish data about your test services, you will be required to obtain a login and password.

• A locally hosted registry— There are several UDDI registries available that you can configure in your own environment (IBM's downloadable UDDI registry and jUDDI are two examples). These registries can be used internally within your company for Web Service discovery and testing.

Listing 21.1 shows how UDDI4J can be used to register a business in the IBM test registry.

Listing 21.1. RegisterBusiness.java—A Simple UDDI Client

 1: import com.ibm.uddi.*;
 2: import com.ibm.uddi.datatype.business.*;
 3: import com.ibm.uddi.response.*;
 4: import com.ibm.uddi.client.*;
 5: import org.w3c.dom.*;
 6: import java.util.*;
 7: import java.security.*;
 8:
 9: public class RegisterBusiness
10: {
11:   public static void main (String args[])
12:   {
13:     System.setProperty("java.protocol.handler.pkgs",
14:                        "com.ibm.net.ssl.internal.www.protocol");
15:     Security.addProvider(new com.ibm.jsse.JSSEProvider());
16:
17:     UDDIProxy proxy = new UDDIProxy();
18:
19:     try
20:     {
21:       proxy.setInquiryURL(
22:           "http://www-3.ibm.com/services/uddi/testregistry/inquiryapi");
23:       proxy.setPublishURL(https://www-3.ibm.com/services/uddi/ +
24:                                "testregistry/protect/publishapi");
25:
26:       AuthToken token = proxy.get_authToken("fbloggs", "Wibble" );
27:
28:       System.out.println("Authentication Token: " + token.getAuthInfoString());
29:
30:       Vector businessEntities = new Vector();
31:
32:       BusinessEntity businessEntity = new BusinessEntity("", "Bloggs Business");
33:       businessEntities.addElement(businessEntity);
34:
35:       BusinessDetail detail =
36:                  proxy.save_business(token.getAuthInfoString(),entities);
37:
38:       businessEntities = detail.getBusinessEntityVector();
39:       BusinessEntity returnedBusinessEntity = (BusinessEntity)(businessEntities
.elementAt(0));
40:
41:       System.out.println("List businesses starting with B to find ours");
42:
43:       BusinessList list = proxy.find_business("B", null, 0);
44:
45:       Vector businessInfoVector  = list.getBusinessInfos().getBusinessInfoVector();
46:       for (int i = 0; i < businessInfoVector.size(); i++)
47:       {
48:         BusinessInfo businessInfo = (BusinessInfo)businessInfoVector.elementAt(i);
49:         System.out.println(businessInfo.getNameString());
50:       }
51:     }
52:     catch (UDDIException ex)
53:     {
54:       DispositionReport report = ex.getDispositionReport();
55:       if (report != null)
56:       {
57:         System.out.println("UDDIException" +
58:                            "
 faultCode:" + ex.getFaultCode() +
59:                            "
 operator:" + report.getOperator() +
60:                            "
 generic:"  + report.getGeneric() +
61:                            "
 errno:"    + report.getErrno() +
62:                            "
 errCode:"  + report.getErrCode() +
63:                            "
 errInfoText:" + report.getErrInfoText());
64:       }
65:       ex.printStackTrace();
66:     }
67:     catch (Exception ex)
68:     {
69:       ex.printStackTrace();
70:     }
71:   }
72: }
						

There is no intention to walk through the precise details of the code here. However, you should note the following:

• The UDDI4J API provides a UDDIProxy class that acts as a client-side proxy for the UDDI registry. An instance is created on line 17.

• Before using any UDDI-based applications, you must ensure that you have a valid username and password for the registry in question. These are used on line 26 to obtain an authentication token that is passed in subsequent calls to identify this user.

• Because you will need to send your login name and password to authenticate yourself to a public registry, these registries require the use of HTTPS for this purpose. Lines 21–24 show the URLs for inquiries and updates being set on the UDDI proxy. The URL for updates (publish) uses an https:// protocol identifier. To use this type of URL from a standalone client such as the one shown, you must use the Java Secure Sockets Extension (JSSE). If you are using a pre-JDK 1.4 platform, you will have to download and install this extension. The application shown uses the IBM version of JSSE and initialises it on lines 13–15.

After it has contacted the UDDI registry, the application creates a (very sparse) business entity and publishes this to the registry. It then lists all of the businesses beginning with B to ensure that the update has taken place correctly.

Although at this stage the application is not too complex, the act of retrieving or publishing information can be somewhat tortuous. This is particularly true in the area of service definitions. Consider the situation where you want to publish the WSDL description of your service. To do this, you must convert that service description into a UDDI tModel. The UDDI data structure corresponding to the tModel must be created as an XML document, and this document must then be uploaded to the registry. Even if you like creating XML documents, there is still the issue of retrieving the relevant parts of the service description from your WSDL to import this into the tModel document. Although there is another IBM API, called WSDL4J, that can help you to perform this manipulation, things are becoming fairly messy by now.

Manipulating Service Information Using the IBM WSTK Client API

Because of the complexity associated with using UDDI4J, you may decide to use the IBM WSTK Client API that provides a higher-level abstraction of the UDDI4J API. The WSTK Client API also uses the WSDL4J API to help convert WSDL document information into UDDI tModel and service binding information.

The WSTK Client API is centred around the ServiceRegistryProxy class, which is an equivalent to the UDDIProxy. One way of creating a new ServiceRegistryProxy is shown in the following:

ServiceRegistryProxy proxy = new ServiceRegistryProxy (inquiryURL, publishURL, userName,
 password);

As you can see, the initial code to use a ServiceRegistryProxy instance is little different from that to use a UDDIProxy in that you must provide it with URLs for inquiry and publication, credentials to access the registry, and so forth. However, after the proxy has been initialized, you need essentially only deal with four Java types—service provider, service definition, service implementation, and service interface.

The ServiceProvider class represents the business information in your UDDI registry entry. This is a wrapper for the UDDI businessEntity information. You will build a ServiceProvider object to represent your organization when publishing information, or you will manipulate ServiceProvider objects when retrieving business information from the registry.

The ServiceDefinition class wraps the UDDI businessService structure and provides a way to obtain the interface and location information for the service. The ServiceImplementation wraps the UDDI bindingTemplate and allows you to retrieve the endpoint information for a service. The ServiceInterface class represents the UDDI tModel for the service. For both the ServiceImplementation and the ServiceInterface, a WSDL filename can be passed to the constructor and all of the manipulation of the WSDL document is done for you. This greatly simplifies the creation of service information.

Retrieving and Using Service Information

So far, you have mainly considered the creation of your own business and service information to be registered in the UDDI registry. However, you may also want to use other peoples' services within your application. To do this, you must search the registry and use the information you retrieve.

Regardless of which registry API you use, you will follow the white/yellow/green page model of searching. As an example, the ServiceRegistryProxy provides many finder methods, similar to those on an EJB home interface. The finders allow you to specify various facts to help find the required information, such as names, categories, ownership, service definitions, and interface definitions. The information you provide to the finder will depend on what you know already and what type of information you want to get back. The finders will return ServiceProvider, ServiceDefinition, and ServiceInterface objects either singly or in arrays. From these objects, you can find out all you want to know about the service you have found.

The next question is what you do with the service information when you have it. You will probably be retrieving information in one of three scenarios:

• You have an application that uses pre-defined Web Service interfaces. At runtime it will use UDDI to retrieve services that implement that interface and choose the most suitable implementation to use.

• Your application or component forms part of an application creation framework. It will retrieve service information using UDDI and offer the choices to the application builder (think of your typical Java IDE).

• Your application will retrieve service information and dynamically invoke the methods it finds. In this case, the application has no fixed binding to any particular service interface. This is the most complex form of interaction, requiring more coding to invoke the services dynamically and more intelligence to make the right choice about the correct operations and parameters.

As time goes on, standards and tools should make the creation of UDDI-based applications easier. One such standard is the Java API for XML Registries (JAXR) being developed through the Java Community Process.