<xi:include href="../../../bindings/www.backbase.com.2006.btl/codeHighlighter/codeHighlighter.xml"></xi:include>

Creating and Communicating SOAP Messages

Introduction

This examples page will guide you through the process of how to work with Backbase to create and communicate SOAP messages to a web service in JavaScript and in 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 in this example page 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

And 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:

<b:codeHighlighter class="epage-snippet"> <e:handler xmlns:xi="http://www.w3.org/2001/XInclude" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" event="click" type="application/javascript"> 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> </b:codeHighlighter>

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, passing oEnvelope.encode() as shown in the following listing:

<b:codeHighlighter class="epage-snippet"> <b:button xmlns:xi="http://www.w3.org/2001/XInclude" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"> <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> </b:codeHighlighter>

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.

<b:codeHighlighter class="epage-snippet"> <e:variable xmlns:xi="http://www.w3.org/2001/XInclude" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" name="eEnvelope"> <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> </b:codeHighlighter>

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.

<b:codeHighlighter class="epage-snippet"> <b:button xmlns:xi="http://www.w3.org/2001/XInclude" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"> <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> </b:codeHighlighter>

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 (please refer to the Additional Resources for more information). 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):

<b:codeHighlighter class="epage-snippet"> <e:handler xmlns:xi="http://www.w3.org/2001/XInclude" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" event="click" type="application/javascript"> var oEnvelope = new SOAPEnvelope("1.2"); </e:handler> </b:codeHighlighter>

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.:

<b:codeHighlighter class="epage-snippet"> <e:handler xmlns:xi="http://www.w3.org/2001/XInclude" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" event="click" type="application/javascript"> var oRequest = new XMLHttpRequest; oRequest.open("POST", "WebService.asp", false); oRequest.setRequestHeader("Content-Type", "application/soap+xml"); oRequest.send(oEnvelope.encode()); </e:handler> </b:codeHighlighter>

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.

Closure

This example page has demonstrated 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, please refer to the following: