UDDI

Chapter 11 concluded with the introduction of Universal Description, Discovery, and Integration (UDDI) APIs. We will now look at what UDDI APIs are available, what they can do for us, and how they work.

UDDI Publishing API

The UDDI Publishing API is designed to publish all the data structures shown in Figures 11.7 to 11.11. It offers one publishing method for each data structure. The following is a list of all available methods:

 save_business and delete_business  save_service and delete_service save_binding and delete_binding save tModel and delete_tModel set_publisherAssertions, add_publisherAssertions and delete_publisherAssertions 

All the save, set, and add methods are meant to publish new or edit existing information on the UDDI registry. The delete methods will hide the previously published information from the registry users. We'll first cover all the save methods, and then see the delete methods.

The save_business Method

This method publishes the businessEntity structures conforming to Figure 11.7 (repeated here in Figure 13.1). An example of the XML structure for a save_business method call will look like the following:

 <save_business generic="2.0" xmlns="urn:uddi-org:api_v2">      <authInfo>An authorization token string.</authInfo>     <businessEntity businessKey = "">         <discoveryURLs>             <discoveryURL useType = "businessEntity">                 An HTTP URL pointing at an alternate discovery mechanism.             <discoveryURL>         <discoveryURLs>         <name>Name of a contact person</name>         <description>A short business description</description>         <contacts>             <contact useType = "Technical Support">                 <description>How this contact can be useful</description>                 <personName>Name of the contact</personName>                 <phone>Phone number</phonse>             </contact>         </contacts>         <identifierBag>             <keyedReference tModelKey = "dnb-com:D-U-N-S" keyName = "D-U-N-S"                 keyValue = "DUNS identification number"/>             <! Other keyed references.  >         </identifierBag>         <categoryBag>             <keyedReference tModelKey = "unspsc-org:unspsc:3-1"             keyName = "UNSPSC"                 keyValue = "UNSPSC code"/>             <! Other keyed references.  >         </categoryBag>         <! Other businessEntity structures.  >     </businessEntity> </save_business> 

Figure 13.1. The businessEntity structure.

The save_business method call shown here has two child elements: an authInfo element and a businessEntity element.

The authInfo Element

The authInfo element is used in all methods of the Publishing API. It is used to authenticate the publishing request and contains an authorization token. Therefore, you will need an authorization token before you can publish anything on a UDDI registry.

You can use a get_authToken method call to get an authorization token. This method call looks like the following structure:

 <get_authToken generic="2.0" xmlns="urn:uddi-org:api_v2">      userID = "login name"     cred = "password"/> 

The get_authToken method call takes two parameters, a login name and a password. The UDDI specification does not define the process through which an operator issues user login names and passwords. Therefore, each UDDI operator will design its own mechanism to issue login names and passwords.

Return value from the get_authToken is another XML structure that contains the required authorization token:

 <authToken generic="2.0" operator = "some UDDI operator"      xmlns="urn:uddi-org:api_v2">     <authInfo>An authorization token string.</authInfo> </authToken> UDDI users can discard authorization tokens by using the discard_authToken method: <discard_authToken generic="2.0" xmlns="urn:uddi-org:api_v2">     <authInfo>An authorization token string.</authInfo> </discard_authToken> 

The discard_authToken method will effectively end the secure session; that is, any subsequent method calls that use a discarded authorization token will be rejected.

UDDI also enables operators to implement their own mechanism of communicating authorization tokens to the publishers. For instance, an alternative technique is to exchange certificates instead of a login/password mechanism. In this case, it is optional for the UDDI operator to implement the get_authToken and discard_authToken methods.

The businessEntity Structure

A single save_business method call can contain any number of the businessEntity elements to be published, each conforming to the structure of Figure 13.1.

All the businessEntity substructures have been well explained in the discussion associated with Figure 11.7. The intent here is just to explain a few points.

The businessKey attribute of the businessEntity element in the save_business call shown previously is an empty string. The empty string means that we are publishing a new businessEntity structure. If we want to edit or update an existing businessEntity structure, we will pass its businessKey value along with the save_business call.

Also look at the discoveryURLs child element inside the businessEntity structure, which is a collection of URLs that can be used to point to the same businessEntity structure that you are publishing. This is useful if you have also published your business at other (probably non-UDDI) data repositories and discovery mechanisms, and you want your UDDI version of the business to point to other places where the same information can be found.

Another point to be noticed is that Figure 13.1 includes a collection of businessService elements that we have not shown in our save_business call. You may include businessService elements within the same call, or you may use separate save_service calls (explained in the next section) to publish businessService structures. If you include businessService elements within a businessEntity structure, you can publish both in the same save_business call. Moreover, as depicted in Figure 11.8 (repeated here as Figure 13.2), a businessService structure can in turn contain one or more bindingTemplate structures. Therefore, the same save_business call can publish all structures in one go. This shows that save_business has the broadest publishing scope.

Figure 13.2. The businessService structure.

The save_business method returns a businessDetail message as shown here:

 <businessDetail generic="2.0" operator = "some uddi operator"      xmlns="urn:uddi-org:api_v2">     <businessEntity businessKey="F5E65…">         <! Content of the businessEntity structure.  >     </bindingTemplate>     <! Other businessEntity elements.  >  </bindingDetail> 

The businessDetail structure contains a number of businessEntity elements that reflect the information you have just published.

Notice that we passed an empty string as the value of the businessKey attribute with the save_business call. The UDDI registry generated the businessKey and returned the same to us. The businessKey attribute is not an empty string in the businessDetail message shown here.

The save_service Method

This method call publishes the businessService structures of Figure 13.2. The following is a typical method call:

 <save_service generic="2.0" xmlns="urn:uddi-org:api_v2" >      <authInfo>An authorization token string.</authInfo>     <businessService serviceKey =""             businessKey="F5E65…">         <name>The name of the service.</name>         <description>             Textual description of the Binding Template.         </description>         <categoryBag>             <keyedReference tModelKey = "unspsc-org:unspsc:3-1"                     keyName = "UNSPSC"                     keyValue = "UNSPSC code"/>             <! Other keyed references.  >         </categoryBag>     </businessService>     <! Other businessService elements. > </save_service> 

The save_service method has the same logical structure as that of the save_business call. There is an authInfo element for authorization, followed by a number of businessService elements that need to be published.

The businessService element contains a businessKey as well as a serviceKey. The businessKey attribute refers to the parent businessEntity that contains this businessService structure.

The save_service element method returns a serviceDetail message, as shown here:

 <serviceDetail generic="2.0" operator = "some uddi operator"      xmlns="urn:uddi-org:api_v2">     <businessService businessKey="F5E65…" serviceKey="3D21…">         <! Contents of the businessService structure. >     </businessService>     <! Other businessService elements. > </serviceDetail> 

The save_binding Method

This method publishes the bindingTemplate structure of Figure 11.9 (repeated here as Figure 13.3). The following is a typical save_binding method call:

 <save_binding generic="2.0" xmlns="urn:uddi-org:api_v2" >      <authInfo>An authorization token string.</authInfo>     <bindingTemplate bindingKey = ""         serviceKey = "key of the parent businessService">         <description>             Textual description of the Binding Template.         </description>         <accessPoint URLType = "http">             www.mySOAPServices.com/SOAPServer         </accessPoint>         <tModelInstanceDetails>             <tModelInstanceInfo tModelKey = "The tModel Key">                 <description>                     Textual description of this tModel instance.                 </description>                 <instanceDetails>                     <description>                         Textual description of the instance details.                     </description>                     <overviewDoc>                         <description>                             Textual description of this overviewDoc.                         </description>                         <overviewURL>                             URL of our WSDL file that describes                             the interface that our SOAP server is expecting.                         </overviewURL>                     </overviewDoc>                 <instanceDetails>             </tModelInstanceInfo>         </tModelInstanceDetails>     </bindingTemplate>     <! Other binding templates.  > </save_binding> 

The save_binding method call shown here has two child elements. The first is the authInfo element that we have already discussed in the save_business method call.

The second is a complete instance of bindingTemplate structure shown in Figure 13.3 that we want to save (publish) using the save_binding method call. A single save_binding call can have one or more bindingTemplate structures (we have shown just one).

Figure 13.3. The bindingTemplate structure.

The bindingTemplate structure shown previously has two attributes and three child elements. The two attributes are actually two keys. The first is a bindingKey, which identifies the bindingTemplate that you are publishing. If you want to update an existing bindingTemplate, you will provide its key. If you are publishing a new bindingTemplate, you will pass an empty string as the value of the bindingKey attribute.

The serviceKey identifies the registered businessService object that is the parent of the bindingTemplate being published.

The three child elements are description, accessPoint, and tModelInstanceDetails. The description element is simply a textual description of the binding template.

The accessPoint element provides a URL that is the address of a location where an actual service is deployed. The service might be in any form: it might be a SOAP-based Web Service (the URL points to a SOAP server), a Web page, a customer service phone, fax number, or an email address. The URLType attribute tells the type of the service. Its possible values are mailto, http, https (secure HTTP channel), ftp, fax, phone, or other (any other type). The bindingTemplate structure shown previously assumes a SOAP-over-HTTP Web service, so we have specified http as the URLType and included a SOAP server address as the content of accessPoint element.

The tModelInstanceDetails structure acts as a technical fingerprint of the binding template, and explains what you can expect to be waiting for you when you visit the URL specified by the accessPoint. To explain the technical details of the binding template, the tModelInstanceDetails contains one or more tModelInstanceInfo structures (again, we have shown just one). All the tModelInstanceInfo structures together inside a tModelInstanceDetails structure define a single technical fingerprint.

Each tModelInstanceInfo structure contains a tModelKey attribute that refers to a tModel structure (refer to Figure 11.10, repeated here as Figure 13.4, and the accompanying discussion in Chapter 11).

Figure 13.4. The tModel structure.

