The central idea behind the Web services revolution is that the Web will be populated with an assortment of small pieces of code, all of which can be published, found, and invoked across the Web. One key technology for the service-based Web is SOAP, the Simple Object Access Protocol. Based on XML, SOAP allows an application to interact with remote applications. That's all well and good, but how do we find those applications in the first place? That's where UDDI comes in.

UDDI provides three basic functions, popularly known as publish, find, and bind:

• Publish: How the provider of a Web service registers itself.
• Find: How an application finds a particular Web service.
• Bind: How an application connects to, and interacts with, a Web service after it's been found.

A UDDI registry contains three kinds of information, described in terms of telephone directories:

• White pages: Information such as the name, address, telephone number, and other contact information of a given business.
• Yellow pages: Information that categorizes businesses. This is based on existing (non-electronic) standards (see Resources).
• Green pages: Technical information about the Web services provided by a given business.

When I am working with a UDDI registry, there are four information types that are important to me:

• Business information: Contained in a BusinessEntity object, which in turn contains information about services, categories, contacts, URLs, and other things necessary to interact with a given business.
• Service information: Describes a group of Web services. These are contained in a BusinessService object.
• Binding information: The technical details necessary to invoke a Web service. This includes URLs, information about method names, argument types, and so on. The UDDI4J BindingTemplate object represents this data.
• Information about specifications for services: This is metadata about the various specifications implemented by a given Web service. These are called tModels in the UDDI specification; the UDDI4J TModel object represents this data.

In this article I will show how to write basic code for manipulating objects in a UDDI registry. You can test your applications with IBM's Test registry (see Resources) or download the UDDI registry server software available with the Web Services Toolkit (see Resources).

What's in the UDDI4J package

UDDI4J contains an implementation of the client side of UDDI (everything your application needs to publish, find, and bind a Web service). It also includes the source of the code, the complete JavaDoc documentation, and three sample applications. I will go over the UDDIProxy class, the most important class in the package, and cover the three sample applications.

Back to top

The UDDIProxy class

This class is the main object you'll use in your UDDI applications. It has all the methods you need to connect to a UDDI registry, execute a query, and process the results. In the sample applications I discuss here, the UDDIProxy object is what we use to interact with the registry. Listing 1 shows how to create such an object and point it at the registry:

UDDIProxy proxy = new UDDIProxy();
proxy.setInquiryURL("http://www-3.ibm.com/services/uddi/ testregistry/inquiryapi");
proxy.setPublishURL("https://www-3.ibm.com/services/uddi/ testregistry/protect/publishapi");

This code creates the object, then points the proxy to the IBM UDDI registry. Notice that the protocol in the setPublishURL method is https, the UDDI standard defines that anyone should be able to query a registry, but only applications and users with the proper access can modify registry information.

Other classes

Other classes supplied with UDDI4J provide access to all of the information available in the UDDI registry. For example, the BusinessList object allows you to access some number of BusinessInfo objects. For a given BusinessInfo object, you can access the ServiceInfoobjects that describe the services it provides. The classes in UDDI4J map to the various XML elements and APIs described in the UDDI Programmer's API Specification and the UDDI XML Structure Reference (see Resources).

Back to top

Sample application 1: Find a business in the UDDI registry

 BusinessList bl = proxy.find_business("S", null, 0);

All versions of the find_business method take three parameters: the first is the search parameter, the second is a FindQualifiers object (null in this example), and the third is the number of matches to return (0 means return all matches). There are several different kinds of search parameters, the simplest of which is a search string. More advanced search parameters include collections of business identifiers, business categories, URLs, and tModels. The method returns a BusinessList object, a collection that can be used to find specific information about all the businesses that match the search parameter.

Once we have the list of businesses that match our search criteria, this code iterates through the list and prints the names of all the businesses that match:

Vector businessInfoVector = bl.getBusinessInfos().getBusinessInfoVector();
for (int i = 0; i < businessInfoVector.size(); i++)
{
	BusinessInfo businessInfo = (BusinessInfo)businessInfoVector.elementAt(i);
	System.out.println(businessInfo.getNameString());
}

Although all the first sample application does is find Web services that meet certain criteria, it does do several interesting things. First, it connects to the UDDI registry, the first step in using Web services. Second, it queries the registry to find the businesses that meet certain criteria. Finally, it takes the information returned from the registry and does something marginally useful with it. Our next two samples will take interacting with a UDDI registry a step further.

Back to top

Sample application 2: Publish a business listing

UDDIProxysetPublishURL

AuthToken token = proxy.get_authToken("userid", "password");

The next step is to create a new BusinessEntity object and populate it with the various properties I want it to have. To keep the sample simple, I am only defining the business name, done with the elegantly-named setName method, in Listing 3.

Vector entities = new Vector();

BusinessEntity be = new BusinessEntity("");

be.setName("Sample business");

entities.addElement(be);

BusinessDetail bd = proxy.save_business(token.getAuthInfoString(), entities);

To verify that our data was published to the registry successfully, I print the data we received from the save_business method, as seen in Listing 4.

Vector businessEntities = bd.getBusinessEntityVector();

BusinessEntity returnedBusinessEntity =
	(BusinessEntity)(businessEntities.elementAt(0));

System.out.println("Returned businessKey:" +
	returnedBusinessEntity.getBusinessKey());

Back to top

Sample application 3: Unpublish (delete) a business listing

BusinessEntity

BusinessList bl = proxy.find_business("Sample business", null, 0);

Now that I have the list of businesses that match, I'll attempt to delete each one (see Listing 5). There may be any number of Sample business entries in the registry; this code will fail for any entries that weren't created by the userid in our sample, so I have to handle the error case (actually, all of the samples handle error cases, I've just left them out of this discussion for clarity).

Vector businessInfoVector = bl.getBusinessInfos().getBusinessInfoVector();
for (int i = 0; i < businessInfoVector.size(); i++)
 {
 	BusinessInfo bi = (BusinessInfo)businessInfoVector.elementAt(i);
 	System.out.println("Found business key:" + bi.getBusinessKey());
 	DispositionReport dr = proxy.delete_business(token.getAuthInfoString(),
 		bi.getBusinessKey());
 	if (dr.success())
 	{
 		System.out.println("Business successfully deleted");
	}
    else
    // handle error case

Back to top

Summary

IBM's release of UDDI4J gives Web services developers a complete and robust implementation of the client side of UDDI. With this code, you can interact with any UDDI registry, giving your applications complete access to the world of Web services. You're now ready to lead the revolution; get out there and get started!

Resources

• Visit the UDDI4J Project site to get complete information and the latest file releases.
  
  
• The definitive source for UDDI information is www.uddi.org. This site is jointly sponsored by IBM, Ariba, and Microsoft. There are four main documents to review:
  
  
• The UDDI registries for Microsoft and are available at http://uddi.microsoft.com.
  
  
• Download the IBM Web Services Toolkit. It includes the UDDI4J server for testing your Web services.
  
  
• The "yellow pages" information used in UDDI registries is typically based on two existing standards: NAICS (the North American Industry Classification System) and UNSPSC (the Universal Standard Products and Services Classification). NAICS is a joint project of the governments of Canada, Mexico, and the United States. Complete details can be found at www.naics.com. UNSPSC was created when the United Nations Development Program and Dun & Bradstreet merged their efforts into a single classification system. See www.unspsc.org for more information on UNSPSC.
  
  
• The SOAP specification was submitted to the W3C by IBM, Microsoft, DevelopMentor, Lotus, and UserLand Software. You can read it in all its glory at www.w3.org/TR/SOAP/.
  
  
• The developerWorks Web services zone offers an article on building a SOAP-based application.
  
  

About the author

MC Dug-T is developerWorks' Minister of Science, droppin' the XML, Java, and Web services 411 on the public. In his travels, he gets mad props from his peeps worldwide for the stone-cold, stoopid-fresh style sheets he leaves behind. All his mad-phat nollidge will soon be published by O'Reilly and Associates in the Strictly Non-Fiction book XSLT (ISBN 0596000537, pre-order your copy today at amazon.com) which will then start slayin' soft-sellin' suckas at tha local booksella. Discussing the book in a recent dW interview, he boasted, "I'm gonna empty mah dome into one supa-fly tome."
For relaxation, he likes to put his hands up in the air, and in his words, "wave 'em around like I just don't care." When not chillin' with his worldwide XML krew, he maxes at the crib in Raleigh with his wife, cooking teacher CT-ONE, and their six-year-old shortie, Lily the Flayva Princess. You can send him a shout-out at dtidwell@us.ibm.com.

Rate this article

Comments

Back to top

Table of contents

• What's in the UDDI4J package
• The UDDIProxy class
• Sample application 1: Find a business in the UDDI registry
• Sample application 2: Publish a business listing
• Sample application 3: Unpublish (delete) a business listing
• Summary
• Resources
• About the author
• Comments