In this article, we will look at UDDI and the role it plays in the discovery and browsing of web services. We will provide an overview of UDDIís standard model and the API that is used by clients to access the UDDI Registry. This is second of two articles that focus on describing and publishing web services using WSDL and UDDI. This is part of a larger series of articles to help you prepare for the web service developer exam. You can review the first article on describing and publishing web services, ďTutorial:Review of WSDL Document for the Web Service Developer ExamĒ if needed.

Introduction to UDDI

The Universal Description, Discovery, and Integration (UDDI) is a standardized directory used for publishing and discovering information about web services. UDDI is an industry initiative to create a platform-independent, open framework for describing services, discovering businesses, and integrating business services. It focuses on the process of discovery in the service-oriented architecture. UDDI is centered around the concept of a Web service interface which is typically described by a WSDL document

As web services became more and more popular as a basis for electronic commerce, it became difficult for companies to interact with their partners without defining more interfaces to connect to each of the partners systems. Corporations were looking for a means of discovering what each of their business partners could do. Attempting to do this manually would have been prohibitively expensive and time consuming. It is from this situation came the concept of UDDI that provides a registry that is distributed among many nodes that replicates the participating businesses' data with one another. The UDDI registry of services which are hosted by a multitude of businesses on the Internet addresses this problem. A conceptual figure of this is shown below:

Tutorial:In Depth Look at UDDI for the Web Service Developer Exam-b4-uddiservicediscovery.jpg
Figure: UDDI Facilitating Service Discovery

UDDI Overview

With UDDI, a business can register three different types of information into a UDDI registry. There are not called by these types in the specification, but they provide a clear overview of the type of information that UDDI can store for businesses:

White pages
This provides basic contact information and identifiers about a company, including business name, address, contact information, and unique identifiers such as D-U-N-S numbers or tax IDs. This information can be used to discover the desired web service based upon your business identification.

Yellow pages
This information describes a web service by the use of taxonomies (i.e. different categorizations) and allows others to discover your web service based upon its categorization like manufacturing or car sales.

Green pages
This provides technical information describing the behavior and supported functions of the web services hosted by your business. This information includes pointers to the grouping information of web services and where the web services are located.

How UDDI Is Used

UDDI has a number of different uses. From a business analyst's perspective, UDDI is similar to an Internet search engine for business processes. A business analyst can browse one or more UDDI registries to search for different businesses exposing web services and the specifications of those services. Since most the of information in a UDDI register is not reader friendly, generally a business user would use a marketplace or business search portal to browse the services and businesses hosted in a UDDI registry. As well, software developers can use the UDDI Programmer's API to publish services in the registry and to query the registry to discover services matching various criteria. Although some registries are user-friendly, generally the web service tool you use should automate the interaction with a UDDI registry.

Technical Architecture

The UDDI Business Registry (UBR) is a conceptually single system with multiple nodes that has itís data synchronized through replication. Each of a series of operator nodes hosts a copy of the content. The global grouping of operator nodes is known as the UBR. The operator nodes replicate content among one another. Irrespective of the any individual operator node being accessed, it will provide the same information and quality of service as any other operator node. Any content inserted into the UBR is always initially completed at a single node which then becomes the master owner of that particular content. All subsequent changes of the data must occur at the master owner operator node. This registry is known as a public cloud. The figure below shows the UBR:

Tutorial:In Depth Look at UDDI for the Web Service Developer Exam-b4-uddiarchitecture.jpg
Figure: UDDI Architecture

The UBR has a widely accessible inquiry services. All published services can only be done by authenticated entities. The authenticated business can create an operator node and publish it over the Internet thus becoming part of the UBR.

There is a demand by companies to setup private UDDI nodes that would allow for a smaller set of companies to meet the demands of the industrial sector or in order to work more closely with their partners. Private operator nodes can also define the access rules for their nodes on a case-by-case basis. They are free to follow the same model as the UBR or make the restrictions looser or tighter. There are quite a number of products that have been created or expanded to facilitate the creation of public or private UDDI registries. Examples of these come from IBM WebSphere and Bea WebLogic Server that include a fully compliant UDDI Server as part of the application server package.

UDDI Specifications and Java-Based APIs

Below we will outline the different specifications that make up the UDDI initiative and the options available to Java developers for writing programs that interact with a UDDI registry.

UDDI Specifications

The UDDI project also defines a set of XML Schema definitions that describe the data formats used by the various specification APIs. These documents are all available for download at The web page you are looking for is no longer available. | UDDI. The UDDI project releases their specifications in unison. The current version of all specification groups is Version 2.0. The specifications include:
  • UDDI replication - this specification describes the data replication processes and interfaces to which a registry operator must conform to achieve data replication between sites. This specification defines the replication mechanism used among UBR nodes.
  • UDDI operators - this specification outlines the behavior and operational parameters required by UDDI node operators. It defines data management requirements to which operators must adhere. An example would be that node operators are responsible for ensuring each business registration has a valid email address associated to it, the integrity of data during deletions a well as the recording and backup of all data. Note that private registries are not required to support it.
  • UDDI Programmer's API - this specification defines a set of functions for use by programmers that all UDDI registries are required to support for inquiring about services hosted in a registry and for publishing information about a business or a service to a registry. It defines a series of SOAP messages with XML documents to which a UDDI registry accepts, parses, and responds. This is part of the programming interface to a UDDI registry along with the UDDI XML API schema and the UDDI Data Structure specification.
  • UDDI Data Structures - this specification details the XML structures contained within the SOAP messages defined by the UDDI Programmer's API. There are five core data structures defined as well as their relationships to one another.

The UDDI XML API schema is stored as an XML Schema document defining the structure and datatypes of the UDDI data structures. It is not a specification.

Java-Based APIs

Although the UDDI specifications do not define a Java-based API for accessing a UDDI registry. Instead, the Programmer's API specification provides a series of SOAP messages that a UDDI registry can accept. For the Java developer wanting to access a UDDI registry, the options are listed below:

A Java-based SOAP API
You can use an API that creates SOAP messages containing a UDDI XML document. You would need to hand roll each XML document and insert it into the body of each SOAP message. This requires a profound understanding of the ordering of the SOAP messages that a UDDI registry accepts and the ability to format each SOAP message properly.

A Custom Java-based UDDI client API
There are companies that have created their own client APIs for accessing a UDDI registry. The classes and constructs of these APIs represent the data structures and messages supported by UDDI. They permit you to interact with a UDDI registry without knowledge of SOAP or the XML messages and the data structures with which UDDI interacts. These custom libraries generally work with any UDDI registry. An example of this type of custom library is the one created by Systinet.

Using JAXR
JAXR defines a standard way for all Java programs to access a registry. With JAXR, a developer can write code to access several different registries, including UDDI and the ebXML Registry/Repository. The JAXR API gives you a common way to access a variety of different registry types, although the JAXR's programming constructs don't mimic those used by UDDI. The main downside for this portability is the additional layer of abstraction required by JAXR.

Programming UDDI

There are two APIs for the UDDI specification. These are the Inquiry API and the Publishing API. They are accessed using the same techniques but the XML documents, data structures, and access points for each are different. You use the Inquiry API to locate information about a business, the services the business offers, the specifications of those services, and any information about how to address a failure. All read operations from a UDDI registry uses one of the Inquiry API's messages. It is not required to be authenticated in order to use the Inquiry API. It is accessible via HTTP.

You use the Publishing API to create, store, or update information located in a UDDI registry. You must be authenticated to access any function of this API. The login identity must be in the UDDI registry. The security credentials for the identity should be passed as a parameter of the XML document for each UDDI invocation. Since the publishing API requires authenticated access, all traffic for accessing it is over HTTPS on a different URL than the one used for the Inquiry API. In the table below is a list of the inquiry and publishing access point URLs for some major operator nodes.

Tutorial:In Depth Look at UDDI for the Web Service Developer Exam-b4-accesspointurls.jpg
Table: Access Point URLs
UDDI APIs are designed to be simple to use. All operations that a UDDI registry performs are synchronous. So your requests must block and wait for a response before continuing with processing. Also all operations use a simple request/response mechanism which allows them to be stateless behaviour. Thus alleviating the need for the UDDI APIs to require a lot of complex ordering.

UDDI Data Structures

The UDDI Data Structures are a part of the API which are important to understand. There are basically five key elements that you need to know about.
  • A <businessEntity> structure represents a business's basic information. This includes the contact information, categorization, identifiers, descriptions, and relationships to other businesses. Companies that are part of the UDDI use this to establish relationships with one another via a <publisherAssertion>.
  • A <publisherAssertion> structure is used to establish public relationships between two <businessEntity> structures. The relationship between two <businessEntity> structures is visible only to the "public" when both companies have created the same assertion with two separate <publisherAssertion> documents independently. A company can only claim a business relationship if its partner asserts the same relationship. The company's assertion about a business relationship isn't visible to the public until the partner creates a similar, but separate, <publisherAssertion> document for its own <businessEntity> structure.
  • A<businessService> represents a single, logical service classification. It is one or more of the structures contained within a <businessEntity>. A <businessService> element is used to describe a set of services provided by the business. The services can be either web or manual services. A <businessService> document can be reused by several <businessEntity> elements.
  • A <bindingTemplate> holds pointers to the technical descriptions and access point URL. It does not contain any details of the service's specifications. It is considered part of a <businessService> which can contains one or more <bindingTemplate> structures. The <bindingTemplate> has an optional text description of the web service, the URL of its access point, and a reference to one or more <tModel> structures.
  • A <tModel> is an abstract description of a particular specification or behavior to which the web service adheres. A <tModel> is a like a digital "fingerprint" for determining the specifics of how to interact with a particular web service. The <tModel> structure contains pointers to locations of the actual specifications. A Company could use the information pointed to by a <tModel> to determine whether a web service is compatible with their business requirements.

The figure below shows the relationships between the primary UDDI data structures:

Tutorial:In Depth Look at UDDI for the Web Service Developer Exam-b4-erd-uddi.jpg
Figure: Entity Relationships for UDDI Data Structures

UUID Identifiers

The data structure instances are identified and referenced through a universally unique identifier, known as a UUID. UUIDs are assigned to the data structure when they are first inserted into the UUID registry. They are hexadecimal strings defined by the ISO/IEC 11578:1996 standard which provides the generation algorithm and structure for them. They are used in order to guarantee that the identifier generated will be unique. This is due to the concatenation of the current time, hardware address, IP address, and random number in a specific fashion to generate the UUID. The UUID are on used by the Inquiry API uses the UUID to request a particular structure on demand.

Browsing Basic Information

When you want to retrieve basic information about a business, web service or metadata on a specification supported by a web service, there is a series of messages that allow a program to achieve this. These messages are all SOAP messages whose XML body element begins with find. There is also a response message defined that corresponds to each request message. This is shown in the table below that shows the messages that can be used to retrieve basic information for searching purposes.

Tutorial:In Depth Look at UDDI for the Web Service Developer Exam-b4-browsinginquiries.jpg
Table: XML Documents for Browsing Inquiries

In the table, the "Message name" column shows the name of the XML root element used as the body of the SOAP envelope in the request. The "Response document" column shows the name of the XML root element that is the body of the SOAP envelope for the response.

There are numerous structures that make up the UDDI Programmer's API and UDDI Schema documents for request and response messages. You use the Programmer's API identifies the structure of the request and response messages. Please check the input parameters for every request message in order to avoid mistakes. The same data structures along with datatype and constraints are provided in the UDDI Schema. In fact, when you are doing any development with UDDI, it is important to keep copies of both documents.

Finding More Inquiry Detail

The message use to get more detail such as find_ messages are designed to return basic information about the structures that a UDDI registry manages. If you provide the UUID to one of the major data structures, it is possible to drill down into the registry to obtain the full listing of the details stored on that structure. There are a number of get_ messages available in the Inquiry API to retrieving information from the registry. These are shown in the table below:

Tutorial:In Depth Look at UDDI for the Web Service Developer Exam-b4-xmldocgetdetailedinfo.jpg
Table: XML Documents to Get Detailed Information

As you can see the message are simple and direct. All you need is a valid UUID for the data structure and you can obtain its details. For example if you wanted to use find more information about a web service in which you already knew the UUID from a previous query, you could do the following for a <get_serviceDetail> message to the UUID:

XML Code: Example of Get Service Detail Request
<uddi:get_serviceDetail generic="2.0"> 
Note that the <get_serviceDetail> message has only one subelement <serviceKey> and no optional attributes for the UUID of the web service for which you have requested more detail. You could provide more than one <serviceKey> subelements in your query. The response document returned by the UDDI server is shown below:

XML Code: Example of UDDI Response Document for Acme Traders
<serviceDetail generic="2.0" operator="SYSTINET" xmlns="urn:uddi-org:api_v2">
        <businessService businessKey="9a26b6e0-c15f-11d5-85a3-801eef208714" 			serviceKey="860eca90-c16d-11d5-85ad-801eef208714">
          <name xml:lang="en">CommodityQuote</name>
          <description xml:lang="en">Find the latest commodity quotes</description>
              <description xml:lang="en">
                The address to which you should send the name
                and address of your commodity quotes
              <accessPoint URLType="mailto">
                  <description xml:lang="en">
                    The smtp protocol is used when sending information
                      <description xml:lang="en">
                        Describes how to use this service
                  <description xml:lang="en">
                    The namespace in which our commodity quotes are used.
            <keyedReference keyName="Acme Traders" 
            <keyedReference keyName="Acme Commodities Traders"
            <keyedReference keyName="Portugal" 
            <keyedReference keyName="France"
            <keyedReference keyName="Spain"
            <keyedReference keyName="Acme Commodities Traders"
            <keyedReference keyName="Luxembourg"
            <keyedReference keyName="Germany, Federal Republic of"
