UDDI: Universal Description, Discovery, and Integration, Part 3

This excerpt from O'Reilly's Java Web Services focuses on UDDI programming with the Java API for XML Registries (JAXR).

Using JAXR

Now that we've looked at a simple SOAP client to build a request by hand, and a client that uses a UDDI API to build a request with slightly higher-level tools, let's proceed to the next level of abstraction: the Java API for XML Registries (JAXR). JAXR is a uniform approach to accessing a registry that advertises business information and services in XML. JAXR attempts to provide a single API that can access many different kinds of registries, including ISO 11179, OASIS, eCo Framework, ebXML, and UDDI (although the reference implementation can access only a UDDI registry).

The JAXR reference implementation is unique because it requires Tomcat for the client implementation! This requirement is somewhat odd, but fortunately, it is only a characteristic of the reference implementation. The provider implementations created by vendors will probably be simple libraries that don't require an external server such as Tomcat. You can get JAXR and Systinet WASP UDDI Standard to use the same Tomcat installation; details on how to accomplish this installation are in this chapter's README.txt file. When installing and configuring JAXR on your machine, make sure that the .jaxr.properties file included with this chapter's examples is placed in your home directory. On a Unix system, this directory is the ~/ directory; on NT or Windows 2000, the home directory is given by the value of the %USERPROFILE% environment variable. To run the program to search for Demi Credit using JAXR, use this command:

Since you should now have a better understanding of how these UDDI queries work, this example provides a more thorough parsing of the response message. This program provides a formatted output, rather than simply dumping an XML document to the screen. The code for this client is in the file JAXRFindBusiness.java. Here is the source code in its entirety:

JAXR uses javax.xml.registry for the base package name for all of its classes. The main( ) method for this program parses a single parameter, which is the query string to use as the business name in the request:

Most work for this program takes place in the doQuery( ) method. A client program first needs to create a connection to the service provider. In our case, the service provider is our local UDDI registry running at http://localhost:8080/wasp/uddi/inquiry/. To create the connection, we create a Properties object and fill it with relevant information: the javax.xml.registry.queryManagerURL value should be the URL of the UDDI registry that you are accessing, while the javax.xml.registry.factoryClass is the class that implements a ConnectionFactory object. Different JAXR providers provide different values for this property; the JAXR reference implementation uses com.sun.xml.registry.uddi.ConnectionFactoryImpl. Finally, the client code creates an instance of the ConnectionFactory class, associates the properties with this class, and then creates a Connection object using the createConnection( ) method:

Once we have a connection to a service provider, we need to connect to a RegistryService object. Since different registries support different types of services, a RegistryService object tells your program exactly which services the registry supports. For example, some registries allow declarative SQL queries (UDDI does not). The RegistryService interface has methods for telling a program the registry's capabilities and returning manager objects that support a particular type of capability. For business requests, such as the requests that UDDI supports, the BusinessQueryManager interface must be used. To retrieve a reference to a BusinessQueryManager object, call the getBusinessQueryManager( ) method on a RegistryService object:

The BusinessQueryManager interface has a series of findXXX( ) methods that perform different types of queries. Different methods query for different items; for example, the findOrganizations( ) method queries a registry for business information, while the findServices( ) method asks for different services that may or may not be available. Most methods take one or more Collection objects as input; these objects refine the query using qualifiers. The first parameter of the findOrganizations( ) method takes a Collection of find qualifiers that refines how the query should be performed. Find qualifiers can apply a sort or restrict the number of entries that are returned; in this case, we ask that the responses be sorted by name. The second parameter of the findOrganizations( ) takes a Collection of name patterns to apply to the search. To populate this Collection, we add the business name that we read from the command line. The other parameters (all set to null in this example) take qualifiers that search for businesses based upon classifications, specifications supported, external identifiers, and external URLs, respectively. The query returns a BulkResponse object that can be checked for exceptions from the server or converted to a Collection:

The rest of the program is responsible for iterating through the output and formatting it for display on the screen. It's a bit wordy, so it's not included again here. A client application would use the information retrieved from the query to perform other queries or to leverage a particular service.

As you undoubtedly noticed, the JAXR API is more complicated than the Systinet API. JAXR does not have class representations for each UDDI XML structure; instead, we have to work with query managers and lists of various qualifiers. Working with the Systinet API is convenient because every class has an XML counterpart with the same name. You pay a price for abstraction, though: the Systenet client is tied to UDDI, while the JAXR client could conceivably make a similar request from a different kind of registry with little or no modification.

Getting More Detail

find_ messages are designed to return basic information about the structures that a UDDI registry manages. Given the UUID to one of the major data structures, you can drill down into the registry to get a full listing of the details stored in that structure. The UDDI inquiry API provides a series of messages that begin with get_ for retrieving information from the registry. Table 6-3 lists these messages.

Given one or more UUIDs of different <bindingTemplate> documents, this message returns a <bindingDetail> structure containing the complete <bindingTemplate> document for each matching UUID. The specification recommends that a client application caches <bindingTemplate> documents locally so repeated calls to a web service do not require a query on the UDDI server each time. If a call based on cached <bindingDetail> information fails, a new <bindingDetail> structure can be retrieved using this message.

