Searching for this schema is left as the proverbial "exercise for the reader." At this stage, you should have an idea of the complexity of UDDI data structures and their navigation. An entire book could be dedicated to exploring every facet of the UDDI Programmers API. The rest of this chapter focuses on how to interact with UDDI and presents Java clients that demystify some of the complexity in the UDDI API and its data structures.

Finding a Business

Now it's finally time to pull everything that we have talked about together into a program. The examples in this chapter use Systinet WASP UDDI Standard. We selected this software because it is robust and free for development purposes. It includes:

Database scripts for using Oracle, PostgreSQL, Cloudscape, Microsoft SQL Server, IBM DB2, and Sybase as the persistent store for the local UDDI registry

A Java-based UDDI client API

Sample code that illustrates how to use its custom client API in Java

We use Systinet WASP UDDI Standard primarily for its local registry, which allows you to run a registry locally on your computer for testing and development. We won't focus on the client API. Since a UDDI server accepts standard SOAP messages, we can use any Java-based SOAP client API to create the appropriate messages and direct them to a valid UDDI registry.

Our first UDDI client retrieves basic business information for a fictitious company called Demi Credit. The Systinet WASP UDDI registry comes with a preconfigured entry for Demi Credit. This example uses the Apache SOAP client library to create an appropriate SOAP message that has a <find_business> document as its body. We won't create this document programmatically, which would be an exercise in the use of the DOM or JDOM APIs; instead, we'll take the body for our SOAP request message from the file Ch6_FindBusiness.xml:

The <uddi:find_business> tag indicates that this element is named find_business and defined in the uddi namespace. The contents of the tag must adhere to the schema for find_business, which defines a couple of different attributes. The generic attribute indicates the UDDI API version that is used (Version 2.0, in this case). maxRows indicates how many matching <businessInfo> structures should be returned if the query matches more than one company.

Optional Attributes and Elements

All UDDI API messages have several optional attributes and elements. For example, the maxRows attribute of the <find_business> element is optional. If this attribute is not included, the response message will contain an unbounded list of every match that could be found (up to the point where the UDDI server truncates a response).

In fact, the <name> subelement of <find_business> is optional as well. You can search for companies in other ways (besides using their name). You can search by category (through the <categoryBag> element), identifier (through the <identifierBag> element), or a particular specification that one of their web services implements (through the <tModelBag> element). Categories and identifiers are discussed in more detail later in this chapter.

This <find_business> element has a single subelement, <name>, which is the meat of our request. The value of the <name> element is a simple regular expression used to search the names of different businesses. The percentage sign (%) can be used for wildcard matching. In this example, we know the name of the company we are searching for: Demi Credit.

Before looking at the code for the client, let's run it and observe its behavior. The client reads an XML file, wraps it in a SOAP envelope, and sends it to a URL destination, adding various UDDI and Systinet namespace declarations that are required to make the SOAP message comply to the UDDI specification. The destination is the URL of an endpoint configured to accept UDDI inquiry messages. Run the command:

This output is saved as Ch6_FindBusiness_OUTPUT.xml and is included with the examples provided for this chapter. Other examples that use this program have their response documents saved in the same format.

Let's pick apart the response to see what it contains. The UDDI Server returned a single <businessList> structure which, in turn, has a single <businessInfos> structure. The <businessInfos> element can have zero or more <businessInfo> elements, based upon the number of businesses that were matched as part of the query. In this case, the server found only one business matching the name Demi Credit in the UDDI registry.

The <businessInfo> element contains several other important pieces of information. First, the businessKey attribute contains the UUID of Demi Credit. The UUID value is needed to do a more detailed information search or an update using the Publisher's API. Second, the <businessInfo> structure has a <description> that contains a textual description of what the company does. Next, the <businessInfo> structure contains a <serviceInfos> structure that contains a collection of all web services registered by this business. Each web service is described by a single <serviceInfo> structure, which contains the web service's UUID as an attribute.

Now that we've seen what the client does and examined the documents it sends and receives, it is time to look at UDDISoapClient.java in its entirety:

This code is similar to the code presented in the SOAP chapters, with a couple of exceptions. First, Systinet WASP UDDI uses different servlets to implement the inquiry and publisher ports. When Systinet WASP UDDI is first installed, the URL of the inquiry port is http://localhost:8080/wasp/uddi/inquiry. In the program, this URL is assigned to the constant DEFAULT_HOST_URL:

Second, UDDI SOAP messages don't require the use of a SOAP header. Thus, all of the code used to create a SOAP header and fill it with values, such as mustUnderstand, is not needed. Next, UDDI and Systinet WASP UDDI SOAP envelopes require the addition of several different namespaces that they have defined. These namespaces are required at the envelope level of the message, not the SOAP header or body. In the Apache SOAP API, the Envelope interface has a method called declareNamespace( ) that adds these additional namespaces:

WARNING:
Systinet was formally named Idoox. In their documentation, namespaces, and other declarations, you'll often see references to Idoox. When you come across these references, treat them synonymously with Systinet.

Using Systinet's UDDI Java API

The simple SOAP client we've just examined is sufficient to demonstrate a variety of UDDI APIs and data structures. It has some obvious limitations, however:

SOAP envelope complexities such as namespaces have to be coded manually.

SOAP Fault messages that are received have to be handled manually.

The input and output XML documents are weakly typed as XML. A more sophisticated package would have Java interfaces that represent each UDDI data structure, allowing a program to check datatypes at compile time instead of discovering faults at runtime.

To get a feeling for what these limitations mean, we'll implement the same example using Systinet's UDDI Java API. To run this program, compile the file SystinetFindBusiness.java and execute the following command:

java -Dwasp.restrictor.packages=- SystinetFindBusiness

Because of a limitation in the way the Systinet UDDI client library operates, you get a series of array typing error messages if you omit the -Dwasp.restrictor.packages=- environment variable definition. Don't forget to include the hyphen (-) after the equal sign!

The Systinet UDDI client library is spread throughout several different packages. Since the UDDI API and data structures changed from Version 1.0 to Version 2.0 of the specification, Systinet opted to create separate Java packages for each version. This can be problematic for developers, but it is workable. Here are the import statements needed for the current crop of packages:

Within findBusinessByName( ), the program needs to create a <find_business> message and populate it with the search criteria we established. The Systinet UDDI library has a separate class abstraction representing each UDDI XML message. Therefore, to create a <find_business> structure, you merely need to create an instance of their FindBusiness class. The FindBusiness class has several methods that add elements and attributes to the underlying <find_business> structure. In this example, we'll use addName( ), which adds the company name to search for, and setMaxRows( ), which limits the number of matches returned:

// Create a FindBusiness instance.
// This creates a SOAP message.
FindBusiness findBusiness = new FindBusiness( );
// Set the name to use in the query.
findBusiness.addName(new Name(name));
// This will limit the number of returned matches.
// maxRows is an optional attribute.
findBusiness.setMaxRows(new MaxRows("10"));

Next, the program creates a connection to a UDDI server's inquiry port. The UDDILookup class has static methods that create a dynamic Java proxy object that communicates using SOAP. From the developer's point of view, it looks and feels like an RMI stub, except it doesn't communicate over RMI. The UDDILookup.getInquiry( ) method creates an inquiry connection. This program uses the same inquiry port as the UDDISoapClient program, http://localhost:8080/wasp/uddi/inquiry/. An UDDIApiInquiry object is returned and encapsulates an active stub that communicates with the UDDI server:

// This will retrieve a stub to the UDDI inquiry port.
UDDIApiInquiry inquiry =
UDDILookup.getInquiry("http://localhost:8080/wasp/uddi/inquiry/");

Finally, the program needs to send the <find_business> document as part of a SOAP message. The UDDIApiInquiry object has a number of methods that create the SOAP envelope and populate it with an XML structure. A separate method exists for each UDDI XML message in the Programmer's API. For our example, the program calls the find_business( ) method on the UDDIApiInquiry object, passing in the FindBusiness object containing the XML structure.

The Systinet API also has matching classes for the response XML structures. Thus, since a <find_business> request yields a <businessList> response structure, the Systinet API has a BusinessList class. We can traverse this class to get to each subelement and attribute that was returned: