"Java" understands the WSDL of the UDDI registry

How to publish and find WSDL service descriptions

There are several uses for Web Service Description Language (WSDL). In particular, there are several ways in which WSDL can be used in the UDDI registry, depending on the needs of the application. In this 1th article (a total of three articles in this series), we will cover several different approaches to using WSDL in a UDDI registry.

Web Service Description Language (WSDL) is an XML language used to describe a Web service that describes a Web service as a set of network endpoints that operate on a message. A WSDL service description contains an abstract definition of a set of operations and messages, a specific protocol that binds to these operations and messages, and a network endpoint specification for this binding.

Unified Description Discovery and Integration (UDDI) provides a way to publish and find service descriptions. UDDI data entities provide support for defining business and service information. The service description information defined in the WSDL is supplemented by UDDI registry information. UDDI provides support for many different types of service descriptions. As a result, UDDI does not have direct support for WSDL and no direct support for any other service description mechanisms.

The UDDI organization, Uddi.org, has published an optimization method document titled using WSDL in UDDI registry 1.05(see Resources). This optimization method document describes some of the elements that describe how to publish a WSDL service in a UDDI registry. The purpose of this article is to increase this information. The main focus issue is how to map a complete WSDL service description to the UDDI registry, which is required by existing WSDL tools and runtime environments. The information in this article adheres to the approximate procedure outlined in the documentation for the optimization method and is consistent with the WSDL 1.1, UDDI 1.0, and UDDI 2.0 specifications (see Resources).

UDDI and WSDL Overview

Before describing the process of mapping a WSDL service description to a UDDI registry, it is important to understand the UDDI data type and the primary WSDL document type.

UDDI Data types

There are 4 main data types in the UDDI registry: businessentity, businessservice, bindingtemplate , and TModel. Figure 1 shows the relationships between all of these data types.

Figure 1. UDDI Data types

BusinessEntity provides information about the merchant and can contain one or more businessservice. This merchant is a service provider. The technical and business descriptions of WEB services are defined in Businessservice and its bindingtemplate. Each bindingtemplate contains a reference to one or more tModel. TModel is used to define the technical specifications of the service.

WSDL Document Type

To help publish and find WSDL service descriptions in the UDDI registry, WSDL documents are divided into two types: Service Interface (Services Interface) and service implementation (services implementations) (See Figure 2).

Figure 2. WSDL Document Type

The service interface is described by a WSDL document that contains the types, import, message, portType , and binding of the service interface and other elements. The service interface contains the WSDL service definition that will be used to implement one or more services. It is an abstract definition of a WEB service and is used to describe a particular type of service.

By using an import element, a service interface document can reference another service interface document. For example, a service interface that contains only the message and PortType elements can be referenced by another service interface that contains only this portType binding.

The WSDL service implementation document will contain the import and service elements. The service implementation document contains a description of the service that implements a service interface. At least one of the import elements will contain a reference to the WSDL service interface document. A service implementation document can contain references to multiple service interface documents.

The import element in the WSDL service implementation document contains two properties. The namespace property value is a URL that matches the targetnamespace in the service interface document. The Location property is a URL that references a WSDL document that contains the full service interface definition. The binding property of the port element contains a reference to a particular binding in the Service interface document.

The Service interface documentation is developed and published by the service interface provider . The service implementation document is created and published by the service provider . The two roles of the service interface provider and the service provider are logically separate, but they can be the same business entity.

Back to top of page

Publish and find WSDL descriptions

This section describes the process of publishing and finding a complete WSDL service description. A complete WSDL service description consists of a service interface and a service implementation document.

Because the service interface represents a reusable definition of the service, it is published as TModel in the UDDI registry. The service implementation describes an instance of the service. Each instance is defined using a WSDL service element. Each service element in the services implementation document is used to publish UDDI businessservice.

When a WSDL service description is published, a service interface must be published as a tModel before the service implementation is published as a businessservice.

Figure 3 contains an overview of mappings from WSDL to UDDI. I'll describe this mapping in the following sections.

Figure 3. Overview of mappings from WSDL to UDDI

Publishing the Service Interface

At the UDDI registry, the service interface is released as TModel. TModel is published by the service interface provider. Some elements in TModel are built using the information from the WSDL service interface description.

UDDI TModel

Table 1 defines the Create TModel step. A valid TModel reference to the WSDL service interface definition should be named with targetnamespace and must contain Overviewurl and categorybag settings.

Table 1: Steps to create a TModel

	UDDI tModel	WSDL Service Interface	description	required
1	Name	The targetnamespace property of the definitions element	The TModel name uses the target namespace setting of the service interface document. Names need to be consistent to ensure that only the information in the service implementation document is used to locate TModel.	Is
2	Description	The documentation element in the definitions element	The TModel description element is limited to only 256 characters. The English value of this element can be set according to the first 256 characters of the definitions element (the documentation element is associated with the definitions element in the Service interface document). If the documentation element does not exist, then the name attribute in the definitions element should be used.	Whether
3	Overviewurl	[Service Interface document URL and binding specification]	The location of the service interface document must be set in the Overviewurl element. If there is more than one binding in the Service interface document, the binding must be encoded in the URL.	Is
4	Categorybag	[Not Available]	The TModel categorybag must contain at least one keyed reference. This keyed reference must contain a reference to the uddi-org:types TModel, and the key name must be wsdlSpec . This entry treats TModel as a WSDL service interface definition.	Is

Example of mapping service interfaces to TModel

Listing 1 contains a sample WSDL service interface documentation. Values that are mapped to UDDI TModel are displayed in the Chart keyword.

Listing 1: Sample WSDL Service Interface

<?xml version= "1.0"? ><definitions name= "Stockquoteservice-interface" targetnamespace= "/http  Www.getquote.com/StockQuoteService-interface "xmlns:tns=" Http://www.getquote.com/StockQuoteService-interface " Xmlns:xsd= "Http://www.w3.org/2001/XMLSchema" xmlns:soap= "http://schemas.xmlsoap.org/wsdl/soap/" xmlns= "http// schemas.xmlsoap.org/wsdl/"> <documentation> standard WSDL Service interface definition for a stock quote Serv  Ice. </documentation> <message name= "Singlesymbolrequest" > <part name= "symbol" type= "xsd:string"/> < /message> <message name= "Singlesymbolquoteresponse" > <part name= "quote" type= "xsd:string"/> </mess age> <porttype name= "Singlesymbolstockquoteservice" > <operation name= "getquote" > <input messag E= "Tns:singlesymbolrequest"/> <output message= "Tns:singlesymbolquoteresponse"/> </operation> </     porttype> <binding name= "Singlesymbolbinding"      Type= "Tns:singlesymbolstockquoteservice" > <soap:binding style= "rpc" transport= "Http://sche Mas.xmlsoap.org/soap/http "/> <operation name=" GetQuote "> <soap:operation soapaction=" http://www.getquo Te.com/getquote "/> <input> <soap:body use=" encoded "namespace=" urn:single-symbol-stock-        Quotes "encodingstyle=" http://schemas.xmlsoap.org/soap/encoding/"/> </input> <output> <soap:body use= "encoded" namespace= "urn:single-symbol-stock-quotes" encodingstyle= "http// schemas.xmlsoap.org/soap/encoding/"/> </output> </operation> </binding> </definitions&gt ;

Key words:

Definitions―targetnamespace will be used as the name of the TModel. The contents of the documentation element will be used to describe the TModel.
Binding-The bound name is used to limit overviewurl.

Listing 2 contains the UDDI TModel created when the WSDL service interface definition is published. Values are displayed in the chart keywords.

Listing 2: UDDI TModel created based on the WSDL service interface

<?xml version= "1.0"? ><tmodel tmodelkey= "" >  <name>http://www.getquote.com/ stockquoteservice-interface</name>  <description xml:lang= "en" > Standard    Service interface Definition for a Stock quote service.  </description>  <overviewDoc>    <description xml:lang= "en" >      WSDL Service Interface Document    </description>    <overviewURL>      http://www.getquote.com/services/ Sqs-interface.wsdl#singlesymbolbinding    </overviewURL>  </overviewDoc>  < categorybag>    <keyedreference tmodelkey= "uuid:c1acf26d-9672-4404-9d70-39b756e62ab4"                    keyName= " Uddi-org:types "keyvalue=" Wsdlspec "/>    <keyedreference tmodelkey=" Uuid:d b77450d-9fa8-45d4-a7bc-04411d14e384 "                     keyname=" Stock Market Trading Services "                     keyvalue=" 84121801 "/>  </categoryBag></tModel>

Key words:

the name of the TModel―tmodel is set according to targetnamespace. The description is set based on the documentation element associated with the definitions element. The Overviewurl is set to the location that the WSDL service interface document can be accessed through the network, that is, http://www.getquote.com/services/SQS-interface.wsdl. It also contains a direct reference to a binding that is named Singlesymbolbinding in the service interface document. Since this is the only binding in the Service interface documentation, this reference to the binding is not required. Categorybag contains Wsdlspec entries and all other keyedreference,keyedreference that indicate the intent of this service interface description for commercial purposes.

Back to top of page

Publishing Service implementations

Service implementations are published as Businessservice with one or more bindingtemplate in the UDDI registry. Businessservice is published by the service provider.

UDDI Businessservice
A new businessservice is created for each service element defined in the services implementation document. The following table contains a list of businessservice elements that can be created by the WSDL service to implement the contents of the document.

	UDDI businessservice	description	required
1	Name	The name element of the Businessservice is set according to the service element's Name property in the document.	Is
2	Description	The description element is set based on the content of the documentation element in the service element. The English value of the description element is set according to the first 256 characters in the documentation element associated with the service element. If the documentation element does not exist, then the businessservice description element is not set.	Whether

UDDI bindingtemplate
The new bindingtemplate element is defined in Businessservice for each port element defined in the service element.

	UDDI bindingtemplate	description	required
1	description	If the port element contains a documentation element, then there is a description element that is based on the documenta The first 256 characters of the tion element are set.	no
2	accesspoint	for a SOAP or HTTP binding, Accesspoint is based on the extension associated with the port element. The Location property of the display element is set. This element will contain the URL, and the Urltype property is set according to the protocol in this URL. For protocol bindings that do not use the URL specification, you should use the Urltype property to indicate the type of the protocol binding, and the Accesspoint element should contain a value that can be used to locate a WEB service that uses the specified protocol.	is
3	tmodelinstanceinfo	bindingtemplate will contain one tMo for each tModel that you reference The Delinstanceinfo element. At least one Tmodelinstanceinfo element will contain a direct reference to the TModel that represents the service interface document.	is
4	overviewurl	overviewurl element may contain a direct reference to the service implementation document. References to this document are used only to provide access to human-readable documents. All other information in this document should be accessible through a UDDI data entity. By maintaining a direct reference to the original WSDL document, you can ensure that the document being published is the one returned by the lookup operation. If the document contains multiple ports, then this element should contain a direct reference to the port name. Because there may be multiple ports referencing the same binding, it is not enough to use only direct references in TModel. The port name is specified as the fragment identifier on Overviewurl. The fragment identifier is an extension of the URL, using the "#" character as a delimiter.	no

Example of a service implementation to businessservice mapping
Listing 3 contains an example of a WSDL service implementation document. The highlighted values are the values that are required to map the WSDL information to UDDI Businessservice and bindingtemplate. Values are displayed in the chart keywords.

Checklist 3:WSDL Service Implementation Example

<?xml version= "1.0"? ><definitions name= "StockQuoteService" targetnamespace= "http://www.getquote.com/ StockQuoteService "xmlns:interface=" Http://www.getquote.com/StockQuoteService-interface "xmlns:xsd="/HTTP/ Www.w3.org/2001/XMLSchema "xmlns:soap=" http://schemas.xmlsoap.org/wsdl/soap/"xmlns=" http://schemas.xmlsoap.org/    wsdl/"> <documentation> This service provides an implementation of a standard stock quote service.    The Web service uses the live stock quote service provided by xmltoday.com. The xmltoday.com stock Quote service uses an HTTP GET interface to request a quote, and returns an XML string as a resp    Onse. For additional information on what this service obtains the stock quotes, go to the xmltoday.com Web Site:http://www.xmltod  AY.COM/EXAMPLES/SOAP/STOCK.PSP. </documentation> <import namespace= "http://www.getquote.com/StockQuoteService-interface" location= "http ://www.getquote.com/wsdl/sqs-interface.wsdl "/> <service name= "StockQuoteService" > <documentation>stock Quote service</documentation> <port name= "SingleSym Bolserviceport "binding=" interface:singlesymbolbinding "> <documentation>single Symbol Stock Quote Ser vice</documentation> <soap:address location= "Http://www.getquote.com/stockquoteservice"/> &LT;/PORT&G  T </service></definitions>

Key words:

the Name property of the Service―service element is used as the names of the businessservice. The documentation element in the service element is used to describe the businessservice.
Import-The port name is appended to Overviewurl, and this overviewurl contains a reference to the service implementation document. The location of the service is used to set the Accesspoint in Bindingtemplate.

Listing 4 contains the UDDI businessservice definitions created based on the service implementation document. Categorybag should contain one or more keyedreference, which are used to classify the commercial use of the service intent. Values are displayed in the chart keywords.

Listing 4: UDDI Business Services created based on the WSDL service implementation

      <businessservice businesskey= "..." servicekey= "..." > <name>StockQuoteService</name> <descript Ion xml:lang= "en" > Stock Quote Service </description> <bindingTemplates> <bindingtemplate Binding       Key= "..." servicekey= "..." > <description> single Symbol Stock Quote Service </description> <accessspoint urltype= "http" > Http://www.getquote.com/singlestockquote </accessPoint> &L t;tmodelinstancedetails> <tmodelinstanceinfo tmodelkey= "[TModel Key for Service Interface]" > < instancedetails> <overviewURL> http://www.getquote.com/services/SQS.wsdl </    overviewurl> </instanceDetails> </tModelInstanceInfo> </tModelInstanceDetails> </bindingTemplate> </bindingTemplates> <categoryBag> <keyedreference tmodelkey= "uuid:db77450d -9fa8-45d4-a7bc-04411d14e384 "keyname=" Stock Market Trading Services "keyvalue=" 84121801 "/> </catego Rybag></businessservice>

Key words:

the name of the businessservice―businessservice is based on the WSDL service implementation of the service's name setting in the document. Description is set according to the documentation element in the service element.
bindingtemplate-its description is set according to the documentation element in the port element. Accesspoint is set according to the soap:address extension element. The tModelKey is set to the UUID of the TModel associated with the service interface document. You can use the Namespace property of the import element to position the TModel. Overviewurl is the location of the service implementation document. Because it is the only reference in this document, it does not contain a reference to the Singleservicequote port.

Back to top of page

Find WSDL Service Interface description

All WSDL Service Interfaces are published as TModel in the UDDI registry. Each of these tModel is categorized to identify them as WSDL service descriptions. UDDI Find_tmodel messages can be used to find tModel that have been divided into classes. When using the UDDI V1.0 API, the Find_tmodel messages listed in Listing 5 can be used to locate all WSDL service interface descriptions.

Listing 5: Finding the WSDL Service Interface description

<?xml version= "1.0"? ><find_tmodel generic= "1.0" xmlns= "Urn:uddi-org:api" >  <categoryBag>    <keyedreference tmodelkey= "uuid:c1acf26d-9672-4404-9d70-39b756e62ab4"                    keyname= "Uddi-org:types" Keyvalue= "Wsdlspec"/>  </categoryBag></find_tModel>

The Find_tmodel message returns a list of TModel keywords. Use get_tModelDetail a message to retrieve a specific service interface description. The Get_tmodeldetail message will return a tModel, such as the one listed in Listing 2.

After retrieving a tModel, you can use Overviewurl to retrieve the contents of the WSDL service interface document.

Additional keyedreference can be added to Categorybag to limit the TModel set returned in the response to this lookup request. The Find_tmodel message in Listing 6 can be used to locate all stock quote services defined using WSDL.

Listing 6: Finding the WSDL service interface for the desired commercial use

<?xml version= "1.0"? ><find_tmodel generic= "1.0" xmlns= "Urn:uddi-org:api" >  <categoryBag>    <keyedreference tmodelkey= "uuid:c1acf26d-9672-4404-9d70-39b756e62ab4"                    keyname= "Uddi-org:types" Keyvalue= "Wsdlspec"/>    <keyedreference tmodelkey= "uuid:db77450d-9fa8-45d4-a7bc-04411d14e384"                     Keyname= "Stock Market Trading Services"                     keyvalue= "84121801"/>  </categoryBag></find_tModel>

Back to top of page

Find WSDL Service Implementation description

The WSDL service implementation is published as Businessservice in the UDDI registry. Businessservice will contain one or more bindingtemplate. The businessservice is categorized so that it can be viewed as a WSDL-based service description. When using the UDDI V1.0 API, you must find a businessentity or a businessentity set to use the lookup API for Businessservice. Similarly, you must find a businessservice or a businessservice set in order to use the Find API to locate bindingtemplate.

Find UDDI Businessservice
There are two basic ways to find a service description. With a specific taxonomy, UDDI find_service messages can be used to find service descriptions, or they can be used to find service descriptions that implement a particular service interface.

When using the UDDI V1.0 API, you can emit the message in Listing 7 for a particular businessentity to locate the stock quote service to implement this businessservice. Additional keyedreference can be added to categorybag to narrow the scope of the service description returned in response to this message.

Listing 7: Finding the WSDL Service implementation description

<?xml version= "1.0"? ><find_service businesskey= "..." generic= "1.0" xmlns= "Urn:uddi-org:api" >  < categorybag>   <keyedreference tmodelkey= "uuid:db77450d-9fa8-45d4-a7bc-04411d14e384"                     keyName= "Stock Market Trading Services "                     keyvalue=" 84121801 "/>  </categoryBag></find_service>

Find_service messages can also be used to locate businessservice― the businessservice is an implementation of a particular service interface. The message in Listing 8 contains an example of a find_service message that will look for all businessservice in the businessentity, which implements the service interface for the stock quote service. Because the service interface is represented by TModel, Tmodelbag is used to specify the TModel keyword that the WSDL service interface is associated with the stock quote service.

Listing 8: Using Tmodelbag to find the WSDL service implementation description

<?xml version= "1.0"? ><find_service businesskey= "..." generic= "1.0" xmlns= "Urn:uddi-org:api" >  < Tmodelbag>    <tmodelkey>[tmodel key for WSDL service interface]</tmodelkey>   </tModelBag> </find_service>

The Find_service message returns a list of service keywords. The businessservice description can be retrieved using the get_serviceDetail message. The Get_servicedetail message will return a businessservice, such as the one in Listing 4.

After retrieving a businessservice, you can select a specific bindingtemplate to invoke the Web service. The Accesspoint in Bindingtemplate is the endpoint of the service. Overviewurl can be used to retrieve the contents of the WSDL Service implementation document, which may contain additional details about the implemented service.

Find UDDI Bindingtemplate
If Businessservice contains more than one bindingtemplate, it may be difficult to determine which bindingtemplate to use. find_bindingmessages can be used to locate the bindingtemplate that should be used.

Listing 9 contains a find_binding message that you can use to retrieve bindingtemplate that reference a specific tModel. This tModel can be associated with a specific binding in the WSDL service interface description.

Listing 9: Finding UDDI bindingtemplate

<?xml version= "1.0"? ><find_binding servicekey= "..." generic= "1.0" xmlns= "Urn:uddi-org:api" >  < Tmodelbag>    <tmodelkey>[tmodelkey for WSDL service interface]<tmodelkey/>  </tModelBag> </find_service>

This message will return one or more bindingtemplate, such as the one in Listing 10. After you have accessed bindingtemplate, the endpoints of the Web service are listed in Accesspoint. If Bindingtemplate is created from an existing WSDL service implementation document, then Overviewurl may contain a reference to this document. This document can be accessed to obtain additional, human-readable information about WEB services that cannot be found in the UDDI registry.

List 10:uddi bindingtemplate

<?xml version= "1.0"? ><bindingtemplate bindingkey= "" servicekey= "" >  <accessspoint URLType= "http" >    http://www.getquote.com/singlestockquote  </accessPoint>  <tModelInstanceDetails>    <tmodelinstanceinfo tmodelkey= "[TModel Key for Service Interface]" >      <instanceDetails>        < overviewurl>          http://www.getquote.com/services/SQS.wsdl        </overviewURL>      </ instancedetails>    </tModelInstanceInfo>  </tmodelinstancedetails></bindingtemplate >

Back to top of page

Summarize

This article has described the process of publishing and finding the full WSDL service description in the UDDI registry. The WSDL Service Interface description is published as a UDDI TModel, while the WSDL service implementation description is published as a UDDI businessservice. Figure 4 provides an overview of the mapping from the WSDL service interface and the service implementation document to the UDDI registry entry.

In the next article in this series, we will discuss the exact code required to use WSDL in a UDDI registry in 5 different scenarios that developers often encounter.

Figure 4: Overview of mappings from WSDL to UDDI

In the next article in this series, we will apply the procedures described in this article to different WSDL usage case studies. Each usage case study will illustrate how different types of WSDL service descriptions should be published in the UDDI registry.

http://www.ibm.com/developerworks/cn/webservices/ws-uwsdl/part1/