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
function invokeGetVersion(){
var version = new WSRequest();
var options = new Array();
options.useSOAP = 1.2;
options.useWSA = 1.0;
options.action = "http://services.mashup.wso2.org/version/ServiceInterface/getVersionRequest";
var payload = null;
try {
version.open(options,"http://localhost:7762/services/system/version", false);
version.send(payload);
result = version.responseE4X;
} catch (e) {
system.log(e.toString(),"error");
return e.toString();
}
return result;
}
2.0 WSRequest Object
2.1 WSRequest Interface
interface WSRequest
{
property EventListener
onreadystatechange;
property unsigned short readyState;
function void open ( object
options | String httpMethod, String url
[, boolean async [, String username
[, String password]]]);
function void send ( XML
payload | XMLString payload ); // To be used when
the open method of WSRequest is used
function void openWSDL ( String wsdlURL, boolean async, [Object
options,[QName serviceName, [String endpointName]]]);
function void send ( String
operationName | QName operationName, XML payload | XMLString
payload ); // To be used when the openWSDL method of
WSRequest is used
readonly property String responseText;
readonly property Document responseXML;
readonly property XML responseE4X;
readonly property WebServiceError error;
}
2.2 API Documentation
| Member | Description |
| function void open ( object options | String httpMethod, String url [, boolean async [, String username [, String password]]]) | This method prepares the WSRequest object to invoke a
Web service. It accepts the following parameters:
The following is a list of supported options
When WS-Addressing is been used the following options will also be processed
|
| function void send ( XML payload | XMLString payload ) | This method invokes the Web service with the requested
payload. To be used when the WSRequest object was configured using the open method.
|
| function void openWSDL ( String wsdlURL, boolean async, [Object options,[QName serviceName, [String endpointName]]]) | This
method can be used to invoke a external web service which advertices a
WSDL. Using this method had many advantages over using the open method.
The following is a list of supported options
|
| function void send ( String operationName | QName operationName, XML payload | XMLString payload ) | This method invokes the specified operation of the Web service with the requested
payload. To be used when the WSRequest object was configured using the openWSDL method.
|
| property EventListener 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). |
| property unsigned short readyState | The current state of the object, which can be one of
the following values:
|
| readonly property Document 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) |
| readonly property XML responseE4X | The parsed E4X XML message representing the response from the service. |
| readonly property String 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. |
| readonly property WebServiceError 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 Example Usage
2.1 Calling Services in a asynchronous manner
Its important to note that when a service is called in the manner below (assynchronously) the thread will return to the caller immidiatly (Even before the result of the web service invocation is received).// Demonstrates calling the getVersion operation of the version service in a asynchronous manner using the open method
function invokeGetVersionAsync(){
var version = new WSRequest();
version.onreadystatechange = function() {
handleResponse(version);
};
var options = new Array();
options.useSOAP = 1.2;
options.useWSA = 1.0;
options.action = "http://services.mashup.wso2.org/version/ServiceInterface/getVersionRequest";
var payload = null;
try {
version.open(options,"http://localhost:7762/services/system/version", true);
version.send();
} catch (e) {
system.log(e.toString(),"error");
return e.toString();
}
return "Invoked getVersion in a asynchronous manner";
}
handleResponse.visible=false;
function handleResponse(version){
if (version.readyState == 4) {
system.log(version.responseText);
}
}
// Demonstrates calling the getVersion operation of the version service in a asynchronous manner using the openWSDL method
function invokeGetVersionAsync(){
var request = new WSRequest();
request.onreadystatechange = function() {
handleResponse(request);
};
request.openWSDL("http://localhost:7762/services/system/version?wsdl",true);
request.send("getVersion",null);
return "Invoked getVersion in a asynchronous manner";
}
handleResponse.visible=false;
function handleResponse(version){
if (version.readyState == 4) {
system.log(version.responseText);
}
}
2.1 Calling Services which are secured using WS-Security
Calling secured services using the WSO2 Mashup Server is simple. The client given below can handle sevaral security scenarios provided that the proper certificate provisioning has taken place.// Demonstrates calling the getVersion operation of the version service. This client will work for most
// WS-Security scenarios (Works for all the scenarios the Mashup Server ships)
function invokeGetVersion(){
var request = new WSRequest();
var options = new Array();
options["username"] = "keith";
// Will be used if the service policy requires a Username Token. Assuming that access has been granted to keith
options["password"] = "keith";
// Will be used if the service policy requires a Username Token. Assuming that access has been granted to keith
options["encryptionUser"] = "versionCert";
// The alias of the certificate that will be used to encrypt the request.
// This is the public certificate of the Keystore that the version service is secured with.
// If the security policy of the version service needs the request signed the client will do so.
// But the keystore of the version service needs to have keith's (the clients) public certificate
var service = new QName("http://services.mashup.wso2.org/version","version");
request.openWSDL("http://localhost:7762/services/system/version?wsdl",true, options,service,"SecureSOAP11Endpoint");
request.send("getVersion",null);
return request.responseXML;
}