Using Universal Description, Discovery, and Integration (UDDI) for Web Services

UDDI is the most pervasive directory mechanism for Web Services. Implementations of UDDI are Web Services and, therefore, are accessible from any language or platform. UDDI is unique in terms of the service implementation in that it is not location transparent; you need the address of a directory to access the directory. There are two major scenarios for UDDI:

• A software package delivers a private UDDI directory within an intranet for use with its own products or within a company.

• Applications use an Internet-based UDDI directory to collaborate with business partners or potential business partners .

IBM, Microsoft, and others have UDDI directories available on the Internet for access and tests. These directories can stay in sync with each other through the notification Application Programming Interfaces (APIs) built into the later versions of UDDI. The hope is that businesses can publish their information in the public directories for other businesses to find, much like you would locate a business using Google. There are two major differences between Google and UDDI. The first difference is that you will only be dealing with businesses returned from a search, without the wealth of nonbusiness content. The second difference is that the information is supposed to be highly standardized, so searches are more effective.

In many cases, standardization of information about businesses that implement a service already exists in the industry. There are several different classification systems for businesses; I use the North American Industry Classification System (NAICS) in this chapter, a standard that was available in the late 1990s before Web Services burst onto the scene. NAICS is a substantial evolution of an even older classification system that started in the 1930s: the U.S. Standard Industrial Classification (SIC) system.

Perhaps more troublesome than standardizing how to represent metadata about companies will be the problem of how to standardize service interfaces in Web Services. In my opinion, standardized interface development will be the most difficult achievement in Web Services simply because service interface agreement is not a technical achievement, it is a social achievement.

Service information structures change between different directory implementations, so you will spend some time dissecting the service information that UDDI holds. Rather than using SOAP structures to manipulate UDDI structures, you will use a UDDI client-side architecture adapter provided by the UDDI4J (UDDI for Java) package. As a result, all of the code presented in this chapter is in Java.

Understanding UDDI Service Information Structures

The information stored in UDDI is complex for beginners with Web Services. In fact, much of the information stored in UDDI does not even relate to Web Services. UDDI is simply a business-centric information repository.

In UDDI, four structures form the published business and service information:

Business Entity: This represents information about a business, such as the name , description, and any human contacts within the business. The business entity contains one or more business services.

Business service: This represents information about the services that a particular business offers. You would expect these services to represent Web Services, but they do not have to represent them. A service simply is a standard mechanism for describing how to access the services that a business offers, whether they are programmatic interface services or services you would access using your Web browser. Deleting a business entity deletes all of its business services.

Technical model ( tModel ): Technical models are specifications that elements in the directory can share. Business entities do not own or indirectly own tModels. A tModel exists in its own lifecycle; thus, deleting a business entity does not delete associated tModels. Contents of a tModel include a reference to a WSDL file if the tModel represents a Web Service.

Binding template: The binding template is an association between a service and a tModel. Consider the case where a tModel exists and represents a particular standard, such as UDDI. The tModel contains a reference to the standardized UDDI interfaces. The existence of the tModel does not imply the existence of an implementation of the tModel; instead, a specific business must give an implementation of the standard, thus the binding template and the independent lifecycle of the tModel. The binding template associates a business service (owned by a business entity) with a technical specification. The binding template gives information on how to access a particular service that adheres to the definition given in the technical specification.

The business entity, business service, and binding template nest within each other whereas the tModel stands on its own. A business entity contains one or more business services. A business service contains one or more binding templates. Each binding template refers to a tModel that is the specification of a service and forms the bridge between the nested business entity structure and the technical specification given in the tModel. Figure 5-3 shows the structure of the base structures that reside within a UDDI implementation.

Figure 5-3: UDDI service information

The complete UDDI specification is amazingly powerful and versatile. Consider UDDI the next generation of the phone book. Using the phone book, you will not only be able to locate any business, but you can locate a business based on the services it can offer you rather than on a broad category of services. Using today's Yellow Pages , you can easily locate a mechanic for your car, but you cannot tell whether that mechanic can offer you detailing and neon lighting. Correct usage of UDDI allows you to search for companies based on the services they have to offer, the technical specifications they adhere to, or even the company name and contacts available at a company.

Publishing Business Entities