The response document contains a <businessService> structure that has a logical grouping of web services by a business. In the case of Acme Trader, this grouping lists a number of web services that allow you to do get a commodity quote via email. The returned <businessService> has a single <bindingTemplate> that provides technical details of how to access the web service. The <accessPoint> is the web service endpoint URL.Here it is the email address:


Categorization of data is an important requirement of UDDI. Categorization permits the data in a UDDI registry to have numerous associations with items such as industry, product, or geographic code set. There are numerous categorization systems that can be used on data within UDDI. A <tModel> structure is used for each taxonomy categorization within UDDI. This means that each categorization has a tModel name and UUID that can be used to reference it. Although the tModel name is the same for all UDDI registries, the UUID for the tModel can vary between operator nodes. These systems are summarized in the following table:

Tutorial:In Depth Look at UDDI for the Web Service Developer Exam-b4-categorizationtaxonomies.jpg
Table: Supported Categorization Taxonomies


An identifier is a property type or keyword that is used to uniquely identify a business or specification. They can be applied equally to <businessEntity> and <tModel> structures. Identifiers, can be used as part of a search when doing a <find_business> or <find_tModel> request message.

Identifiers and are implemented similarly to categorizations. They are attached to <businessEntity> and <tModel> documents via an <identifierBag> structure. The <identifierBag> structure may have one or more <keyedReference> structures providing the name, value, and <tModel> UUID reference that is used to locate more information.
There are presently two general-purpose identifier schemes that have been incorporated into all operator nodes as well as other schemes. The following table lists the identifier types that form part of the core of an operator node.

Tutorial:In Depth Look at UDDI for the Web Service Developer Exam-b4-supportedidtypes.jpg
Table: Supported Identifier Types

tModel Documents

<tModel> documents are useful for the metadata information that they provide about a web service specification, categorization specification, or identifier specification. <tModel> documents form part of the core data structure in the UDDI specification and represent the most detailed information that a UDDI registry can provide about any specification.

If we return to our previous listing of Acme Traders, you can see that the CommodityQuote <businessService> has two <tModelInstanceInfo> documents within the <bindingTemplate>. Each <tModelInstanceInfo> document holds a UUID in the tModelKey attribute representing information about the supporting specification. There are additional tModelKey attributes for each <keyedReference> structure as part of the <categoryBag>. If we use a client to retrieve the <tModel> document for any of these UUIDs. The listing of the request would look like the following:

XML Code: Example of tModel Request Document
<uddi:get_tModelDetail generic="2.0"> 
And the resulting response would be as below:

XML Code: Example of tModel Response Document
<tModelDetail generic="2.0" operator="SYSTINET" xmlns="urn:uddi-org:api_v2">
   <tModel authorizedName="admin" operator="SYSTINET"
	<description xml:lang="en">E-mail based web service</description> 
		keyName="A transport tModel is a specific type of protocol"
In the response, the authorizedName attribute is the recorded name of the individual who published this <tModel> and the operator attribute is the certified name of the UDDI registry site that owns the master copy of the <tModel> data. Note that the tModelKey is the UUID of this <tModel> matches the tModelKey for the request document.

Publishing to a UDDI Registry

When you decide to publishing to a UDDI registry you will need functionality that allows you to do CRUD operations on the data in a UDDI registry. Below are the key technical differences between publishing and inquiring:

Authenticated access
All publishing messages require authenticated access. The process for authentication is specific to the operator node. Once you have authenticated credentials, your program can access any publishing message.

Different access point
Publishing message requests use a different access point than do inquiry messages. The HTTP protocol was suitable for inquiry messages, but HTTPS is required for all publishing messages.

Space limits
Operator nodes can impose space and registration restrictions on an individual or company. A site may decide to limit some users to one <businessEntity> structure and prevent them from inserting additional data without special permissions.

Operator node binding
As we mentioned earlier, when information is inserted at an operator node, that operator node becomes the owner of that data's master copy. All updates or changes to the data afterwards must be performed at the same operator node. Also UDDI does not have the functionality for resolving conflicts if there are duplicate entries at another operator node. For the Publisher API messages that require authentication, please check your UDDI documentation.

Errors and <dispositionReport> Documents

