Identifiers

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

Identifiers and categorizations are implemented similarly. Identifiers are attached to <businessEntity> and <tModel> documents through an <identifierBag> structure. The <identifierBag> structure can have one or more <keyedReference> structures that provide the name, value, and <tModel> UUID reference for locating more information.

At this time, only two general-purpose identifier schemes have been incorporated into all operator nodes, but other schemes can be used as well. Table 6-5 lists the identifier types that are a core part of an operator node.

The Dun & Bradstreet D-U-N-S number is a unique nine-digit identification sequence. This sequence provides unique identifiers for single business entities, while linking corporate family structures. More information can be found at http://www.d-u-n-s.com.

Thomas Register

thomasregister-com:supplierID

This scheme provides identifiers for over 150,000 manufacturing and
e-commerce companies worldwide. More information can be found at http://www.thomasregister.com.

tModel

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

Looking at Demi Credit, we can see that the DCAmail <businessService> has a <bindingTemplate> with two <tModelInstanceInfo> documents. Each <tModelInstanceInfo> document contains a tModelKey attribute that is the UUID of a <tModel> document representing information about the supporting specification. There are also tModelKey attributes for each <keyedReference> structure that was part of the <categoryBag>. We can use the UDDISoapClient to retrieve the <tModel> document for any of these UUIDs. Let's get the <tModel> document for uuid:93335d49-3efb-48a0-acea-ea102b60ddc6, which is a specification implemented by the DCAmail web service. Here is the listing of Ch6_GetTModelDetail.xml, which is used as the body of the SOAP request:

The authorizedName attribute is the recorded name of the individual who published this <tModel>. The operator attribute is the certified name of the UDDI registry site that owns the master copy of the <tModel> data. The tModelKey is the UUID of this <tModel>; it matches the tModelKey for the request document. The <name> subelement is the recorded name of the <tModel>; it can be used as part of a search when doing a <find_tModel> request. The <description> subelement provides a specification's textual description. A <tModel> can have an optional <categoryBag> or <identifierBag> structure as well. Finally, a <tModel> can contain an optional <overviewDoc> subelement, which contains a URL that points to remote descriptive information.

Publishing to a UDDI Registry

Publishing to a UDDI registry involves any operation that would create, update, or destroy data in a UDDI registry. Here are some key technical differences between publishing and inquiring:

Authenticated access

All publishing messages require authenticated access. The process for authentication is not defined by the UDDI specification and is specific to the operator node. Given authenticated credentials, however, 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. For example, a site may limit some users to one <businessEntity> structure and prevent them from inserting additional data without special permissions.

Operator node binding

When information is inserted into an operator node, that site becomes the owner of that data's master copy. Any subsequent updates or changes to the data must be performed at the same operator node. UDDI does not have a mechanism for resolving conflicts if duplicate entries are made at another operator node.

The Publisher API messages that require authentication are listed in Table 6-6.

Given a valid authentication token and a <publisherAssertion> document, this message adds a <publisherAssertion> to an individual publisher's collection of assertions. A publisher assertion creates an association between two businesses. When the publishers of both businesses have added matching <publisherAssertion> documents to their collection, the relationship becomes publically visible.

<delete_binding>

<dispositionReport>

Given a valid authentication token and the UUID of one or more <bindingTemplate> documents, this message deletes the matching <bindingTemplate> documents from the UDDI registry.

<delete_business>

<dispositionReport>

Given a valid authentication token and the UUID of one or more <businessEntity> documents, this message deletes the matching <binding-Template> documents from the UDDI registry. Deleting these documents causes the deletion of any contained <businessService> or <bindingTemplate> data. Additionally, any <publisherAssertions> created with the UUID of this <businessEntity> will be deleted.

<delete_publisherAssertions>

<dispositionReport>

Given a valid authentication token and the UUID of one or more <publisherAssertion> documents, this message deletes the matching <publisherAssertion> documents from this publisher's collection. If other companies have created similar <publisherAssertion> documents, their documents remain part of their collection.

<delete_service>

<dispositionReport>

Given a valid authentication token and the UUID of one or more <businessService> documents, this message deletes the matching <businessService> documents from the UDDI registry.

<delete_tModel>

<dispositionReport>

Given a valid authentication token and the UUID of one or more <tModel> documents, this message logically deletes the matching <tModel> documents from the UDDI registry by marking them as hidden. The documents are not actually destroyed. Hidden <tModel> documents are not returned as part of a result of a <find_tModel> message, but are still accessible through <get_tModelDetail> and <get_registeredInfo> messages. <tModel> messages are not permanently destroyed, which allows any organization still using the <tModel> to get basic details about it.

<discard_authToken>

<dispositionReport>

Given a valid authentication token, this message tells an operator node to discard the active authentication session, effectively logging out the client. To perform additional Publishing API operations, a new authentication token must be retrieved from the operator node by using the <get_authToken> message.

<get_assertionStatusReport>

<assertionStatusReport>

Given a valid authentication token, this message returns a report that details all <publisher-Assertion> documents that have been created on any <businessEntity> documents managed by this publisher. This report returns <publisherAssertion> documents that were created by this publisher and other publishers. This query can search for complete or incomplete associations.

<get_authToken>

<authToken>

Given a username and password, this message retrieves an authentication token from an operator node to be used on other Publisher API messages.

<get_publisherAssertions>

<publisherAssertions>

Given a valid authentication token, this message returns a complete list of <publisherAssertion> documents that have been associated with the authenticated publisher account.

<get_registeredInfo>

<registeredInfo>

Given a valid authentication token, this message returns a complete list of <businessEntity> and <tModel> documents that are managed by the individual associated with the authentication credentials.

<save_binding>

<bindingDetail>

Given an authenticated token and one or more <bindingTemplate> documents, this message inserts or updates a UDDI registry with the <bindingTemplate> documents passed as input. This message can also update any associations made between a <businessService> document and a <bindingTemplate> document. This message returns a <bindingDetail> message that contains the final results of the call that reflect the information in the UDDI registry.

<save_business>

<businessDetail>

Given an authenticated token and one or more <businessEntity> documents, this message inserts or updates a UDDI registry with the <businessEntity> documents passed as input. This message can make sweeping changes to a UDDI registry; the changes may involve inserts, updates, and deletes of subdocuments contained within a <businessEntity>. Changes to an existing <businessEntity> can impact existing references to <publisherAssertion> documents, <businessService> documents, and <bindingTemplate> documents. This message returns a <businessDetail> message that contains the final results of the call that reflect the UDDI registry information.

<save_service>

<serviceDetail>

Given an authenticated token and one or more <businessService> documents, this message inserts or updates a UDDI registry with the <businessService> documents passed as input. This message can modify <businessService> data and any references to <bindingTemplate> structures. This message returns a <serviceDetail> message that contains the final results of the call that reflect the UDDI registry information.

<save_tModel>

<tModelDetail>

Given an authenticated token and one or more <tModel> documents, this message inserts or updates a UDDI registry. If a passed-in <tModel> documet refers to a <tModel> that was previously deleted (hidden), it will be made visible again. This message returns a <tModelDetail> message that contains the final results of the call that reflect the UDDI registry information.

<set_publisherAssertions>

<publisherAssertions>

Given an authenticated token and one or more <publisherAssertion> documents, this message updates a UDDI registry to contain a complete collection of <publisherAssertion> documents while deleting documents that are not present as part of the input. This message returns a<publisherAssertions> document that contains the current collection of <publisherAssertions> as they are stored in the UDDI registry.

Security and Authentication

Authentication with an operator node is typically straightforward. Most operator nodes implement a name/password scheme that allows you to retrieve an authentication token. Operator nodes that support the name/password scheme for authentication expose their authentication interface through the <get_authToken> message. Operator nodes do not have to support this scheme for authentication and can provide alternative techniques for allowing a client to get an authentication token. Those techniques are not documented by the UDDI specifications and are specific to the operator node. An operator node also has specific ways of registering new publishers and verifying their information. The only requirement that an operator node has to adhere to is that the authentication token returned must be a text value that can be inserted in subsequent XML messages.

The Systinet WASP UDDI Standard has a preconfigured username (admin) and password (changeit). We can obtain an authentication token by running the UDDISoapClient program with the Ch6_GetAuthToken.xml file as input and two command-line modifications:

First, the JDK java.net.URL class does not support HTTPS as a standard protocol. The Message.send( ) method in the Apache SOAP library requires a URL object as input, so enabling HTTPS is key. Enabling HTTP is done by including the -Djava.protocol.handler.pkgs=com.sun.net.ssl.internal.www.protocol option on the command line. Using this option assumes that you have installed the jsse.jar library. This library is installed as part of Systinet WASP UDDI; if you use a different UDDI package, you may have to install JSSE yourself. Second, since we are using the Publishing API, we must access a different URL than the default that is configured for inquiries. The publishing URL for Systinet WASP UDDI is https://localhost:8443/wasp/uddi/publishing/.

TIP:
Using the JSSE library directly is not for the weak of heart. In addition to setting up JSSE and enabling HTTPS as a valid protocol, SSL requires that your program have a valid client certificate to be used against the server. Fortunately, Systinet WASP UDDI Standard installs a client certificate for your use, but otherwise, you would have to create a new certificate using Java's keytool utility.

The real value of using a custom Java API such as Systinet's is apparent when you look at the difficulty of using the UDDISoapClient to generate HTTPS messages. Two complete round-trip SOAP invocations have to be made and you have to go through the rigmarole of configuring SSL appropriately on the client. Systinet's library handles this situation cleanly by providing one method that retrieves your authentication credentials and other methods that use the rest of the Publishing API.

Here is the Ch6_GetAuthToken.xml document that we send to the server to request an authentication token:

<uddi:get_authToken generic="2.0" userID="admin" cred="changeit" />

The <get_authToken> element doesn't have any subelements and passes the name and password as the userID and cred attributes, respectively. Here's the body of the SOAP response:

The response document contains an <authToken> element that has an <authInfo> subelement. The value of the <authInfo> subelement is a key that will be used as the authentication token on all other publishing messages. To write a program that makes a series of updates on a UDDI registry, you must parse the <get_authToken> response message and store the authentication token as a String object. Your program would then have to create a second SOAP message to perform an insert, an update, or a delete operation.

Errors and <dispositionReport> Documents

Errors can occur on any request message, whether they are part of the inquiry API or the Publishing API. UDDI errors are always returned as SOAP Fault messages. (For more information on SOAP Fault messages and their structure, refer to Chapter 4.) The subelement of a SOAP Fault <detail> message is a UDDI <dispositionReport> document; this document is defined in the UDDI schema. Despite being used for all error code situations, <dispositionReport> documents are also used in some non-error situations as a status indicator. Non-error <dispositionReport> documents are returned as part of a standard SOAP response for any UDDI delete_ message.

UDDI SOAP Faults can be returned for dozens of reasons: 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. A full listing of error codes is contained in Appendix A of the UDDI Programmer's API specification. Here is an error that I received one time when I tried to exceed my limit for <businessEntity> documents while using Systinet's WASP UDDI Standard:

A <dispositionReport> has a <result> subelement with an errno attribute. The <result> subelement also has an <errInfo> subelement with an errCode attribute. The value of the errCode attribute must be one of the error codes that are identified in Appendix A of the UDDI Programmer's API specification. In this example, the errCode value is E_accountLimitExceeded. The value of the <errInfo> element is a textual explanation of the error that can be displayed to a user.

When designing a program that interacts with a UDDI registry, your program needs to be prepared to handle SOAP Faults and react appropriately. If you want your program to parse UDDI responses intelligently, use the DOM API to parse a <dispositionReport> structure and then implement specialized actions to handle different errCode situations.

Abstraction APIs, such as the UDDI API provided by Systinet and JAXR, capture SOAP Faults and convert their contents 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>.

What About the Rest of the Publishing API?

Using the rest of the Publishing API is straightforward. If you have the UUID of one major data structure element, you can use the delete_ messages to destroy data in the registry. If you want 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.

Since this chapter has already covered the major talking points of every major UDDI data structure, demonstrating Publishing APIs in full form would be repetitive. At this stage, you have all the necessary tools to work with the UDDI Programmer's and Data Structure specifications.

When working with the Publishing API, keep a couple of points in mind:

Your program signals 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. For example, if you wanted to update a <businessEntity> document with a fictional UUID of 43, then you would create a <businessEntity> document, fill it with the contents you want stored in the registry, and then set this document's businessKey attribute to 43. However, if you wanted to insert a new registration into the registry, the businessKey value would be "".

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>. For example, if you want to update a <businessEntity> document using a save_ message, you might accidentally delete <businessService> and <bindingTemplate> structures in the process. If the existing <businessEntity> element stored in a UDDI registry has <businessService> or <bindingTemplate> structures, but the <businessEntity> document used as input to the save_ message does not have those same subelements, the <businessService> and <bindingTemplate> subelements will be destroyed automatically as part of the update process.

<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.