Using WSRequest

The WSO2 Mashup Server automatically generates stubs to simplify the consumption of the Web Services it hosts. But if you’re consuming a service from somewhere else, we don’t yet provide the same level of ease. Instead of a stub which hides some of the details of exercising an operation, you must use the WSRequest object directly to formulate the messages.

The WSRequest object is similar to the XMLHTTPRequest object. It’s usage typically involves specifying the endpoint address and setting up options on how to frame the message, invoking the operation with a specific XML payload, and then checking and extracting information from the result. Here’s a simple, synchronous, example:

var flickr = new WSRequest();
var options = new Array();
options.useSOAP = 1.2;
options.useWSA = 1.0;
options.action = "http://api.flickr.com/services/soap/";

request =  <f:FlickrRequest xmlns:f="urn:flickr">
                <method>flickr.photos.search</method>
                <api_key>{api_key}</api_key>
                <format>soap2</format>   
                <group_id>54718308@N00</group_id>
                <tags>3</tags>
                <page>1</page>
                <per_page>25</per_page>
           </f:FlickrRequest>;

try {
    flickr.open(options,"http://api.flickr.com/services/soap/", false);
    flickr.send(request);
    result = flickr.responseXML;
} catch (e) {
    // some error happened
}

The WSRequest object is available natively within the Mashup Server in the form of a hosted object. It can be instantiated as an ActiveX Control on Windows or an XPI on Firefox (although the current distributable is obsolete and still called SOAPHttpRequest, WSRequest version will be available soon), or you can use a JavaScript native version (eg: http://localhost:7762/js/wso2/WSRequest.js) that relies on the XMLHttpRequest object available within popular browsers.

The WSRequest object has the following members:

open(options, endpointAddress, async)

This method prepares the WSRequest object to invoke a Web service. It accepts the following parameters:

options (array): an array of options for formulating the message. These options correspond to the message framing required by the service as documented in the service's WSDL and/or documentation. A list of the supported options is at WSRequest Options.

endpointAddress (string): a URL representing where to send the message.

async (boolean): a boolean flag representing whether the operation should be invoked asynchrounously or not.

The open() function throws an exception if the WSRequest object cannot accommodate the request (e.g., the options are malformed.)

send(payload)

This method invokes the Web service with the requested payload.

payload: an XML object or a string containing the XML source for the request.

onreadystatechange

This property can be set to a function object, which is invoked when the state of an asynchronous request changes (e.g., the request completes).

readyState

The current state of the object, which can be one of the following values:

0: The object has not been initialized by calling the open() method.

1: The object has been initialized successfully, but the send() method has not been called.

2: The request is pending

3: The request is partially complete (some data has been received, and may be available in the responseText property.

4: The request is complete, all data has been received.

Of these, typically only the last (readyState = 4) is used.

responseXML

The parsed XML message representing the response from the service.

responseText

The raw text representing the XML (or non-XML) response. If the responseXML property is empty, you can check the responseText property to see if a non-XML response was received.

error

When an asynchronous operation failed to complete successfully (including internal errors, or protocol errors such as SOAP faults) the error property is an object with the following properties:

code	A string (often a QName) representing the error code.
reason	A brief textual description of the error.
details	A full description (usually XML) of the error.

For non-error responses, or if the request was made synchronously, this property is null.

WSRequest Options

The following options are supported by all versions of WSRequest at this time:

useSOAP	"1.2", 1.2, "1.1", 1.1, true, false	Indicates which version of SOAP to use. If the value is "1.2", 1.2, or true, the message will be framed as an SOAP 1.2 message. If “1.1” or 1.1, SOAP 1.1 will be used. If false, the payload will be sent directly as the HTTP body. These options correspond to the WSDL 2.0 SOAP 1.2 binding [ref], the WSDL 2.0 SOAP 1.1 binding [ref], and the WSDL 2.0 HTTP binding [ref].
useWSA	TRUE \| FALSE \| 1.0 \| "1.0" \| "submission"	Indicates whether to use WS-Addressing. If TRUE, 1.0 or "1.0", WS-Addressing 1.0 is used. When "submission" is specified, the submitted version is used. Except when FALSE, the "action" option must also be set.
action	xs:anyURI	The WS-A action to use when constructing the WS-A headers. Also used as the SOAP Action when specified, regardless of whether WS-A is engaged or not.
HTTPMethod	xs:string \| "POST"	The HTTP method to use to formulate the request.