<get_businessDetail>

<businessDetail>

Given one or more UUIDs of different <businessEntity> documents, this message retrieves a <businessDetail> structure that contains <businessEntity> documents for each matching UUID.

<get_serviceDetail>

<serviceDetail>

Given one or more UUIDs of different <businessService> documents, this message returns a <serviceDetail> structure that contains the complete <businessService> document for each matching UUID.

<get_tModelDetail>

<tModelDetail>

Given one or more UUIDs of different <tModel> documents, this message returns a <tModelDetail> structure containing the complete <tModel> document for each matching UUID.

All of these messages are fairly straightforward. As long as you can get a valid UUID for the data structure you are interested in, you can get its details. In the <find_business> example for Demi Credit, the response document indicated that Demi Credit had published a web service named DCAmail with the UUID 860eca90-c16d-11d5-85ad-801eef208714. Let's send a <get_serviceDetail> message to get all of the information about this web service. To get this information, we'll use the UDDISoapClient program from our previous examples to send a handwritten XML document. This document contains a <get_serviceDetail> message using the UUID for the DCAmail web service. Here's a listing of Ch6_GetServiceDetail.xml:

The <get_serviceDetail> message doesn't have any optional attributes; it has only one subelement, <serviceKey>, which is the UUID of the web service for which you want more detail. The <get_serviceDetail> message can accept one or more <serviceKey> subelements on which to query. Here is the response document returned by the UDDI server:

This document contains a <businessService> structure, which is a logical grouping of web services by a business. In the case of Demi Credit, this grouping lists a number of web services that allow you to do a credit check via email. The returned <businessService> has a single <bindingTemplate> that provides technical details of how to access the web service. The <accessPoint> is the web service endpoint URL. In this case, it is a simple email address: mailto:DCAmail@democredit.bar.

More importantly, the <bindingTemplate> has two <tModelInstanceInfo> documents that show where to find more information about how this web service runs and the specifications it supports. Each <tModelInstanceInfo> document contains a tModelKey attribute, which is the UUID of a <tModel> structure that contains a particular specification's metadata. The <tModelInstanceInfo> document also contains an <instanceDetails> subelement that contains a description of how to use the web service.

Categorization

Categorization of data was an important requirement during the development of UDDI. Categorization allows data in a UDDI registry to be associated with an industry, product, or geographic code set. Some obvious problems come with the use of categories; they should be familiar to anyone who's ever searched for something on the Web. Broad categories, such as manufacturing, can return thousands of matching services and businesses--certainly too many to sift through manually. On the other hand, specific categories, such as "manufacturing in Buffalo," might be too specific to return any results.

It's probably not realistic to expect software to dynamically discover and use new businesses on the fly in the near future. Realistically, human analysts need to browse a UDDI portal that allows customized searches and queries to discover the businesses they are interested in working with. It's more likely that software will contain the logic necessary to locate and integrate with web services for companies that have been predetermined. It's also likely that businesses will set up private UDDI registries that they can share with their approved partners to facilitate B2B integration.

Many categorization systems can be used on data within UDDI. These systems are summarized in Table 6-4. Each taxonomy categorization is registered as a <tModel> structure within UDDI. This registration means that each categorization has a tModel name and UUID that can be used to reference it. The tModel name is the same in all UDDI registries, but the UUID for the tModel may change between operator nodes.

The North American Industry Classification system. Hundreds of classifications are in this system, including "Pet supply stores," "Hazardous waste collection," and "Diet and weight reducing centers." More information can be found at http://www.census.gov/epcd/www/naics.html.

UNSPSC

unspsc-org:unspsc:3-1

The Universal Standard Products and Services Classification. It is the first system to classify products and services for worldwide use. More information can be found at http://www.unspsc.org.

General-purpose associations that a business might want to make. This taxonomy allows operator nodes to promote invalid entries or entries that would otherwise be rejected by another classification system. There is no specification on how this works; it is operator-node specific.

A <categoryBag> structure contains zero or more <keyedReference> structures. Each <keyedReference> structure contains the name and value of a category to which the data element belongs. In the previous <businessService> example, the <categoryBag> had eight <keyedReference> subelements. Three <keyedReference> subelements were for NAICS categorizations; the other five were for ISO 3166 country categorizations.

Determining which categorization a <keyedReference> belongs to can be difficult, but more details can be discovered by looking up the <tModel> document, using the tModelKey attribute that is also part of a <keyedReference>. If you look at the <categoryBag>, you will notice that three of the <keyedReference> elements have the same tModelKey value and the other five attributes have a different tModelKey value. For example, here is one of the ISO 3166 country categorization <keyedReference> elements returned as part of the <categoryBag>:

The keyName value identifies the categorization. It is also a textual name given to the categorization. The keyValue is the categorization code, as identified by the specification. The categorization code is guaranteed to be unique. The tModelKey value is the UUID of a <tModel> document that provides metadata of the specification that this categorization supports.