Simple Object Access Protocol (SOAP) is the basis on which web services are built. It is an XML-based protocol used to communicate and interoperate with web services. With Mozilla 1.0 (upon which Netscape 7.0x is built), it is now possible for the browser to directly communicate with web services using its low-level SOAP implementation through JavaScript.
Gecko's JavaScript interface for establishing SOAP calls is a low-level API which requires one to build the SOAP envelope using several SOAP-specific JavaScript objects. This article will cover the basic SOAP operations, for a more detailed look at the low-level SOAP API in Gecko click here.
Using JavaScript to talk to web services is subject to the same security policies as other scripts in terms of cross domain access. Therefore, accessing web services on a server other than the one where the JavaScript lives will violate the cross-domain policy. This article will show how to temporarily circumvent this for testing purposes.
The most basic object is SOAPCall, which is used to initiate and invoke a SOAP call.
var mySOAPCall = new SOAPCall();
mySOAPCall.transportURI = "http-based service URI"
mySOAPCall.encode(0, "method name ", "target object namespaceURI ", 0, null, SOAPParameter array.length, SOAPParameter
array);
var response = mySOAPCall.invoke();
A SOAPCall object has a member called transportURI, which is the URI of the location where it
should send the SOAP call to. The encode method requires the name of the method to call at the web service,
its namespaceURI, the amount of SOAPParameters passed in, and an array of SOAPParameters which contains all the parameters.
All these parameters can be found in the WSDL file for the web service, which is discussed in the Example section.
SOAP parameters are created using the SOAPParameter object. They are name/value pairs that are passed to the
web service.
var param = new SOAPParameter();
param.name = "translationmode";
param.value = "en_fr";
Once invoke is called, Gecko generates the SOAP envelope and sends it to the URI specified. Since the request is
synchronous, the response is the return value of invoke.
var returnObject = mySOAPCall.invoke();
if(returnObject.fault){
alert("An error occured: " + returnObject.fault.faultString);
} else {
var response = new Array();
response = returnObject.getParameters(false, {});
alert("Return value: " + response[0].value);
}
The return value of invoke is stored and checked for a fault member. If it exists,
an error occurred at the web service, and the error message is stored in fault.faultString. If
fault doesn't exist, we call the getParameters function on the returned object to retrieve
the returned SOAPParameters.
The example uses an existing web service, Babelfish, which is provided by xmethods.net. The Babelfish web service allows translating between several languages. It takes as an input two parameter: a string in the format of "originalLanguage_resultLanguage" and the text to translate as another string. The WSDL file for the Babelfish web service is available here and contains all the information needed to setup a low-level SOAP call to the web service.
The first step is to figure out the location of the web service, which will be the value of the SOAPCall's
transportURI member. This can be found in the WSDL's service element, specifically the
location attribute of soap:address.
WSDL:
<service name="BabelFishService">
<documentation>
Translates text of up to 5k in length, between a variety of languages.
</documentation>
<port name="BabelFishPort" binding="tns:BabelFishBinding">
<soap:address location="http://services.xmethods.net:80/perl/soaplite.cgi"/>
</port>
<service>
JavaScript:
var babelFishCall = new SOAPCall();
babelFishCall.transportURI = "http://services.xmethods.net:80/perl/soaplite.cgi";
...
The next step is the most complex one - figuring out exactly what the web service expects to be sent in terms of
parameters. The Babelfish web service only has one method, "BabelFish", which in the WSDL is represented
in operation tags, which is a child of the portType element. Each WSDL operation
has two children: the input and output elements, which contain the type expected. The types are defined in message
elements, of which there are two: BabelFishRequest, which is what is going to be passed into the web service, and
BabelFishResponse, the return type. As can be seen, the operation BabelFish expects two in parameters: translationmode
and sourcedata. The example will translate from english to french the string "I am".
WSDL:
<message name="BabelFishRequest">
<part name="translationmode" type="xsd:string"/>
<part name="sourcedata" type="xsd:string"/>
</message>
<message name="BabelFishResponse">
<part name="return" type="xsd:string"/>
</message>
<portType name="BabelFishPortType">
<operation name="BabelFish">
<input message="tns:BabelFishRequest"/>
<output message="tns:BabelFishResponse"/>
</operation>
</portType>
JavaScript:
// SOAP params
var param1 = new SOAPParameter();
param1.value = "en_fr";
param1.name = "translationmode";
var param2 = new SOAPParameter();
param2.value = "I am";
param2.name = "sourcedate";
// combine the 2 params into an array
var myParamArray = [param1,param2];
Next it's time to setup and invoke the SOAPCall object. "BabelFish" is the method the example wants to use at the
web service. The next parameter is the namespace expected to be passed into the web service for the method BabelFish.
This can be found in the WSDL binding element. The binding element has again an operation
child for the BabelFish method. The namespace needed is the value of the namespace attribute of soap:body
inside the input element.
WSDL:
<binding name="BabelFishBinding" type="tns:BabelFishPortType">
<soap:binding style="rpc" transport="http://schemas.xmlsoap.org/soap/http"/>
<operation name="BabelFish">
<soap:operation soapAction="urn:xmethodsBabelFish#BabelFish"/>
<input>
<soap:body use="encoded" namespace="urn:xmethodsBabelFish" encodingStyle="http://schemas.xmlsoap.org/soap/encoding/"/>
</input>
...
</operation>
</binding>
JavaScript:
babelFishCall.encode(0, "BabelFish", "urn:xmethodsBabelFish", 0, null, myParamArray.length, myParamArray);
var translation = babelFishCall.invoke();
As seen in Figure 5, the response of the BabelFish method ("BabelFishResponse") has one parameter, namely a string. After
making sure no fault was returned, the returned object's getParameters method is used to retrieve an array of
SOAPResponses. Since only one return parameter is expected, it is alerted as the translation.
JavaScript:
if(translation.fault){
// error returned from the web service
alert(translation.fault.faultString);
} else {
// we expect only one return SOAPParameter - the translated string.
var response = new Array();
response = translation.getParameters(false, {});
alert("Translation: " + response[0].value);
}
As mentioned in the introduction, SOAP calls obey the cross domain access policy for scripting. There are two ways to circumvent the security policy for testing purposes:
Run the script from your local drive
Save the code locally to your hard disk. The cross-domain security model does not affect code run from the local hard disk.
Enable Cross Domain Access
You can bypass the cross-domain check by setting a preference as explained in Bypassing Security Restrictions and Signing Code article and in adding a JavaScript command to request overriding of the cross-domain check. The first step is to locate the profile used in the Netscape Gecko-based browser. The Netscape 7.0x release notes contain a table of profile location depending on operating system. Each profile has a "salt" directory, which then leads to the actual profile. Shut down the browser and place user.js in that directory (there should be a prefs.js file in the same directory).
After adding the the file, start the browser and load this modified
example page. It will ask (via a dialog) for permissions to turn off cross-domain (for this session) for the function generating the SOAP call.
The only change made is adding netscape.security.PrivilegeManager.enablePrivilege("UniversalBrowserRead"); to
the function that generates the SOAP call.
JavaScript:
var babelFishCall = new SOAPCall();
babelFishCall.transportURI = "http://services.xmethods.net:80/perl/soaplite.cgi";
// SOAP params
var param1 = new SOAPParameter();
param1.value = "en_fr";
param1.name = "translationmode";
var param2 = new SOAPParameter();
param2.value = "I am";
param2.name = "sourcedate";
// combine the 2 params into an array
var myParamArray = [param1,param2];
babelFishCall.encode(0, "BabelFish", "urn:xmethodsBabelFish", 0, null, myParamArray.length, myParamArray);
var translation = babelFishCall.invoke();
if(translation.fault){
// error returned from the web service
alert(translation.fault.faultString);
} else {
// we expect only one return SOAPParameter - the translated string.
var response = new Array();
response = translation.getParameters(false, {});
alert("Translation: " + response[0].value);
}
Here is a HTTP dump (using the cross-platform Ethereal tool) of what actually gets sent and retrieved when the example gets executed:
Sent:
POST /perl/soaplite.cgi HTTP/1.1
Host: services.xmethods.net:80
...
Content-Type: text/xml
Content-Length: 516
<env:Envelope xmlns:env="http://schemas.xmlsoap.org/soap/envelope/" xmlns:enc="http://schemas.xmlsoap.org/soap/encoding/"
env:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/" xmlns:xs="http://www.w3.org/1999/XMLSchema"
xmlns:xsi="http://www.w3.org/1999/XMLSchema-instance">
<env:Header/>
<env:Body>
<a0:BabelFish xmlns:a0="urn:xmethodsBabelFish">
<a0:translationmode xsi:type="xs:string">en_fr</a0:translationmode>
<a0:sourcedata xsi:type="xs:string">I am</a0:sourcedata>
</a0:BabelFish>
</env:Body>
</env:Envelope>
Recieved:
HTTP/1.1 200 OK
Date: Tue, 11 Mar 2003 20:28:11 GMT
Server: Apache/1.3.26 (Unix) Enhydra-Director/3 PHP/4.0.6 DAV/1.0.3 AuthNuSphere/1.0.0
SOAPServer: SOAP::Lite/Perl/0.52
Content-Length: 532
...
Content-Type: text/xml; charset=utf-8
<?xml version="1.0" encoding="UTF-8"?>
<SOAP-ENV:Envelope xmlns:SOAP-ENC="http://schemas.xmlsoap.org/soap/encoding/" SOAP-ENV:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/" xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/" xmlns:xsi="http://www.w3.org/1999/XMLSchema-instance" xmlns:xsd="http://www.w3.org/1999/XMLSchema">
<SOAP-ENV:Body>
<namesp1:BabelFishResponse xmlns:namesp1="urn:xmethodsBabelFish">
<return xsi:type="xsd:string">je suis</return>
</namesp1:BabelFishResponse>
</SOAP-ENV:Body>
</SOAP-ENV:Envelope>