UDDI: Universal Description, Discovery, and Integration, Part 2

This excerpt from O'Reilly's Java Web Services focuses on how to program UDDI services.

Two APIs are described by the UDDI specification: the inquiry API and the Publishing API. They are accessed using the same techniques but use different XML documents, data structures, and access points. The inquiry API locates information about a business, the services a business offers, the specifications of those services, and information about what to do in a failure situation. Any read operation from a UDDI registry uses one of the inquiry API's messages. The inquiry API does not require authenticated access and is subsequently accessed using HTTP.

The Publishing API is used to create, store, or update information located in a UDDI registry. All functions in this API require authenticated access to a UDDI registry; the UDDI registry must have a logon identity, and the security credentials for this identity must be passed as a parameter of the XML document for each UDDI invocation. Because publishing requires authenticated access, it is accessed over HTTPS, with a different URL than the one used with the inquiry access point. Table 6-1 lists the inquiry and publishing access point URLs for some major operator nodes.

Several primary information types construct the XML documents used as input and output to UDDI invocations. This section shows these data structures along with the major APIs as defined by the UDDI specifications.

UDDI APIs are designed to be simple. All operations that a UDDI registry performs are synchronous, meaning that the requesting client blocks and waits until it receives a response message. Additionally, all operations have a simple request/response mechanism that gives them a stateless behavior. Therefore, using the UDDI APIs doesn't require a lot of complex ordering.

UDDI Data Structures

To understand the structure of the messages that are part of the API, you need a basic appreciation for the different data structures and XML formats that are used. This section discusses the major data structures that are passed as input and output parameters for major API messages. Figure 6-3 shows the relationships between the primary UDDI data structures.

Figure 6-3. Relationship of primary UDDI data structures.

A <businessEntity> structure represents a business's basic information. This information includes contact information, categorization, identifiers, descriptions, and relationships to other businesses. UDDI allows companies to establish relationships with one another. Many different types of relationships are possible. For example, a conglomerate can reference a subsidiary, or two companies can declare a partnership. In either case, each company must establish a unique <businessEntity> and separately establish its relationships to other companies that have their own <businessEntity> structures.

The <publisherAssertion> structure is used to establish public relationships between two <businessEntity> structures. A 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. Thus, a company can claim a business relationship only if its partner asserts the same relationship. One company's assertion about a business relationship isn't visible to the public until its partner creates a similar, but separate, <publisherAssertion> document for its own <businessEntity> structure. Thus, if Company A asserts a relationship with Company B (fromKey=A, toKey=B), then the relationship will become public when Company B asserts a relationship with Company A (fromKey=B, toKey=A).

A <businessEntity> contains one or more <businessService> structures. A <businessService> represents a single, logical service classification. A <businessService> element is used to describe a set of services provided by the business. These services can be web services or manual services such as a nonelectronic service. A <businessService> document is reusable (i.e., a <businessService> element can be used by several <businessEntity> elements). For example, GE might create an HR web service and publish that service as part of an "HR web service" <businessService> structure. Additionally, GE might choose to list each of its subsidiaries as a separate <businessEntity>, since each subsidiary has its own IT infrastructure. Doing so would allow the <businessEntity> structure for the Plastics division to reference the same "HR web service" <businessService> as the Chemicals division.

A <businessService> contains one or more <bindingTemplate> structures. A <bindingTemplate> contains pointers to technical descriptions and the access point URL, but does not contain the details of the service's specifications. A <bindingTemplate> contains 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 type of digital "fingerprint" for determining the specifics of how to interact with a particular web service. The <tModel> structure does not provide the web service's specification directly. Instead, it contains pointers to the locations of the actual specifications. Companies can use the information pointed to by a <tModel> to determine whether a web service is compatible with their business requirements.

UUID

Instances of these data structures are identified and referenced by a universally unique identifier, known as a UUID. UUIDs are assigned when the data structure is first inserted into the UUID registry. They are hexadecimal strings whose structure and generation algorithm is defined by the ISO/IEC 11578:1996 standard. This standard virtually guarantees the generation of a unique identifier by concatenating the current time, hardware address, IP address, and random number in a specific fashion. The Inquiry API uses the UUID to request a particular structure on demand.

<publisherAssertion> documents do not have UUIDs, however.

Browsing Basic Information

A series of messages allow a program to retrieve basic information about a business, a web service, or metadata about a specification that a web service supports. These messages all have SOAP messages whose XML body element begins with find. Table 6-2 lists the messages that can be used to retrieve basic information for searching purposes. The "Message name" column lists the name of the XML root element used as the body of the SOAP envelope on the call's request portion. The "Response document" column shows the name of the XML root element that is the body of the SOAP envelope for the response.

Table 6-2: XML documents used in browsing inquiry messages

Message name

Response document

Brief description

<find_binding>

<bindingDetail>

Given a UUID to a <businessService> structure, this message retrieves zero or more <bindingTemplate> structures within a single <bindingDetail> structure matching the criteria specified in the input arguments.

<find_business>

<businessList>

Given a regular expression, business category, business identifier, or <tModel>, this message retrieves zero or more <businessInfo> structures contained within a single <businessList> structure that meet the criteria specified in the input arguments.

<find_relatedBusinesses>

<relatedBusinessesList>

Given the UUID of a <businessEntity>, this message returns a list of UUIDs contained within a <relatedBusinessList> structure for the other businesses that have a relationship with this business.

<find_service>

<serviceList>

Given the UUID of a <businessEntity> and either the name of the service, the <tModel> of an implemented specification, or the service category, this message returns a list of all matching <businessService> documents contained within a <serviceList> structure.

<find_tModel>

<tModelList>

Given the a name, a category, or identifier, this message returns all matching <tModel> structures contained within a <tModelList> structure.

UDDI Response Structure

Many response messages return an XML document that contains zero or more of the primary UDDI data structures, rather than the data structures themselves. For example, the <find_business> message returns zero or more <businessInfo> structures, but does so in a <businessList> structure. The <businessList> structure is merely another data structure designed to hold zero or more other elements, similar to a Java Collection object. Don't confuse collection structures such as <businessList> with the primary UDDI data structures; they exist only for grouping.

The UDDI Programmer's API and UDDI Schema documents identify dozens of different structures used to make up the request and response messages. The Programmer's API identifies the structure of the request and response messages, paying particular attention to the input parameters for every request message. The UDDI Schema represents the same data structures, but provides datatyping and constraint information that can't be conveyed in the Programmer's API. When doing any development with UDDI, you should keep a copy of these two documents.

Traversing UDDI data structures can be complicated. To demonstrate this complexity, let's delve into the inner workings of the <find_business> message. The <find_business> message returns a <businessList> structure. Here's the definition of <businessList> from the UDDI Schema:

This definition says that a <businessList> contains a single <businessInfos> subelement (defined in the same schema, as indicated by the preceding uddi:) and three attributes named generic, operator, and truncated. Doesn't tell us much, does it? So, let's delve further. The schema for the <businessInfos> structure is:

This definition tells us that a <businessInfos> structure contains zero or more <businessInfo> subelements, which are also defined in the same schema document. minOccurs="0" and maxOccurs="unbounded" tell us that the included <businessInfo> elements can be repeated zero or more times. We now need to seek out the schema definition of the <businessInfo> structure, which is:

This structure contains three subelements and an attribute. The attribute, businessKey, is the UUID for this business. The first subelement, <name>, gives the name of the business. The second subelement, <description>, is zero or more text elements that describe what the business does. The third subelement, <serviceInfos>, is a grouping of <businessService> documents. To figure out what a <businessService> document is, we must search the schema for the <serviceInfos> element.