White Papers

Consuming Web Services Through UDDI, SOAP And Weblets

Introduction

Web Services in the Microsoft .NET Framework make it easy to write components that communicate using HTTP GET, HTTP POST, and SOAP. Consumers of a Web Service do not need to know anything about the platform, object model, or programming language used to implement the service; they only need to understand how to send and receive SOAP messages (HTTP and XML).

Since the decentralized nature of Web Services enables both the client and the Web Service to function as autonomous units, there are countless ways to consume a Web Service. For example, a call to a Web Service can be included in a Web application, a middleware component, or even another Web Service.

This article provides a general overview of UDDI and describes how to consume web services through UDDI, SOAP and light-weight components (referred to here as Weblets).

Introduction To UDDI

UDDI, acronym for Universal Description Discovery and Integration is the name of a group of web-based registries that expose information about a business or other entity and its technical interfaces (API’s). UDDI provides a way for businesses to publish information about their own services and find services they need from other businesses.

UDDI Business Registry

The UDDI Business Registry is a global, public, online directory that gives businesses a uniform way to describe their services, discover other companies’ services, and understand the methods necessary to conduct e-business with a particular company. UDDI Project recently released second version of the UDDI Specification (on June 2001). The key features of the new version are support for complex organizations, improved internationalization, additional categorization and identifier schemes, and richer search capabilities. The UDDI Business Registry is an implementation of the UDDI version 2 specifications. Public UDDI registries are now fully operational.

Is There A Charge For Using The UDDI Registry?

There is no charge for using the services published in the registry. The goal of the free business registry is to enable companies to do business with new or current partners easily over the Web using XML.

Operator Sites

Operator Sites are the websites that maintain the public UDDI Business Registry. Microsoft and IBM are the companies that serve as operators of the registry at present. Ariba, which was also one of the former registry operator has now shifted to be a registrar. Hewlett-Packard Co. has signed on as an operator, and its site is expected to go live by the end of the year. Companies can register with any node. Though the registry sites will be in physically different locations, they will contain the same information. And also the common set of SOAP APIs are supported by all the nodes.

Operator Sites

How UDDI Works

Software companies, standards bodies, and programmers populate the registry with descriptions of different types of services, they support.
UDDI Business Registry assigns a programmatically unique identifier to each service and business registration.
Marketplaces, search engines and business applications query the registry to discover services at other companies.
Business uses this data to facilitate easier integration with each other over the Web.

Technical Overview

The Universal Description, Discovery and Integration (UDDI) specifications consist of an XML schema for SOAP messages, and a description of the UDDI API specification. Together, these form a base information model and interaction framework that provides the ability to publish information about a broad array of Web Services.

Four Data Structure Types In The UDDI Registry

The core information model used by the UDDI registries is defined in an XML schema. The UDDI XML schema defines four core types of information. These are: business information, service information, binding information, and information about specifications for services.

Data Types in UDDI Registry

Registry Data

There are two types of information that can be registered in the UDDI Base Registry.

Business Registration details
Service Type Registration details

Business Registration

Conceptually, the information provided in a UDDI business registration consists of three components: 'white pages' including address, contact, and known identifiers; 'yellow pages' including industrial categorizations based on standard taxonomies; and 'green pages', the technical information about services that are exposed by the business. Green pages include references to specifications for Web Services, as well as support for pointers to various file and URL based discovery mechanisms if required.

Registry Data

Service Type Registration

The Service Type Registration contains the following info

Pointer to the namespace where service type is described.
Identifier for who published the service.
Identifier for the service type registration called at ModelKey, that is used as a signature by the websites that implement those services.

Design And Architecture Of Registry APIs

Accessing UDDI Registry programmatically may be accomplished via APIs that comes with the UDDI SDK Toolkit. The programming APIs for UDDI are based on Extensible Markup Language (XML). There are two types of APIs in the UDDI.

Publishers API
Inquiry API

The UDDI Programmers API Specification defines approximately 30 SOAP messages that are used to perform inquiry and publishing functions against any UDDI compliant service registry.

Publishers API

They define the calls needed for interactions between the programs and the UDDI registry for the purpose of storing or changing data in the registry. Authenticated access is required to use publishers API.


API calls to save information in registry	save_business save_service save_binding save_tModel
API calls to delete information from registry	delete_business delete_service delete_binding delete_tModel
API calls that takes care of security	get_authToken discard_authToken

Inquiry API

Inquiry APIs define the calls through which program can access the registry and read information from the registry. No authentication is required to make use of the Inquiry API functions.


API calls to search the registry	find_business find_service find_binding ind_tModel
API calls to get details from registry	get_businessDetail get_serviceDetail get_bindingDetail get_tModelDetail

SOAP Messaging

The APIs interact with the operator sites using SOAP through standard HTTP-POST protocol.

The SOAP messages can be traced by setting the trace property of the RequestManager object to true and specifying the trace path where the trace messages are to be stored.

Example

The following figure shows the SOAP message that travels across the wire on calling the Inquiry API method, find_business().

SOAP message that travels on invoking find_business() inquiry API

The UDDI server responds with a BusinessList object on receiving this UDDI SOAP request as, shown in the figure below.

Response SOAP message containing BusinessList on invoking find_business() inquiry API

Error Handling

The RequestManager object has three properties that are used for reporting the errors: UDDIErrno, UDDIErrorCode and UDDIErrorText. If any error occurs while processing the UDDI API calls, a SOAP Fault will be returned to the caller containing these values. Errors that are not reported by way of SOAP Faults are reported using the dispositionReport structure.

Reporting Success

Successful process of the request is indicated via UDDIErrno: 0 and UDDIErrorCode: E_success.

Reporting Errors With The Disposition Report Structure

All application errors are communicated via the use of the SOAP FAULT structure. The following figure shows how an error generated on behalf of invalid key is reported to the user, using DispositionReport structure.

SOAP message containing fault payload on encountering error

Reporting Critical Errors

Critical errors like connection broken unexpectedly while interacting with the registry or some other technical errors that occurred while processing the request are reported with the Error number 10500 and fault code, E_FatalError.

Error Reporting Account Limit Exceeded

One can publish a maximum of four businesses in the UDDI Registry with his user account. So if he tries to publish more than that, UDDI reports with a error number 10610 and fault code E_accountLimitExceeded.

UDDI And .NET

Microsoft's .Net framework aims to transform applications into services that get swapped over the Web. But if there are no Web sites available for exchanging services, the idea will miss its target. Thus, Microsoft is integrating support for UDDI into the .NET Platform, insuring that standards and industry cooperation are the basis for the next generation Internet.

Consumption Of A .NET Webservice Through UDDI

Topic: Dynamic consumption of webservices published in the UDDI Registry by an ASP.NET client

Let us see a demo on how an Asp.NET client uses the UDDI Registry to dynamically access the web services published in it.

Step 1

Searching The UDDI Registry For Businesses

The web page below, Search1.aspx searches the UDDI (Test) registry for the specified search text and search type and brings the list of businesses in the registry that matches the specified search criteria.

The inquiry API call find_business() is used to get the business list from the UDDI registry matching the search text. In this case, it lists companies that match the search text ‘Calsoft’. There is only one business matching the name ‘Calsoft’ in the UDDI Registry, and that is listed as shown in the page.

Search1.aspx (Searches UDDI Registry for the specified search text)

The code snippet that searches the registry and fetches the list of businesses matching the search criteria is as follows

Protected Sub Submit_Click(ByVal sender As System.Object, ByVal e As System.EventArgs)

Dim Search_Text, Search_Type As String
				Dim env As New UDDIEnv.Envelope()
				Dim reqmgr As New UDDIEnv.RequestManager()
				Dim rspenv As New UDDIEnv.Envelope()
				Dim inqreq As New UDDI10.find_business()
				Dim inqres As New UDDI10.businessList()
				Dim result As UDDI10.businessInfo
				
				On Error Resume Next 
				
				'Get the Search Text and Search Type
				
				Search_Text = Request.Form("tSearchText")
				Search_Type = Request.Form("dSearchType")
				
				'Set the envelope to the find_business() template
				env.Plugin = inqreq
				'Set the businessname to Search_Text
				inqreq.name = trim(Search_Text)
				'Set the mode to Test thereby uses 
				'http://test.uddi.microsoft.com
				reqmgr.Mode = UDDIEnv.UDDIMode.test
					 
				'Calls UDDI registry for the specified type
				'and brings the Business List matching the text
					 
				rspenv = reqmgr.UDDIRequest(env)
				   
				'On successful getting the Business List
				
				 If (reqmgr.UDDIErrno = 0) Then
					rspenv.Plugin = inqres
					Dim business_count As Integer
					business_count = 1
				
				If (inqres.businessInfos.count >= 1) Then
					Do While business_count <= inqres.businessInfos.count
					result = inqres.businessInfos.businessInfo.
									Item(business_count)
					‘Displays the Business Name, result.name
					Loop
					Else
					‘Displays No Businesses found 
					'matching the search criteria
				End If
				Else
				Response.Write("Error Text : " & reqmgr.UDDIErrorText)
				End If
				
				If (Err.Number <> 0) Then
					Response.Write(Err.Description)
					End If
				End Sub

Step 2

Finding Whether The Business Exposes Any Compatible Webservices

The following web page (ConvertDocument1.aspx) is reached on clicking the Business Name “Calsoft” in the previous page. This page gets the business details associated with the business “Calsoft”, using the inquiry API call, get_businessDetail().

Then, it lists the services that are exposed by the business and says whether it is compatible to be invoked. This application supports only DotNet webservices to be called.

ConvertDocument1.aspx (Lists the services exposed in the specified business)

Looking at the above page, you can see that the business by name, “Calsoft” exposes four services: Document Conversion, Math Service, E-Mail Web Service and File Upload of which only the first three are compatible.

The code snippet that corresponds to the above page ConvertDocument1.aspx, which brings the list of web services exposed by the Business is as below