The tModelInstanceInfo structure might also optionally contain an instanceDetails substructure. Although a tModel provides an abstract service description, an instanceDetails element will provide implementation-specific details (if any) relative to the tModel. The overviewDoc child element holds the overviewURL, which points to a resource that describes the implementation-specific details of the tModel instance. In the case of WSDL and SOAP-based Web services, the overviewURL will point to a WSDL file.

The save_binding method call returns a bindingDetail structure that contains the bindingTemplate that is published as a result of the save_binding method call:

 <bindingDetail generic="2.0" operator = "some uddi operator"      xmlns="urn:uddi-org:api_v2">     <bindingTemplate bindingKey="F5E65…" serviceKey="E4D6…" >         <! Content of the binding template.  >     </bindingTemplate>     <! Other binding templates.  >  </bindingDetail> 

The save_tModel Method

This method publishes a tModel structure. Recall the tModel structure of Figure 13.4 and the associated discussion in Chapter 11.

The following is how a save_tModel method call looks:

 <save_tModel generic="2.0" xmlns="urn:uddi-org:api_v2" >      <authInfo>An authorization token string.</authInfo>     <tModel tModelKey = "">         <name>A logical and meaningful name of the tModel</name>         <description> Textual description of the tModel. </description>         <overviewDoc>             <description>                Textual description of this overviewDoc.             </description>             <overviewURL>                 URL to a file that describes                 details of how this tModel fits in                 the Web Service description.                 It may refer to a WSDL file.             </overviewURL>         </overviewDoc>         <identifierBag>             <keyedReference tModelKey = "dnb-com:D-U-N-S" keyName = "D-U-N-S"                 keyValue = "DUNS identification number"/>             <! Other keyed references.  >         </identifierBag>         <categoryBag>             <keyedReference tModelKey = "unspsc-org:unspsc:3-1"                 keyName = "UNSPSC"                 keyValue = "UNSPSC code"/>             <! Other keyed references.  >         </categoryBag>     </tModel>     <! Other tModels.  > 

A single save_tModel method call can include any number of tModel structures. The XML code block given here shows only one.

In addition to the name and description child elements already discussed, a tModel structure also contains an overviewDoc substructure. It is the same substructure that you saw in the save_binding discussion (inside the instanceDetails structure). Note that when an overviewDoc substructure appears inside an instanceDetails structure, it provides information about a particular instance of a tModel. On the other hand, when it appears inside a tModel structure, it contains information about the abstract tModel definition.

The save_tModel method returns a tModelDetail structure, which is a simple structure that contains the tModel structures published by the save_tModel method:

 <tModelDetail generic="2.0" operator = "some uddi operator"      xmlns="urn:uddi-org:api_v2">     <! List of tModels.  > </tModelDetail> 

The set_publisherAssertions and add_publisherAssertions Methods

The set_publisherAssertions method call publishes one or more publisherAssertion structures, which represent relationships between two different businessEntities. A single call to set_publisherAssertions manages all the tracked relationship assertions associated with an individual publisher account. The set_publisherAssertions method call uses the following XML structure:

 <set_publisherAssertions generic="2.0" xmlns="urn:uddi-org:api_v2" >      <authInfo>An authorization token string.</authInfo>     <publisherAssertion>         <fromKey>F5E65…</fromKey>         <toKey>A237B…</toKey>         <keyedReference tModelKey="uuid:34D5…" keyName = "Holding Company"             keyValue = "parent-child" </keyedReference>     </publisherAssertion>     <! Other publisherAssertion elements.  > </set_publisherAssertions> 

The fromKey and toKey elements are the unique keys of the first and second businessEntities, respectively, which are being asserted to become related to each other. The keyedReference element defines the actual relationship.

You can also use the add_publisherAssertions method instead of the set_publisherAssertions method shown earlier (the structure is exactly the same; you just need to replace the method name). The add_publisherAssertions method adds one or more assertions to the existing collection of assertions.

Note that to make the relationship visible on the UDDI registry, both businessEntities have to publish exactly the same asserting information.

How To Delete Data From a UDDI Registry

You have seen the five save_XX method calls. There are also five corresponding delete_XX method calls available, each meant to delete a data structure from the UDDI registry. The five delete methods are

 delete_binding  delete_business delete_publisherAssertions delete_service delete_tModel 

All the delete_XX methods are similar to each other. They just need all the authentication tokens and keys that can uniquely identify the object that needs to be deleted. For example, the delete_business method looks like

 <delete_business generic="2.0" xmlns="urn:uddi-org:api_v2" >      <authInfo>An authorization token string.</authInfo>     <businessKey>KB2</businessKey>     <! Other businessKey elements  > </delete_business> 

Only the delete_publisherAssertions is different from the rest. It takes the all the assertion structures that are to be deleted:

 <delete_publisherAssertions generic="2.0" xmlns="urn:uddi-org:api_v2" >      <authInfo>An authorization token string.</authInfo>     <publisherAssertion>         <fromKey>F5E65…</fromKey>         <toKey>A237B…</toKey>         <keyedReference tModelKey="uuid:34D5…" keyName = "Holding Company"             keyValue = "parent-child" </keyedReference>     </publisherAssertion>     <! Other publisherAssertion elements that need to be deleted.  > </set_publisherAssertions>