Writing the SOAP Sample Application

This topic describes the design of the SOAP Sample application.

Obtaining the service description document:
The first step to being able to connect to a service is to obtain the service description document in the WSDL format. For this sample, we are using the web service made available by National Oceanic and Atmospheric Administration (NOAA). We use the NOAWeatherWDSLServlet to obtain the WSDL document. In order to invoke the service, here is an overview of the steps involved.

Instantiating the SOAP Service widget
The following code instantiates the SOAP Service widget.

<div dojoType="ibm_soap.widget.SoapService" id="noaa" url="noaservice.wsdl"></div>

We identify this widget with the ID "noaa", and the widget has one input parameter: the service description. You can either download the WSDL document, store it in the application and point to it, or fetch the document dynamically at runtime. In this example, we have configured a servlet at the URL location /noaservice.wsdl which obtains and returns the WSDL document.


Creating the SOAP Request

The following code creates the SOAP request:

// Create the SOAP request structure using the zipcode entered by the user
var lookupLatParams = new dojox.wire.ml.XmlElement("LatLonListZipCodeRequest");
lookupLatParams.setPropertyValue("zipCodeList",zipcode);

Before you can invoke the service, you need to know what method you will be invoking and what the method expects. In this case, we choose a simple method that returns the latitude and longitude of a given zipcode. To successfully create the SOAP request, you need to refer to the WSDL document and create the SOAP request accordingly. Once you know the parameter format for the method you want to invoke, you can create the parameter list as an XML object.

Invoking the service
The following code invokes the service:

// Invoke the service
deferred = noaaService.service.LatLonListZipCode(lookupLatParams);

Once you have instantiated the service and created the XML structure for the parameters, invoking the service is just like calling a method on the service member of the service that you instantiated. In simple words, if you want to invoke method xyz on the service and you have created the parameter structure as parms, you can invoke the method by using the following format:
<service handle>.service.xyz(parms);

Under the covers, this invokes the external web service with the parameters that you pass to it and retrieves the results.

Parsing the results

The following code parses the results:

// Process the results
deferred.addCallback(function(xmlData){
.........
.........
}


Once you invoke the service, the method as described above can be used to parse the XML sent back by the service to obtain the required results. The xmlData object contains an XML object with the contents of the SOAP Body tag within the results sent back from the service. Depending on the structure, you can use XML functions to retrieve the data you want.


Usage of Ajax Proxy

The sample uses Ajax Proxy included with the Feature Pack for Web 2.0 for communicating with the external service. Please refer to the corresponding documentation for its usage.