Protected Sub ConvertDocument1_Load
				(ByVal Sender As System.Object, ByVal e As System.EventArgs)
				If Not IsPostback Then 
				' Evals true first time browser hits the page
				
				Dim envdom As New MSXML2.DOMDocument()
				'Set the RequestManager to Test Repository http://test.microsoft.com
				reqmgr.Mode = UDDIEnv.UDDIMode.test
				
				'Get the BusinessDetail corresponding to the BusinessKey
				envdom.loadXML("
				
				"
				& request.querystring("BusinessKey") &
				"
				")
				
				envdom.save("c:\getbusinessDetail.xml") 
				env.Load("c:\getBusinessDetail.xml") 
				'Send the request getBusinessDetail() to Registry 
				getResp = reqmgr.UDDIRequest(env)
				 'On No error from the Registry If reqmgr.
				 UDDIErrno = 0 Then 
				 'Associate a businessDetail object with the response 
				 getResp.Plugin = bizDet 'now get the detail data 
				 desired using the document object 
				 Dim business As UDDI10.businessEntity 
				 Dim service As UDDI10.businessService 
				 Dim service_desc As UDDI10.Description 
				 Dim binding_template As UDDI10.bindingTemplate
				 Dim service_url As String 
				 If (bizDet.businessEntity.Count > 0) Then 
				 no_services = bizDet.businessEntity(1).
				 businessServices.count 
				 If no_services = 0 Then 
				 ‘Display No Service Exists 
				 in the Business Else For serviceindex = 1 To no_services
				 Display the Service Name and Description 
				 Next no_bindings = service.bindingTemplates.count 
				 For bindingindex = 1 To no_bindings 
				 binding_template = service.bindingTemplates. 
				 bindingTemplate.Item(bindingindex) 
				‘Fetch the url of the service service_url = 
				 binding_template.accessPoint. accessPoint.ToString() 
				‘From the Url, identify whether the service ‘is compatible
				 to be accessed and display 
				 Next 
				 End If 
				 End If 
				 End If 
				 End Sub

Step 3

Accessing The WebService

In step 2, we got the list of web services exposed by the business. The inquiry API call, get_businessDetail() in the previous step gets the binding details of the service, which will have the access point URL of the service in it. The access point Url of the “Document Service” is http://203.129.222.82/ado.net/PdfService/Service1.asmx

Case 1: Accessing “Document Service” exposed by Calsoft :The webservice “Document Service” converts the documents from various formats to PDF format. It exposes one method namely “Convert Document”. The method accepts the Url of the document to be converted as one of its parameters. It then uses an API call, UrlDownloadToFile() to download the document passed as Url location by the client, converts it to PDF, hosts it and passes the Url of the converted PDF file back to the client.

To summarize the steps to be followed to access this service

The service description of the service “Document Conversion” is shown in the figure below

Service Description of the service, “Document Service”

Parse the XML file loaded in the DOM object and extract the following information to invoke the service

Web methods exposed by the service
The input parameter name of the web methods and their data type
The return data type of the web method

Having known the above information, the web page (InvokeService.aspx) is built as shown in the figure below.

InvokeService.aspx (Displays the web methods, input parameters & data types and their return types found in the web service)

This service, “Document Service” exposes only one web method named “ConvertDocument”, that accepts six parameters: JobId (int), Source_Url (string), Dest_Ip (string), Dest_Port (string), DocType (string) and Pdf_Filename (string).

Enter the input values to the parameters of the method “ConvertDocument” as per their data types.

The SOAP request message is built using the XMLDOM object, that will contain the method “ConvertDocument” of the webservice carrying the input parameters and their values entered by the client as shown below.

'Create an instance of XMLDOM object
				Set xmldom = CreateObject("Microsoft.XMLDOM")
				
				'Build the SOAP Request Payload
				Set pi = xmldom.createProcessingInstruction
				("xml", " version=""1.0""")
				xmldom.insertBefore pi, xmldom.childNodes.Item(0)
				Set objXMLroot = xmldom.createNode
				(1,"SOAP:Envelope",
				  "http://schemas.xmlsoap.org/soap/envelope/")
				xmldom.appendChild (objXMLroot)
				objXMLroot.setAttribute
				"xmlns:soapspenc",
				  "http://schemas.xmlsoap.org/soap/encoding/"
				objXMLroot.setAttribute
				"xmlns:xsi",
				  "http://www.w3.org/1999/XMLSchema-instance"
				objXMLroot.setAttribute
				"xmlns:xsd",
				  "http://www.w3.org/1999/XMLSchema"
				Set objxmlbody = xmldom.createElement("SOAP:Body")
				xmldom.documentElement.appendChild (objxmlbody)
				Set objxmlmethod1 = xmldom.createNode
				(1,"ConvertDocument", "http://tempuri.org/")
				objxmlbody.appendChild (objxmlmethod1)
				Set objxmlparam1 = xmldom.createNode
				(1, "JobId", "http://tempuri.org/")
				objxmlparam1.Text = Trim(tJobid.Text)
				objxmlmethod1.appendChild (objxmlparam1)
				Set objxmlparam2 = xmldom.createNode
				(1,"Source_Url", "http://tempuri.org/")
				objxmlparam2.Text = Trim(tSource.Text)
				objxmlmethod1.appendChild (objxmlparam2)
				Set objxmlparam3 = xmldom.createNode
				(1,"Dest_Ip", "http://tempuri.org/")
				objxmlparam3.Text = Trim(tDest_ip.Text)
				objxmlmethod1.appendChild (objxmlparam3)
				Set objxmlparam4 = xmldom.createNode
				(1, "Dest_Port", "http://tempuri.org/")
				objxmlparam4.Text = Trim(tDest_port)
				objxmlmethod1.appendChild (objxmlparam4)
				Set objxmlparam5 = xmldom.createNode
				(1, "Pdf_Filename", "http://tempuri.org/")
				objxmlparam5.Text = Trim(tPdf_Filename.Text)
				objxmlmethod1.appendChild (objxmlparam5)
				Set objxmlparam6 = xmldom.createNode
				(1, "DocType", "http://tempuri.org/")
				objxmlparam6.Text = Trim(tDoctype.Text)
				objxmlmethod1.appendChild (objxmlparam6)

POST the SOAP request to the webservice using the XMLHTTP object.

So, the Url of the document that is to be converted is sent as a string parameter to the method “ConvertDocument” of the web service.

The web service processes the SOAP request and sends the SOAP response back to the client. In this case it converts the document passed by the client to PDF format and on successful processing, it returns a SOAP response containing the Pickup Url of the converted Pdf file back to the client.

Get the response SOAP payload received from webservice using the responseText property of the XMLHTTP object. Load it to a XMLDOM object.

xmldom.loadXML(XMLHTTP.responseText)

InvokeService.aspx (Displays the structured response returned from the webservice on calling the method ConvertDocument)

Parse the XMLDOM object having the SOAP response payload received from the webservice and extract the result tag which carries the result of the method.

In this case, the result type is a structured data type of name Reply containing the Pickup Url of the converted Pdf file, which is shown in the text area in the above figure. In case if there is any error encountered in processing the SOAP request, the service responds with a Fault payload which will be informed to the user.

With the Url of the converted Pdf file, the client can use HTTP-GET to pickup the document.

Thus the web services published in the UDDI Registry can be dynamically consumed.

Introduction To Weblets

Weblets can be defined as lightweight components that may be used consume web services. On Microsoft platforms weblets may be implemented as COM/Active-X components. Java platforms may use Beans (Java Beans, Enterprise Java Beans) or just Java classes.

A Weblet acts as an interface between a web service and a client application and enables the client application to access the web service very easily. All the programming nuances of setting up and working with UDDI, XML and Description Languages are made transparent, and the weblet functions like a proxy to the web service. One may drag and drop (embed) or simply instantiate a weblet from a client application and then call its methods to access the web service. Weblets need not have user interfaces, though many times it may be useful to have one.

Weblets may be used to aggregate multiple web services. A service provider may obtain weblets from multiple service providers, aggregate/embed them into a single weblet and then provide it to its customers. These Weblets may be downloaded on the fly and installed, sensitive to updates. For e.g. on Microsoft platforms, a .CAB file may be used, with the codebase pointing to an online repository. Similarly for Java classes.

Why do we need Weblets?
Weblets make access to Web Services componentizable and easier to manage. After all, why should every programmer write code against these interfaces to invoke services, when a prewritten weblet would suffice?

Weblets make aggregation or use of multiple services to be delegated to the client-side, wherever it makes sense. For example, a weblet could perform login and user authentication, a purchase order, and shipping in sequence using web services that offer authentication, purchase transactions and shipping respectively.

Weblets make creation of thin-client applications easier. A word processor client may use a disk storage service weblet for storing and retrieving files, a print service weblet for printing, a spreadsheet weblet for embedding a spreadheet, a billing service weblet for keeping track of usage and billing and so on.. These thin-client applications can thus provide access to software and online services, on a rental basis if required.

Weblets also help avoid additional investment in training and maintaining resources. An enterprise wishing to integrate a web service into its MIS can use its existing programmer pool to incorporate the weblet.

Consumption Of A .NET Webservice From VB Application Through WEBLETS

Let’s go through the steps involved in consuming a .Net webservice from a VB application through weblets.