WSRequest Host Object

1.0 Introduction

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.

1.1 Example

var version = new WSRequest();
var options = new Array();
options.useSOAP = 1.2;
options.useWSA = 1.0;
options.action = "urn:getVersion";
request = "<getVersion/>";

try {
	version.open(options,"http://127.0.0.1:11001/services/version", false);
	version.send(request);
	result = version.responseE4X;
} catch (e) {
	print(e);
}

2.0 WSRequest Object

2.1 WSRequest Interface

interface WSRequest
{
    property EventListener onreadystatechange;
    property unsigned short readyState;
    void open ( in object options | in String method, in String url [, in boolean async [, in String user [, in String password]]]);
    void send ( [in Document payload | in XMLString payload | in XMLString payload ]);
    readonly property String responseText;
    readonly property Document responseXML;
    readonly property XML responseE4X;
    readonly property WebServiceError error;
}

2.2 API Documentation

Member Description
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. (Currently this is same as responseE4X, but this will be fixed to return a DOM document in the future versions)
responseE4X The parsed E4X 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 a WebServiceError object

3.0 Options

Option Range of values Description
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 a 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, and the WSDL 2.0 HTTP binding.
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" must 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.

See Ideas for evolving WSRequest for additional options under development.

4.0 References