|
This tutorial guides you through the process of how to work with Backbase to create and communicate Simple Object Access Protocol (SOAP) messages to a web service in JavaScript and in the XML Execution Language (XEL).
Prerequisites and Intended Audience
The content in this example page is intended for anyone interested to understand how to use Backbase Client Framework to communicate with a web service. To complete this example you need Backbase Client Framework and experience with the Backbase JavaScript or XEL and Command APIs.
Overview
SOAP is a lightweight protocol intended for exchanging structured information in a decentralized, distributed environment.
The first section demonstrates how to construct a SOAP message and communicate it to a web service using the Backbase JavaScript API.
The second section demonstrates the same procedure using the Backbase XEL and Command APIs.
The third section examines the different SOAP versions and explains how to work with them properly.
Using JavaScript to Connect to a Web Service
In this section you will learn how a SOAP message can be created and communicated in JavaScript.
Creating a SOAP message
The global object SOAPEnvelope offers an easy-to-use constructor for SOAP messages. It has two public properties:
- header - a reference to the SOAPEnvelope header block
- body - a reference to the SOAPEnvelope body block
It also has three public methods:
- addBlock - adds a new block to the message
- setBlockValue - sets the value of the block
- encode - encodes message and returns its XMLDocument
Constructing a SOAP message using SOAPEnvelope is achieved by adding blocks of XML elements:
var oEnvelope = new SOAPEnvelope;
var oHeaderBlock = oEnvelope.addBlock(oEnvelope.header, "my:header", "my://test");
var oBodyBlock = oEnvelope.addBlock(oEnvelope.body, "my:request", "my://test");
var oBodyBlockParam = oEnvelope.addBlock(oBodyBlock, "my:param", "my://test");
</e:handler>
Listing: Creating a SOAP message with the SOAPEnvelope constructor.
Sending a SOAP message and processing the response
Sending a SOAP envelope can be performed with the XMLHttpRequest object by passing oEnvelope.encode(), as shown in the following listing:
<e:handler event="click" type="application/javascript">
oEnvelope.setBlockValue(oBodyBlockParam, "data");
//
var oRequest = new XMLHttpRequest;
oRequest.open("POST", "WebService.asp", false);
oRequest.setRequestHeader("SOAPAction", "my://test/request");
oRequest.send(oEnvelope.encode());
//
alert(bb.evaluate("string(//my:response/my:param)", oRequest.responseXML));
</e:handler>
call
</b:button>
Listing: Communicating a SOAP message with XMLHttpRequest.
Note: Line 10 in the listing assumes that the server replied with a my:response block, and queries the response with XPath.
Using the XEL and Command APIs to Connect to a Web Service
This section demonstrates how to create and send a SOAP message declaratively using a combination of the XEL and Command APIs.
Creating a SOAP message
In the following listing, the raw SOAP message is constructed and assigned to a variable. A global variable is used so that the envelope can be reused in a later communication.
<e:data xmlns:my="my://test" type="application/xml">
<SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/" SOAP-ENV:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/">
<SOAP-ENV:Header>
<my:header></my:header>
</SOAP-ENV:Header>
<SOAP-ENV:Body>
<my:request>
<my:param>value</my:param>
</my:request>
</SOAP-ENV:Body>
</SOAP-ENV:Envelope>
</e:data>
</e:variable>
Listing: Creating a SOAP message with XEL.
Sending a SOAP message and processing the response
Sending a SOAP message is achieved using the Command c:load element. The select attribute is used to select the variable that contains the envelope.
<e:handler event="click" type="application/xml">
<c:setText select="'data'" destination="$eEnvelope//my:request/my:param" mode="replaceChildren"></c:setText>
<!-- -->
<e:variable name="eResponse">
<c:load url="test.php" method="POST" select="$eEnvelope">
<c:header name="SOAPAction" select="'my://test/request'"></c:header>
</c:load>
</e:variable>
<!-- -->
<c:alert select="string($eResponse//my:response/my:param)"></c:alert>
</e:handler>
call
</b:button>
Listing: Communicating a SOAP message with the Command API.
Note: Line 9 in the listing assumes that the server replied with a my:response block, and queries the response with XPath.
Compliance with SOAP Versions
Presently, there are two SOAP versions in common use: versions 1.1 and 1.2. To communicate with a SOAP 1.2 web service, the Backbase JavaScript requires some additional coding.
SOAP 1.2 compliant JavaScript
When using SOAPEnvelope object you can pass the version number to the object constructor so the message that is created in is compliant with the version specified ("1.1" version is the default):
var oEnvelope = new SOAPEnvelope("1.2");
</e:handler>
Listing: Passing the version to the envelope.
For version 1.2 compliant messages constructed using JavaScript, a proper Content-Type header of "application/soap+xml" must be sent with the data. When sending SOAP messages with XMLHttpRequest, the header must be defined explicitly:
var oRequest = new XMLHttpRequest;
oRequest.open("POST", "WebService.asp", false);
oRequest.setRequestHeader("Content-Type", "application/soap+xml");
oRequest.send(oEnvelope.encode());
</e:handler>
Listing: Passing the Content-Type to the web service.
XEL and Command APIs
The XML and Command APIs are SOAP version agnostic:
- In the case of the XEL and Command APIs, the procedure for defining the envelope is SOAP version independent because the message is defined manually.
- When sending the message using the c:load element, the version header is included automatically.
This example demonstrates how to use either of the Backbase JavaScript or XEL APIs to communicate with a web service. Communicating with web services is straightforward with Backbase technologies, especially so using the declarative APIs, since the code is SOAP version agnostic.
Additional Resources
For more information on SOAP, refer to the following documentation:
