Understanding UDDI and JAXR

Over the past few years, much of the Java developer community has embraced the various pieces of J2EE, and in the process has given server-side programming the high status formerly enjoyed by client-side programming tools (GUI frameworks that include Swing). Now, the developer community is being challenged once more to weigh SOAP services to see if they can raise the bar for server-side programming.

The proponents of SOAP services believe:

• An enterprise application server is a collection of services (or transactions).
• Available services should be conveniently listed for browsing, searching, and access.
• Designing an application server as a collection of services will encourage developers to use better design practices, just as they are now adhering more closely to component-based development practices.
• These units of transactions can be relocated, load-balanced, replaced, security-applied, etc.

The skeptics, on the other hand, see SOAP services as another attempt at bringing CORBA and COM to a much broader audience. They note that SOAP seems to require a lot of work for a simple call to an object, and argue that the benefits of UDDI are overstated as far as a business differentiation/sales tool.

So which is it? While some developers have already picked sides, those with an open mind will want to understand some of the core technologies before deciding whether or not to embrace SOAP services.

In this effort, I recently spent a good part of a week pouring through magazines and online materials looking for comprehensive information for the role and necessity of UDDI/WSDL for Services. I hope that by writing this article, I can save you a ton of time going through a similar exercise. I would not have written this article if UDDI were not interestingly abstract and complex. But it is both, so on with my findings.

The annotated references at the end of the article will work as references for the basic material. I intend to focus here on the tricky parts of the standard while only covering the basics for a comprehensive read. The article concludes with a discussion of Java APIs for XML Registries and Messaging (JAXR and JAXM, respectively.)

Inside UDDI

Let us start with the acronym. UDDI stands for Universal Description, Discovery and Integration. UDDI's intent is to function as a registry, just like the Yellow Pages is a registry for businesses in a given metropolitan area. Like in the Yellow Pages, in a UDDI registry, companies will register themselves or their services under different categories. By browsing a UDDI registry, a developer should be able to locate a service and a company, and find out how to invoke the service.

Beside the Yellow Pages, UDDI also refers to White Pages and Green Pages. White Pages are a listing of business entities. Green Pages (here the phone book metaphor breaks down, unless there are some green-colored manuals hidden away at the phone company) basically represent technical documents necessary to invoke a given service.

UDDI definitions are general enough to accomodate services of different kinds, which are not necessarily SOAP services. A UDDI definition could represent a faxing service or a telephone service. UDDI, being a registry, is typically implemented using a database of sorts. In this database, there is a data model allowing publishing and querying of these pieces of information.

UDDI Data Model

The UDDI data model contains the following main elements:

• businessEntity: Represents a physical company.
• businessService: Represents a service offered by a company.
• bindingTemplate: Instructions on how to invoke a service.
• tModel>: Good luck understanding this! (Just kidding, I will explain this later.)

Examples of UDDI XML documents are available here.

For an in-depth understanding of the data model, let's look at a UML representation of these data elements. Figure 1 shows the relationship between the four main elements.

From this diagram, you can infer that a business entity (a company) has a descriptive URL that can tell us more about the company, and a list of contacts at that company. In addition, a business entity has a list of business services. There can be multiple ways of invoking each business service. Each invocation is described by a binding template. Because a binding template describes in detail how to access a service, it can benefit from a series of documentation elements that describe how one can access the service. This connection between a binding template and its necessary documentation is accomplished through what is called a tModel. In the diagram, this relationship is simplistically represented for now as a bindingTemplate having a collection of tModels. This relationship will be further explored in the coming pages. Unfortunately, before I can explain how tModel>s relate to binding templates, we have to travel the detour of understanding what tModels are.

What is a TModel?

Imagine a tModel as an independent table in a database with the following columns: name, description, URL (that can tell you more about the name and description), unique key (to identify the name). In essence, a tModel is something that has a "name" and "description." Of what use is such minimal information? And isn't that a waste, giving a database table to represent this minimal concept? Let us take an example and explore.

Here are a couple of entries in a fictitious tModel database:

A few things can be noted by correlating a tModel to a database table. First of all, a tModel is an independent table, meaning it can exist by itself. Secondly, a tModel is a lookup table providing a translation between a key and a representation of what that key is. In this sense, a tModel is a reference table, like a dictionary. In some databases such a table is also known as a codeset.

In all cases, the above definitions will allow me to say:

com.mycompany.HelloWorld, 1

This implies that the string com.mycompany.HelloWorld is a fully qualified Java class.

com.mycompany.HelloWorldHome, 2

This implies that the string com.mycompany.HelloWorldHome is a JNDI name.

Related Reading Java Web Services By David A. Chappell, Tyler Jewell

So in a sense, the unique keys of tModels are representing a concept, such as a "namespace." To illustrate this further, consider the following numbers:

904-555-1212
904-555-1213
1-56592-391-x

How could you tell what these numbers are? You need a context, or a namespace, to establish that 904-555-1212 is a telephone number, 904-555-1213 is a fax number, and 1-56592-391-x is an ISBN number.

So in your tModel database, you will define three entries: one for a telephone number, one for a fax number, and one for an ISBN number.

Let's say that your company "mycompany" has declared a helpline at number "1-800-my-helpline" and you want to register this with the UDDI. Then your data models will be:

company name: mycompany
Service name: helpline
tModel: key=11 (representing telephoneline), name=telephone, 
        description=telephone stuff, url: 
		some at&t url
binding: 
      accesspoint: 1-800-my-helpline
      tModelInstanceInfo: 11

With this basic understanding of the tModel, let us investigate, using a UML diagram, the relationship between a binding template and tModels. As I have suggested earlier, this should lead us to a direct understanding of how a binding template achieves the "how to invoke a service" requirement of UDDI.

In Figure 2, I have elaborated the relationship between a binding template and tModels. From the diagram, you can see that a binding template can point to a technical specification identified by a tModel. This technical specification has two parts:

• The type of the specification (e.g., email, fax, WSDL, SOAP service, etc.)
• Documents identifying inputs and outputs (in the case of a SOAP service, these documents could be XML input/output message formats)

Now that we understand tModels in some detail, let us move to the next level of complexity in UDDI, namely identity bags and category bags.

Understanding Identity and Category Bags

If conceptual understanding of the tModels is the first obstacle in understanding UDDI, understanding the identity and category bags is the second obstacle. These bags are best described with an example.

Your company has a tax ID number for doing business in the U.S. If you were to operate in another country as well (say, Mexico), you would need to have a Mexican tax ID number in addition to your U.S. number. To capture this information about your company in the UDDI registry, you would do something like this:

Company name: mycompany
Identifiers:
	US tax number: 111111
	Mexico tax number: 2223344
	Some other number: 333333

...Other xml stuff
<identifierBag>
	<keyedReference tModelKey="US-tax-code" 
	 keyName="taxnumber" keyValue="1111111">
	<keyedReference tModelKey="Mexico-tax-code" 
	 keyName="taxnumber" keyValue="2223344">
	<keyedReference tModelKey="other-stuff" 
	 keyName="taxnumber" keyValue="333333">
</identifiedBag>
... Other xml

See how the tModels are being used as namespaces (us-tax-code, mexico-tax-code, etc.)? To further solidify your understanding of the identifier bags, Figure 3 shows a UML diagram.

From Figure 3, one can see that an identifier bag is a collection of key/value pairs within a given context. The context is essentially the namespace that can uniquely resolve the name/value pairs. This namespace is identified by a tModel. The same is true with category bags. The only difference is that the namespace identified by the tModel in a category bag points to a predefined category (or a "taxonomy").

Category Bags

Let's say I want to categorize my company as belonging to the "restaurants" category and geographically located in "Jacksonville."

Company name: mycompany
Applicable Categories:
	Type of business classification: restaurant
	city classification: Jacksonville


<categoryBag>
	<keyedReference tModelKey="BusinessTypeClassification"
	   keyName="restaurant" keyValue="..">
	<keyedReference tModelKey="CityClassification" 
	   keyName="JAX" keyValue="..">
</categoryBag>

So far we have seen how tModels have been used for the purposes of Identifier and Category bags. tModels have essentially served as namespaces.

Are there any standard namespaces and/or classifications that are expected with any UDDI provider?

Obviously, you need to get the unique keys of these tModels to reference them in your category bags.

The best source for understanding identity and category bags is the "UDDI data structures" document (PDF) from UDDI.org.

Can tModels be categorized as well?

So far we have seen how a business entity can make use of category bags using tModels. In addition, UDDI allows tModels themselves to be categorized. Why?

Let's draw a parallel to a hierarchical file system. Directories are used to categorize files, but directories can also be categorized under parent directories. Just like directories on a hard drive, tModels can be hierarchically organized.

Let's talk about a service called getUniversalTime(), which will return the current universal time anywhere in the world. Two competing companies might provide implementations of this service. A business service is tied to a company and not visible outside of that company. So you will end up with the following:

company1:getTime()
company1:getCurrentTime()

Both of these do the same. To indicate that they both implement a concrete conceptual service called getUniversalTime(), you can define a tModel as follows:

tModel
	name: Get Universal Time
	category: uddi-org:types, wsdl 
	  [implying that this a service as 
	  described by a WSDL document]

The above definition indicates that getUniversalTime() is a WSDL service that can be implemented by any organization.

Now that I have clarified the relationship between tModels and bags, I can show you the UML representation of a tModel.

From the diagram, you can see that a tModel is basically a name and description. In addition it can contain a URL for further details. A tModel can also be identified using an identity bag and categorized by a category bag.

How many other types are there in the uddi-org:types category?

While categorizing a tModel, we have learned that some of the categories to which a tModel can belong to are pre-defined by the UDDI -- WSDL, SOAP service, etc. Here is a list of some of these pre-defined categories in the uddi-org:types namespace.

• tModel
• identifier (Unique identifier)
• namespace
• categorization
• specification
• xmlSpec
• soapSpec
• wsdlSpec
• protocol
• transport
• signatureComponent

So How Do You Go About Creating a Service in UDDI?

1. You start out defining a tModel for your service. This requires a name for your service and one of the above types of service. Of course, you can always create your own categories if you don't particularly care for the above choices.
2. You define a business service under your company, pointing to the tModel you have created above.
3. In the business service definition, you will need to specify a URL pointing to the actual WSDL document defining inputs/outputs to your service (assuming you are using a WSDL-compliant service).

Please refer to the excellent article by Andy Grove in the November, 2001 edition of Web Services Journal to see an example of this.

What are tModels Used For in UDDI?

tModels are used for the following purposes in UDDI:

• Identifying and categorizing business entities
• Identifying and categorizing business services
• Identifying and categorizing tModels
• Aliasing/binding business services to their abstract tModel definitions

Quick Reference to UDDI Terms

When you read literature about UDDI, it is very annoying to read terms that are fairly abstract. What the authors are trying to do is to draw parallels from the rest of the industry to the concepts in UDDI. However, it's very helpful to draw comparisons (however remote) to aid in our understanding of UDDI concepts.

Interfaces and Implementations

A service binding is considered a case where interfaces are tied to their implementations; a binding element specifies a tModelInstaceInfo and an instanceDetail together. The tModelInstanceInfo points to a tModel that actually defines a service name. instanceDetail is expected to provide some specific detail about this service.

Again, an example will help. For the "Get Universal Time" service, the detail is expected to provide the actual WSDL document that defines inputs and outputs. In addition, the accesspoint of a binding is expected to give you a physical machine and a port where this service is implemented. With this background, one can conclude the following:

• The tModel defined for a service is the interface allowing multiple companies to provide multiple implementations.
• Service binding is the implementation.

Namespaces

Namespaces appear all over the programming languages Java, C++, and XML. They may be called different things, but they all provide a context under which a name makes sense. In UDDI, a tModel represents "name." When you refer to this name as your category, you are essentially saying, "I belong to this name." In this sense, a tModel is representing a namespace.

Technical Fingerprints

When a service is registered as a tModel, one has the option of registering the protocol used to communicate with that service (such as WSDL, SOAP, etc.). Hence, a given tModel has a fingerprint of WSDL or a fingerprint of SOAP, depending on which specification it is using. Thus tModels are considered technical fingerprints, each adhering to a certain technical specification. If tModel can represent a "technical fingerprint," I could also argue that a tModel can also be said to represent a "protocol" as well.

Taxonomy

Taxonomy is synonymous with (and equivalent to) categorization, classification, and namespaces. Taxonomy provides a context under which identifiers such as numbers and names make sense. For example, US tax and ISBN numbers only makes sense when you know that they are US tax numbers or ISBNs. This sort of classification is sometimes called taxonomy.

White Pages

A listing of business entitites in the UDDI registry and the ability to search for companies based on their name.

Yellow Pages

These categorize business entities into their business categories and other sorts of applicable categories.

Green Pages (Technical Specifications)

These add the ability to understand a service definition and its access requirements with the help of a series of documents. serviceBindings and tModels help this cause.

Example XML for UDDI

I cannot possibly leave you without providing a decent reference where you can find example XML documents for the UDDI, to help you solidify your understanding of UDDI.

1. The first excellent reference is provided by Andy Grove in the November 2001 edition of the Web Services Journal under the title of "Understanding UDDI tModels and Taxonomies."
2. The second example is available online at http://dcb.sun.com/practices/webservices/overviews/overview_uddi.jsp.

JAXR

JAXR is a Java XML API for working with service registries. As we have discussed so far, all elements of a UDDI are described using XML documents. In a sense, if you are able to send an XML message containing a service definition, the UDDI registry should be able to register it or update it, as the case may be. Let us see how one can accomplish this if you don't have any tools:

1. Write the necessary XML for the service definition.
2. Understand SOAP headers so that you can send your XML file as a SOAP attachment to the UDDI registry.
3. Access SOAP client Java API to accomplish step 2.
4. Deal with SOAP programmatically.
5. Depending on the UDDI service (sorry to overload this term here), construct messages to accomplish that UDDI task.
6. For each message, go through steps 2 and 3.

If you have access to JAXM, you can do a better job of the same interaction. Because JAXM allows you to send XML messages without concern for SOAP headers and is strictly a message-oriented protocol, using this approach, the above sequence becomes:

1. Write the necessary XML for the service definition.
2. Use the JAXM API to send and receive XML messages. The SOAP stuff is hidden by JAXM.
3. Depending on the UDDI service, construct messages to accomplish that UDDI task. (For example, registering a service with a UDDI registry may contain the exchange of four messages.) This means you are still dealing with XML content.

Here comes JAXR to the rescue. Here, you only need to work with a high-level Java API that will internally generate all of the necessary messages and transact them through JAXM. The interesting point to note is that JAXM will be used to accomplish the task.

Let's look at the stated goals for JAXR:. (This list is directly taken from (JSR 93.)

1. Support for industry-standard XML registry functionality
2. Support for registration of member organizations and enterprises
3. Support for submission and storing of arbitrary registry content
4. Support for lifecycle management of XML and non-XML registry content
5. Support for user-defined associations between registry content
6. Support for user-defined multi-level classification of registry content along multiple user defined facets
7. Support for registry content querying based on defined classification schemes
8. Support for registry content querying based on complex ad hoc queries
9. Support for registry content querying based on keyword based search
10. Support for sharing of Web services
11. Support for sharing of business process between partners
12. Support for sharing of schemas between partners
13. Support for sharing of business documents between partners
14. Support for trading partner agreement assembly and negotiation
15. Support for schema assembly
16. Support for heterogeneous distributed registries
17. Support for enabling publish/subscribe XML Messaging between parties

JAXR is expected to support not only UDDI, but other similar registry standards (such as ebXML) as well.

References

• "Understanding UDDI tModels and Taxonomies" by Andy Grove, Web Services Journal, November 2001.
  If you have access to this magazine, this should be your first read to get an overall idea of UDDI and tModels. You can follow this up by reading the data model as documented in a PDF document at uddi.org. This reference is also a good source to get example XML for the UDDI.

• UDDI Data Structure Specification (PDF)
  This is the most comprehensive and valuable document for not only using UDDI, but understanding it. If you to read only one document on UDDI, read this one.

• UML of the UDDI
  Recently the DTD of an XML is being increasingly represented using UML. UML, being pictorial, can much more easily convey the structure of an XML document. With this trend, this document from XMLModelling.com can give you the minute details of UDDI, represented as XML. The only drawback might be that too much detail in a UML diagram could overwhelm the reader.

• UDDI at Microsoft
  One thing you can gain from the Microsoft Web site is the ability to understand the UDDI registry from the perspective of its GUI interface. For example, how can one register a service graphically, and how can one search for services on the Web?

  This document explains the basic UDDI structures and their programmatic and online manipulation. For the GUI of a UDDI, refer to this document.

• IBM'S UDDI Documents
  This URL explains the relationship between WSDL and UDDI.

• "Hangin' with the JAX Pack", a three-part series by Al Saganich at OnJava.com.
  This series is an excellent and lucid introduction to the JAXPACK API that includes JAXP, JAXB, JAXM, JAX-RPC, and JAXR.

Satya Komatineni is the CTO at Indent, Inc. and the author of Aspire, an open source web development RAD tool for J2EE/XML.

---

Return to ONJava.com.

Copyright © 2009 O'Reilly Media, Inc.