The structure of a business in UDDI starts with the business entity. The business entity contains all of the information that a person or a program needs to locate your business. An interesting note is that UDDI renders the case study in Chapter 3, "Exploring the Service-Oriented Architecture Pattern," virtually irrelevant, except for its illustration of core Web Service attributes. The ability of UDDI to represent your company information makes the information available through the SmallCompany Web Service duplicate functionality.

A reason to use the UDDI representation of your company is the considerable amount of analysis that goes into the company representation. As an architect or designer, you can always benefit from independent analysis. You will not fully leverage the business representation in UDDI in this book, but you will see a few of the important pieces that help you locate businesses programmatically.

To build a UDDI business entity, you first construct a local version of the BusinessEntity and its contents. There are two parameters on the constructor, the business entity key and a name for the business entity. All primary constructs including the business entity, the business service, the binding template, and the tModels have unique keys associated with them. Passing a zero-length string tells the UDDI directory to create the unique identifier for you. After calling the constructor, you set the default description in code, as shown in Listing 5-1.

Listing 5-1: Creating a New Business Entity

 BusinessEntity newEntity =    new BusinessEntity("",       "P.T. Monday Coffee Company");    newEntity.setDefaultDescriptionString(          "P.T. Monday Coffee Company Business Description"); 

 

At this point, your business entity resides within your own process. You still have a considerable amount of work to do to publish the information in UDDI.

Exploring the UDDI Yellow Pages

Once created, you want to ensure people and programs can locate your business through a standard classification system. UDDI supports many common standards; you will use the NAICS to identify the P.T. Monday Coffee Company as a Coffee and Tea Manufacturing business. Code 31192 identifies the business. You also want to identify the unique identifying key for the tModel (discussed in the section "Publishing tModels") that represents the NAICS codes; this key is UUID:C0B9FE13-179F-413D-8A5B-5004DB8E5BB2. The only way to find much of this information is by browsing an existing UDDI directory, such as the IBM test directory at http://www-3.ibm.com/services/uddi/.

You place this information in a category bag within the new business entity. A category bag is simply a structure that contains zero or more references to other structures, usually in the form of a structure known as a keyed reference . Each business categorization is a keyed reference that consists of the tModel key, the name of the key, and the value of the key. The tModel key is a reference to the governing structure for this particular type of code. In this case, the tModel keys reflect a reference to the NAICS business identification system. Listing 5-2 shows how to create the category bag and insert a keyed reference, and it shows the subsequent placement of that reference into the entity. This information represents a way to look up the business as if it were in a Yellow Pages directory.

Listing 5-2: Categorizing Your Business Entity with a NAICS Identifier

 CategoryBag catBag = new CategoryBag(); KeyedReference naicsRef = new KeyedReference(); naicsRef.setTModelKey("UUID:C0B9FE13-179F-413D-8A5B-5004DB8E5BB2"); naicsRef.setKeyName("naics: Coffee and Tea Manufacturing"); naicsRef.setKeyValue("31192"); catBag.add(naicsRef); newEntity.setCategoryBag(catBag); 

 

Note  

There are several references to obtain NAICS identifiers. One location is http://www.census.gov/epcd/www/naics.html; this is a U.S. Census Bureau Web site.You can also look up NAICS keys at UDDI registries, such as IBM's test registry at http://uddi.ibm.com/testregistry.

Exploring the UDDI White Pages

Business entities also contain information about specific contacts at a business. Contacts contain names , physical addresses, email information, and more. One interesting twist on White Pages information is the way the address class holds address lines. Managing an internationalized structure for address information is difficult. An evolving standard exists in the UDDI community, but I do not use it in this section because of a lack of available information at the time of writing. As the information for internationalized addresses becomes widely available, I highly recommend using it.

Creating a contact is straightforward, and you will not have a problem reading Listing 5-3 to create a new contact and insert it into a business entity. This information corresponds to an address book's White Pages , information about people, and their locations. Typically, you would not look up a business by the people in it, but this is useful information after you locate a business to find people you can contact directly for information.

Listing 5-3: Adding Contacts for a Business Entity

 Contacts contacts = new Contacts(); Contact primaryContact = new Contact("Paul Monday"); Vector addresses = new Vector(1); Address address = new Address(); Vector addressLines = new Vector(4); AddressLine ad1 = new AddressLine("500 Eldorado Boulevard"); AddressLine ad2 = new AddressLine("Broomfield"); AddressLine ad3 = new AddressLine("CO"); AddressLine ad4 = new AddressLine("80021"); addressLines.add(ad1); addressLines.add(ad2); addressLines.add(ad3); addressLines.add(ad4); address.setAddressLineVector(addressLines); addresses.add(address); primaryContact.setAddressVector(addresses); Vector emailVector = new Vector(2); emailVector.add(new Email("[e-mail]")); emailVector.add(new Email("[e-mail]")); primaryContact.setEmailVector(emailVector); contacts.add(primaryContact); newEntity.setContacts(contacts); 

 

At this point, you are still operating against a locally constructed business entity. You still have to save this information to a public location before others can access it.

Saving the Business Entity to the UDDI Directory

You now have the bare minimum of information regarding your business. This information resides in a local set of classes. You now want to save this information to the UDDI directory you have chosen . Before calling the function to create the entity, you built a proxy to represent the UDDI directory using the UDDI4J package. It is a straightforward process, and you can browse the downloadable code for more information on this process. The uddi object instance represents the architecture adapter that converts the business entity (along with some authorization information in the authInfo instance variable) to a SOAP message and makes the service request of the target Web Service. The save_business method receives a vector of business entities so that the UDDI directory can build them all with a single service call (see Listing 5-4).

Listing 5-4: Saving the Business Entity to UDDI

 Vector newEntities = new Vector(1);    newEntities.add(newEntity);    BusinessDetail business =        uddi.save_business(authInfo, newEntities); 

 

Once built, anyone can locate your business using the NAICS code or business name and subsequently locate contact information for the company. You can also look at the business detail returned from the call to the UDDI proxy to obtain the unique identifier created by the UDDI directory for your service.

Most UDDI registries allow you to look up businesses from a Web page. Try out IBM's test registry at http://uddi.ibm.com/testregistry (if they moved the site, do not panic; be sure to use IBM's search engine to locate it).

Exploring the UDDI Green Pages

In addition to the White Pages and Yellow Pages in the UDDI directory, there is the concept of the Green Pages . The Green Pages hold technical information about a business, such as the business processes that a business supports, operating platforms, communication mechanisms, and more. There are two parts to a business service that represents this information: information about the service and a binding template that allows traversal to the information. The former describes the business service in enough detail that a business entity can be located based on the services it provides, and the latter binds a service to a technical service implementation. In this section you will look only at the information you provide with a service so that it can be located in the UDDI directory; the next section introduces tModels, and then you will look at how to create a populated binding between the service and tModels.

Listing 5-5 contains the simple code that creates the business service. The service contains a name, an empty binding template, and a business key, which is obtained from the created service in the previous section (the downloaded code contains information on how to retrieve the key from the business detail returned from the call to the UDDI proxy). You can associate category bags that contain keyed references, similar to the NAICS code associated with the business entity, to further identify the service as a standardized service that adheres to a known definition. These keys make it easier to search for a service based ona standard understanding of where a service gets used.

Listing 5-5: Creating a Business Service in UDDI

 BusinessService bs = new BusinessService();   Vector names = new Vector(1);   names.add(new Name("Product Collection"));   bs.setNameVector(names);   bs.setBusinessKey(businessKey);   bs.setServiceKey("");   Vector templateVector = new Vector(0);   BindingTemplates bindingTemplates = new BindingTemplates();   bindingTemplates.setBindingTemplateVector(templateVector);   bs.setBindingTemplates(bindingTemplates);   Vector services = new Vector(1);   services.add(bs);   rtrnValue = uddi.save_service(authInfo, services); 

 

The empty binding template created in Listing 5-5 is simply a placeholder for the binding template you have yet to create. When creating a business service in a normal scenario, the tModel usually already exists. As a result, you create the binding template at the same time as the business service. I have chosen to place the business service creation before the tModel creation so you can understand the nesting of the business entity and business service structures. You will come back and populate the business service with a binding to a tModel after you create the tModel in the "Publishing tModels" section.

Publishing tModels

tModels represent the technical specification of a service in the UDDI directory. Businesses do not own tModels; rather, they associate various elements to tModels. For example, a NAICS identifier is merely a key that a tModel specifies. Recall that upon creating your business entity, you identified your business as a Coffee and Tea Manufacturing business and associated the code for this business to your business entity. Further, upon creating the code, you also identified the technical specification that originates the code. By specifying the tModel, the directory can validate the code when you create the business entity.

Similarly, you can create your own tModels by publishing a reference to a service interface within UDDI. A tModel does not equate to an implementation of the model, just a specification. Listing 5-6 shows how to create a tModel for your product collection. It is similar to the creation of the business entity, so I will not go into many details. The important pieces of the code are the overview document specifying the location of the ProductCollection WSDL file and the subsequent identification of the overview document as a standard WSDL file. You identify the overview document as a WSDL file by creating a keyed reference and setting the tModel key to the UUID associated with the WSDL tModel.

If you used a standard other than WSDL, the keyed reference would point to a different technical specification. As with the business entity, a category bag holds onto the keyed reference. The final step to create the tModel and publish it is to use the uddi proxy to submit the locally built tModel to the Web Service.

Listing 5-6: Creating the tModel in the UDDI Directory

 TModel tm = new TModel();          tm.setName(Publish.PRODUCT_COLLECTION_TMODEL_NAME);          tm.setTModelKey("");          OverviewDoc od = new OverviewDoc();          od.setOverviewURL(             "http://localhost:8080/axis/services/ProductCollection?wsdl");          tm.setOverviewDoc(od);          Vector keyedReferences = new Vector(1);          KeyedReference kr1 =              new KeyedReference("uddi-org:types", "wsdlSpec");          kr1.setTModelKey("UUID:C1ACF26D-9672-4404-9D70-39B756E62AB4");          keyedReferences.add(kr1);          CategoryBag cb = new CategoryBag();          cb.setKeyedReferenceVector(keyedReferences);          tm.setCategoryBag(cb);          Vector tModels = new Vector(5);          tModels.add(tm);          TModelDetail tmodelDetail =          uddi.save_tModel(authToken, tModels); 

 

By running Listing 5-6, you have a business entity, a business service within the business entity, and a separate technical specification for a product collection. There is no established link between the tModel and the business service. It is important to realize that the tModel exists for businesses to share. You want your partners to use the same technical specification as yours. Companies relying on the same tModels reference the published tModels by binding to them with a UDDI binding template.

Binding Services to tModels

Creating a binding between business service and a tModel allows the UDDI directory to show that you use an open technical specification for a particular service. In theory, there will be a day that everyone uses the same tModels to implement similar business behaviors; however, that day may be some time from now.

Creating a binding between a service and a tModel is similar to the processes you have already seen. The important steps are setting the business service key that UDDI created for you earlier in the chapter, identifying the access point for the service, and identifying the tModel instance that the service implements. There does appear to be some duplicate identifying information in Listing 5-7 ” specifically the overview document created for you by the binding template. This overview document is in the same location as the technical specification. Keep in mind that this may not be the case because another party could create the tModel.

Further, UDDI allows you to identify more than one tModel with the binding to the service, in which case you would have a unique WSDL file to associate with your service.

Listing 5-7: Binding a Service to a tModel

 BindingTemplate bt = new BindingTemplate(); bt.setServiceKey(businessServiceKey); bt.setBindingKey(""); AccessPoint ap = new AccessPoint(); ap.setURLType("http"); ap.setText(     "http://localhost:8080/axis/services/ProductCollection"); bt.setAccessPoint(ap); OverviewDoc od = new OverviewDoc(); od.setOverviewURL(     "http://localhost:8080/axis/services/ProductCollection?wsdl"); InstanceDetails instanceDetails = new InstanceDetails(); instanceDetails.setOverviewDoc(od); TModelInstanceInfo tmii = new TModelInstanceInfo(tModelKey); tmii.setInstanceDetails(instanceDetails); Vector tmiiv = new Vector(); tmiiv.addElement(tmii); TModelInstanceDetails tmid = new TModelInstanceDetails(); tmid.setTModelInstanceInfoVector(tmiiv); bt.setTModelInstanceDetails(tmid); Vector entities = new Vector(); entities.addElement(bt); rtrnValue = uddi.save_binding(authInfo, entities); 

 

You now have a complete canonical description of your business and the services it implements. Figure 5-4 gives an overview of the complete UDDI structure you just created. The diagram itself is a physical containment relationship between all of the different structures in the service directory. It relates back to Figure 5-3 in terms of the containment relationships and associations, but its intent is to represent the physical containment of the structures with data instances rather than a diagrammatic representation of classes and instances.

Figure 5-4: The P.T. Monday Coffee Company UDDI structure

The structure contains all of the information under a single representation, but recall that someone else could own the tModel itself, or others could be referencing your tModel as an open standard. The entire structure gives programs and people many different ways to locate your business: through the NAICS identifier, through the tModels you implement, through people employed by your company, or any number of other criteria or combination of criteria you have created here.

Locating Information in UDDI

Most of this chapter discusses the publishing model of UDDI. You have learned about the business entity, business services, tModels, and the service bindings that form the basis for UDDI contents. Although there was a lot of code and explanations , you have really just scratched the surface of the different types of content that UDDI stores at your request. You typically publish information only a few times, but you want it to be located many times in the course of its life.

UDDI supplies a robust query mechanism that allows you to search on any type of information in a variety of combinations and with a variety of different ways to manage the data that returns from the query. The query mechanism is not as generic as Structured Query Language (SQL) or an Object Query Language (OQL) implementation, and it is not as flexible. You will be able to specify different structures and keys to search for without having to start from the top of the hierarchy, the business entity. You can also specify combinations of keys to look for in the directory.

For this example, consider the case where you want to locate all of the businesses in the coffee industry that implement the technical specification for product collections (that you published). This will be of extreme value as you attempt to locate businesses that you can interact with programmatically and integrate into your value chain.

Your query should return results that fill both of the following criteria:

• All businesses in UDDI that use the NAICS code 31192 to classify themselves

• All businesses that offer a product catalog that uses your technical specification for the interface

Recall that you published your own company with similar code to Listing 5-8 for identifying yourself as part of the coffee industry (the category bag instance variable name is changed). Listing 5-8 shows the code for creating the category bag again.

Listing 5-8: Setting Up the Query Criteria for the NAICS Code

 CategoryBag categoryBag = new CategoryBag();   KeyedReference naicsRef = new KeyedReference();   naicsRef.setTModelKey("UUID:C0B9FE13-179F-413D-8A5B-5004DB8E5BB2");   naicsRef.setKeyName("naics: Coffee and Tea Manufacturer");   naicsRef.setKeyValue("31192");   categoryBag.add(naicsRef); 

 

Next, you assume that you have a string that contains the tModel key that the business must implement for the product catalog. You can obtain this key in a variety of ways (manually searching, storing the tModel key from when you created it, querying for it using name and category criteria for tModels). Listing 5-9 shows how to create a tModel bag for use in the query criteria. The bag contains the key of the tModel obtained when you created the model in a previous section; this is the tModelKeyString instance variable.

Listing 5-9: Setting up the tModel Key on Which to Query

 TModelBag tModelBag = new TModelBag();   TModelKey tModelKey = new TModelKey(tModelKeyString);   tModelBag.add(tModelKey); 

 

Finally, you can use the architecture adapter, stored in the uddi instance variable, to submit the query and obtain query results in the form of a business list. All of the parameters on the method call in Listing 5-10 are either null or contain no list items except for the tModelBag and categoryBag .

Listing 5-10: Submitting and Processing the Results of a UDDI Query

 BusinessList businessList = uddi.find_business(names,                               discoveryURLs,                               identifierBag,                               categoryBag,                               tModelBag,                               findQualifiers,                               5);   BusinessInfos businessInfos = businessList.getBusinessInfos();   System.out.println("Located the following businesses...");   for(int i=0 ; i<businessInfos.size() ; i++){       BusinessInfo bi = businessInfos.get(i);       String name = bi.getNameString();       System.out.println("\tName="+name);   } 

 

Upon return from the location method, you loop through the returned businesses and print their names. There are many different processes you could do besides printing their name based on the information contained in each business. For example, because you know the product catalog interface, you could generate your own product catalog for the other business or do comparison shopping with the other product catalog. You could also automatically go to their Web page or locate contacts in the business to call on the telephone or send emails.

The query mechanisms in UDDI are robust and versatile. If you know the data contained in the various UDDI constructs from different businesses, you can construct a query to locate the information you need, when you need it.