Errors can occur on any request message irrespective of whether they come from the Inquiry or Publishing API. The SOAP Fault <detail> message has a subelement, the <dispositionReport> document; that is defined in the UDDI schema. <dispositionReport> documents can be used for some non-error situations as a status indicator as well as all error code situations. The non-error <dispositionReport> documents are returned as part of a standard SOAP response for any UDDI delete_ message.

UDDI SOAP Faults are be returned for a number of reasons. These are the following:
  • expiration of an authentication token
  • a server that is busy and unable to handle requests
  • the use of invalid categorization and identifiers
  • unsupported APIs, etc.

There is full details on the error codes located in the Appendix A of the UDDI Programmer's API specification. An example of an error code for <businessEntity> documents while using Systinet's WASP UDDI Standard is shown below:

XML Code: Example of Publishing a New Web Service
<SOAP-ENV:Envelope xmlns:SOAP-ENV="">
          <ns0:Fault xmlns:ns0="">
              <dispositionReport generic="2.0" 
			operator="SYSTINET" xmlns="urn:uddi-org:api_v2">
                <result errno="10160">
                  <errInfo errCode="E_accountLimitExceeded">
                    An attempt to save more data than allowed.
Your program that interacts with a UDDI registry must be able to handle SOAP Faults and handle them appropriately. If you need to parse UDDI responses intelligently, the consider using the DOM API to parse a <dispositionReport> structure and then implement specialized actions to handle each of errCode codes appropriately.
The various libraries that provide APIs for using UDDI such as JAXR or Systinetís UDDI API capture SOAP Faults and convert them into a specialized exception. This action allows you to write a program that has a familiar try/catch block to handle SOAP Fault scenarios, rather than using the DOM API to parse a <dispositionReport>.

The Rest of the Publishing API

Using the rest of the Publishing API is easy to use. Here is a couple of recommendations for itís use:
For the UUID of one major data structure element, use the delete_ messages to destroy data in the registry.
To insert or update data in a UDDI registry, construct a valid data structure, such as a <businessEntity>, and then use one of the save_ messages.
When working with the Publishing API, keep a couple of points in mind:
Your application indicates the difference between a creation and an update by the value of a document's UUID fields on a save_ message. If a save_ message is used for updating an existing document in a UDDI registry, the value of the existing document's UUID is placed in the input document's UUID field. If a save_ message is used to create a new document in a UDDI registry, the UUID should be left blank.
Be careful when using the delete_ and save_ messages. If the structure you are updating has a number of subelements, such as a <businessEntity>, you can inadvertently destroy them by removing their containment. If you delete a <businessEntity>, it will delete all <businessService> and <bindingTemplate> elements contained within the <businessEntity>. It will not delete a <businessService> referenced by the <businessEntity>, which would occur only if the <businessService> is contained with a different <businessEntity>.
<tModel>documents are never fully destroyed. When you use the <delete_tModel> message, a <tModel> element saved in the registry is merely hidden. Hidden documents can be located through <get_tModelDetail> and <get_registeredInfo> messages, but will not be displayed by any find_ queries. This behavior ensures that the details associated with any <tModel> are still available to anyone who may currently implement the specifications referred by the <tModel>. <tModel> documents can be unhidden by using the <save_tModel> message.

Benefits of Abstraction APIs

Abstraction APIs that facilitate the process of writing programs that interact with UDDI. It provides an abstraction layer that simplifies publishing documents to UDDI.
An example of this is the Service Registry Proxy (SRP) that is part of the UDDI4J project at IBM. The example below demonstrates how to publish a new web service exposed by WSDL into a UDDI registry:

Java Code: Example of Publishing a New Web Service
// Java Document
// Create an active connection to a UDDI registry 
ServiceRegistryProxy srp = new ServiceRegistryProxy(

// Create a category list for an existing tModel (<categoryBag> document) 
CategoryList categoryList = new CategoryList(
// Create service provider (<businessService> document) 
ServiceProvider serviceProvider = new ServiceProvider(
				"Demi Credit", 
				"Financing Company", 
// Publish the service to UDDI 
In the listing, the ServiceRegistryProxy creates connections to an inquiry and publishing access point. The information is passed to the proxy for creating the needed connections, including authentication information in order for the system to return an authentication token. The CategoryList object creates the equivalent of a <categoryBag> document for a specific <tModel>. As WSDL <tModel> documents have a special categorization, the creation of a CategoryList instance and it being used as an input parameter to the ServiceProvider constructor creates this categorization. The ServiceProvider object is an abstraction of a <businessService> document. You can then use the ServiceProvider object to perform such actions as publish, unpublish, and find. These actions are transformed into SOAP messages that are sent to the UDDI server.

OK. Thatís it for UDDI. Next we move on to JAX-WS.