n the first article in this series, you saw how the Universal Description, Discovery, and Integration (UDDI) specification and protocol work together to define messages, application programming interfaces (APIs), and data structures for building distributed registries of Web services. You also saw how to store the business and technical information associated with these services. See the sidebar on this page for a review of UDDI’s high-level architecture.

In this article, you’ll see how to build a client application that uses your UDDI registry to locate businesses and services stored there, how to anticipate and handle some common errors, and how to understand some standard details about UDDI SOAP messages.

The Sample Application
To illustrate how to use UDDI from a client application, this article uses a simple sample application in which you can retrieve an authentication token from the registry and list the businesses stored within it.

Any secured access to a UDDI registry must be executed within the realm of authorized permissions defined by an authentication token. This token is passed back to the registry whenever a secured operation is requested.

The UDDI Authentication Model
When a UDDI registry operation requires a user to authenticate, an authentication token must be obtained from the registry. An authentication token is retrieved using the get_authToken message.

The get_authToken message can operate on against any backend security scheme, such as a directory service, operating system, or a simple table of UserIDs and passwords.

The example in Listing 1 illustrates how the sample application uses the org.apache.juddi classes to obtain an authToken.

The get_authToken SOAP Structures
Each UDDI method call requires that your application be able to send and receive properly formatted SOAP structures in the form of request and response documents. The following XML shows the structures required for the get_authToken SOAP request and response.

   // SOAP Request                                    // SOAP Response                              authentication details               

Finding Businesses and Services
Businesses and their associated services can be searched by issuing inquiry messages to a UDDI registry. There are three types of inquiries which you can execute against a UDDI registry:

1. A white pages inquiry to return basic information such as address, contact, and identifiers about a company and its services.
2. A yellow pages inquiry to retrieve information concerning categorizations and taxonomies.
3. A green pages inquiry to retrieve technical information about the Web services a business publishes, as well as information describing how to execute these services.

The UDDI Inquiry API
The UDDI inquiry API consists of operations that enable you to browse and traverse a registry to obtain information about specific businesses and services. Table 1 shows the inquiry API calls that a UDDI registry must support.

Table 1. The table lists the Inquiry API methods that a UDDI registry must support.

Listing 2 illustrates how the sample application uses the org.apache.juddi classes to find businesses.

The find_business SOAP Structures
Here are the SOAP-request and SOAP-response structures required to find businesses in a UDDI registry.

                                                                                                                                                                                                                                             tModelKey5               tModelKey6                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 

The find_service SOAP Structures
Similarly, here are the SOAP request and response structures you need to find services using the find_service method.

                                                                                                                                                                                       tModelKey3               tModelKey4                                                                                                                                                                                                                                          

Testing the Sample Application
The sample application uses a simple driver class called “Test” to illustrate how to obtain an authentication token and how to search for particular businesses:

   import org.apache.juddi.datatype.response.AuthToken;   import java.util.Enumeration;      public class Test   {      public static void main(String[] args)      {         Test app = new Test();      }         public Test()      {         GetAuthToken getAuthToken = new GetAuthToken();         AuthToken token = getAuthToken.getToken();         if (token == null)         {            System.err.println(               "Unable to obtain authToken");            return;         }            FindBusinesses findBusinesses = new             FindBusinesses();         Enumeration enum = findBusinesses.find();         while (enum.hasMoreElements())         {            org.apache.juddi.datatype.Name businessName =               (org.apache.juddi.datatype.Name)                enum.nextElement();            System.out.println("Found business: " +               businessName.getValue());         }            getAuthToken.discardToken(token);      }   }

Sample Application Test Results
To run the sample application, you will need to:

Figure 1. jUDDI “Happiness” Page: The figure shows the result of running the link The figure shows the result of running the link http://:/juddi/happyjuddi.jsp, which displays jUDDI information.

1. Start the UDDI registry Web application. Refer to the previous article in this series to learn how to start the Web application.
2. Populate the business_entity database with one record having a publisher_id of “Sun.”
3. Populate the business_name database with one record having a name of “Sun.”

With the Web application started, the link http://:/juddi/happyjuddi.jsp will reveal a jUDDI happiness page similar to the page in Figure 1.

After starting the UDDI registry Web application and populating it with a business named “Sun,” you can run the test application. The resulting output should look like Figure 2.

Identifying and Calling Alternate Services

Figure 2. Sample Application Output: Here’s what the sample application’s output should look like after starting the UDDI registry Web application and populating it with a single business, named “Sun.”

UDDI allows for multiple bindings or URLs to be associated with the actual physical endpoints to Web services, thus allowing you to provide a failover mechanism in the event that your primary service choice is not available. These endpoints are designated in the tModel data structure of a registry entry.

To review, tModel entries represent technical information about a service or services. This information is embodied within interface specifications such as WSDL documents, XSD files, XML files, etc.

You can also use a businessEntity structure for service failover, because that structure represents all known information about a business and the services that it offers. The following example illustrates a typical businessEntity structure:

The discoveryURLs element of a businessEntity structure is optional. However, this element contains a list of Uniform Resource Locators (URLs) that can point to alternate document-based service discovery mechanisms.

The discoveryURLs structure holds pointers (a list of discoveryURL elements) to URL-addressable discovery documents that you can retrieve via an HTTP/GET method call. Each discoveryURL element holds a 255-character-length string that represents a Web-addressable discovery document.

UDDI automatically assigns each recorded businessEntity structure a URL that returns the individual businessEntity structure. You conduct a URL search via the find_business call.

For example, here’s a discoveryURL list for a particular businessEntity:

                  http://www.mycompany?businessKey=            BE3D2F08-CEB3-11D3-849F-0050DA1803C0         

Finally, because a UDDI registry acts as an abstract layer between Web service clients and each particular Web service, the registry itself inherently provides a framework for failover and redundancy.

Refer to this DevX Special Report article, “Winning with Web Services” for a detailed look at tModels, discoveryURLs, and the find_business message.

The Universal Description, Discovery, and Integration (UDDI) specification and protocol work together to form one of the primary components of a complete Web services infrastructure. By following the steps shown in the article, you can use your private UDDI registry to find businesses, services, and alternate services.