User's Guide for WSO2 WSF/AJAX XPI

Installation Guide

The modules for the extension is packaged as an XPI So you can just visit the XPI using the Firefox browser and it will get installed automatically. Then restart the browser and the extension is ready to use.

Verify WSO2 WSF/AJAX XPI Installation

Once you use the API provided by WSO2 WSF/AJAX XPI in a web page, the visitors need to have installed the XPI in their browsers as well. The following fragment of code would verify whether the XPI is installed, and if not it will direct the user to download the XPI.

try
{
  var req = new SOAPHttpRequest();
}
catch (e )
{
  if (confirm("SOAPHttpRequest not defined:|\nClick ok to download and install the extension\n"+
              "Or visit the link http://dist.wso2.net/products/wsf/ajax/xpi/0.1/"))
  {
    alert("Please restart the browser after installation");
    window.location="http://dist.wso2.net/products/wsf/ajax/xpi/0.1/";
  }
  else
  {
    alert ("Some of the functionality will not be available without the WSO2 WSF for AJAX extension");
  }
}

User Guide

The WSO2 WSF/AJAX XPI provides an API for the Web programmer to invoke Web services from client side. The API of the extension is very similar to the mozilla AJAX API. It introduces a Java-script class SOAPHttpRequest in place of XMLHttpRequest with extended capabilities to consume Web services.

Some documentation of the API can be found on here. Following sections explain the API with few simple examples to consume an echo Web service.

Build Request XML and Handle Response XML

Since SOAPHttpRequest provides XML in/ XML out programming model, the Web programmer would have to generate XML to be sent and handle XML received.

Java-script function to generate XML for echo service would look like this:

function generateXML(echoWord)
{
  //create the root node
  var req_node = document.createElementNS ("http://localhost:9090/axis2/services/echo", "ns1:echoString" );

  //create the node for text
  var data_node = document.createElement ("text");
  var data_text = document.createTextNode (echoWord);
  data_node. appendChild(data_text);

  //attach nodes
  req_node. appendChild (data_node);
  return req_node;
}

Java-script function to handle XML for echo service would look like this:

function handleXML( responseXML)
{
   return resultContent.firstChild.firstChild.firstChild.nodeValue;
}

Invoke Echo Service Synchronously

Following would invoke the service (synchronously) in blocking mode.

function echo( myWord)
{
   /** generate the request XML - defined above */
   var request = generateXML (myWord);

   /** create and initialize the SOAPHttpRequest */
   var sr = new SOAPHttpRequest();
 
   /** declare the request would be blocking my setting false for the third parameter */

   sr.open ("POST", "http://localhost:9090/axis2/services/echo", false);
   
   /** just invoke the service */
   sr.send (request);

   /** wait for the response and show result*/
   var response = sr.responseXML;
   var echoedText = handleXML(response);

   alert (echoedText);
}

Invoke Echo Service Asynchronously

To invoke the service asynchronously there should be a separate handler function. Here the handler has been declared as a global function and it is assigned to the onreadystatechange property of the SOAPHttpRequest.

/** create and initialize the SOAPHttpRequest */
var sr = new SOAPHttpRequest();

function echo( myWord)
{
   /** generate the request XML - defined above */
   var request = generateXML ( myWord);

   /** set the callback function */
   sr.onreadystatechange = handler;
   
   /** ignore the third parameter so the invocation would be asynchronously. */
   sr.open ( "POST", "http://localhost:9090/axis2/services/echo");
   
   /** invoke the service. */
   sr.send ( request );
}

function handler()
{
   if ( sr.readState == 4 ) /** operation completed */
   {
      if ( sr.state == 200 ) /** http request successful*/
      {
     
       /** get the response and show result */
       var response = sr.responseXML;
       var echoedText = handleXML(response); /** defined above */
    
       alert (echoedText);
      }
   }     
}

Engaging Modules

Modules can be engaged to the engine at run-time through the XPI's API. Modules help to apply WS-* QoS extensions when consuming Web services. Following sample demonstrates the engaging of WS-Addressing module.

function echo( myWord)
{
   var sr = new SOAPHttpRequest();
   ....

   /** set all the options here as key value pair */
   sr.options (
            { wsa_action:"http://ws.apache.org/axis2/c/samples/echoString" } );

   /** engage the module with the name and the version */
   sr.engage ("addressing", "vx");

   ...
   sr.open ( "POST", "http://localhost:9090/axis2/services/echo");
   sr.send ( request );
}