Public Web services add a great deal of functionality to your applications without the hassle of implementing third-party software on your system. A Web service for Web applications is usually utilized server-side. The Web service is intended to replace business objects built either with COM, Enterprise JavaBeans, or as part of another service package. However, with Mozilla, you can easily implement a Web service within the browser using the SOAP API. In this article, I'm going to use a free public Web service for displaying the current temperature on a Web page.
The SOAP API is a _JavaScript interface that contains a set of objects that you can use to manage SOAP messages. SOAP is the communication protocol between the client using the Web service and the server hosting the service; this communique is a series of messages wrapped up in an XML envelope. XML provides the power to create complicated data types and the flexibility to use them across platforms.
The Web service's specifications that I'll be using are located at XMethods. This Web service takes a zip code as a parameter and returns the current temperature.
In order to create the SOAP message with Mozilla, you use the SOAPCall and SOAPParameter objects. SOAPCall is responsible for creating and encoding the SOAP message, and SOAPParameter is for creating the individual parameters to pass to the Web service. In my page, when the page loads--let's say that we have a user-aware site with preferences set--I use the users' preferred zip code to display their local temperature:
function window_onload() {
var soap_call = new SOAPCall();
soap_call.transportURI =
"http://services.xmethods.net:80/soap/servlet/rpcrouter";
var p = [new SOAPParameter("90210", "zipcode")];
soap_call.encode(0, "getTemp", "urn:xmethods-Temperature", 0, null,
p.length, p);
var temp = soap_call.invoke();
if (temp.fault) {
alert(temp.fault.faultString);
} else {
var response = [];
response = temp.getParameters(false, {});
document.getElementById("divTemp").innerHTML = response[0].value +
"°F";
}
}
The first thing that happens is a new SOAPCall object is created. The transportURI property is set; you can find this in the WSDL file in the <soap:address> location attribute. Parameters are passed to the encode() method of the SOAPCall object as an array of SOAPParameter objects.
The getTemp() method of the Web service takes only one parameter: zipcode. This parameter is set to the user's defined zip code; in my example, that user's zip code is 90210.
The encode() method accepts six parameters, but the four that you should concern yourself with are: the Web service method name, the target namespace, the parameter array length, and the parameter array. These are the second, third, fifth, and sixth parameters, respectively.
The method name is self-explanatory; this is the name of the method you wish to invoke. You can find the target namespace for this Web service in the namespace attribute of the <soap:body> input element. The parameter array length is simply the length of the parameter array. (Length is a property on the _JavaScript Array object.) The parameter array is the collection of SOAPParameters in a _JavaScript Array.
In order to make the actual call to the Web service, you can use either the asyncInvoke() method or the invoke() method of the SOAPCall object. The difference between asyncInvoke() and invoke() is that asyncInvoke() will perform an asynchronous invocation of the Web service method. The result is returned to a callback function that will handle the response. The invoke() method will halt the script until a response is received. I'm using this method because I'm not working with time-sensitive operations.
The return value of the invoke() method is a SOAPResponse object. The SOAPResponse object's fault property contains a SOAPFault object if a fault occurs. In this case, I simply issue an alert box with the faultString value of the SOAPFault object. Otherwise, I grab the return parameters and store them to a local variable. Each return parameter is an object that contains three properties: name, value, element. Name is the name of the parameter; value is the value of the returned parameter; element is a pointer to a DOM node in the returned XML. For my purposes, only one parameter is returned, as defined in the WSDL. I set the innerHTML of an arbitrary <DIV> element to the value of the returned parameter.
