Subject

The Whitebeam environment provides virtually everything you need to develop sohpisticated Web based applications. There are a number of occassions when it's useful to access other Internet, Intranet or Extranet resources however. To access such data requires that one application be able to send out Hyper Text Transfer Protocol (HTTP) requests to other servers. Whitebeam provides a simple way of making such requests via the HttpRequest JavaScript class.

The HttpRequest class provides an application with the ability to access any of the HTTP based network applications available on the Internet. Examples include:

• Accessing online data-sources. Such sources may have a Simple Object Access Protocol (SOAP) or may simply be XML or HTML documents
• Reading existing web pages and reskinning them on the fly. For example where a company has a legacy web-site comprising a lot of static pages. A 'quick' way of changing the corporate image for such a site is to run each page request through a Whitebeam Presentation Page that performs the look and feel translation.
• Adding security to an existing insecure application. For example where you want to make an Intranet application available to authorised people over the Internet. Leave the old application behind a firewall and use the Whitebeam security architecture to encapsulate each page in a secure wrapper.

Simple HTTP requests

In it's simplest form the HttpRequest class allows an application to simply specify an IP address or host name, port number and URL. The HttpRequest object makes the request and returns a string containing the data returned by the server. The text can then be processed either textually - or more easily in many cases - using the XML/HTML parsing rules within the Whitebeam Presentation Engine.

Example

Suppose we wish to go to a specific Web page and find all the links to other pages:

var request = new HttpRequest;

  request.host="www.whitebeam.org";
  request.path="/";

  request.doRequest();
  if (request.res==200) {
     // Create a parser.
     var aParser = new XmlParser();

     aParser.mode(XmlModeHTML);

     // Build the tree.
     if (aParser.build(request.body)) {

       // Find all the anchor tags with href attributes using XPath.
       var attribs = aParser.root.select("//a/@href");

       // Display all the links we find.
       for (var i=0;i<bodyTag.length;i++) {
          // Write to the client.
          rb.page.write("<tr><td>"+attribs[i]+"</td></tr>\n");
       }
     }
     else {
       rb.page.write("Couldn't build XML Tree - text contains errors!");
     }
  }
  

The first few lines (in bold) configure and make the HTTP request. First of all a request object is created, then some properties are set on that object that determine how to find the required server - and what resource on that server is required. The minimum required is the host and the path. By default the HttpRequest object will use port 80, and send an HTTP 'GET' request.

The example above is very simple. It reads the raw HTTP page from the Whitebeam home page. If the request works (request.req is the HTTP response code - 200 means success) the page then creates an XML parser - configuring it to accept HTTP requests then asks it to build a tree from the page received.

An XPath 'select' call is then made on the root of the built tree to find all anchor tags (<a...>) that have 'href' attributes.

Finally any references found are written out to the page being generated in a table

Simple Object Access Protocol (SOAP)

SOAP is a standardised protocol for invoking procedures on remote systems over HTTP. The protocol uses the HTTP request to contain the name of the method being invoked and the required parameters. The response is then encapsulated in the response back to the client.

The beauty of protocols like SOAP is that they are text based - and they do not require any complex libraries to work. Although Whitebeam does not include any integral support for SOAP at this point - the HttpRequest class along with the XML facilities are all that are required to build a SOAP library. This section deals with how to issue a simple SOAP request.

SOAP utility class.

For this example we're going to encapsulate the basic HttpRequest object taht is native to Whitebeam in an application class called SoapRequest. This class will is simply defined as follows:

function SoapRequest(host, port, path, nameSpace, method) {

   if (host!=null)
      this.host = host;

   if (path!=null)
      this.path = path;

   if (nameSpace!=null)
      this.nameSpace = nameSpace;

   if (method)
      this.call = method;

   this.params = new Array;
}

SoapRequest.prototype = new HttpRequest;

SoapRequest.prototype.execute = function() {

   this.method   =  "POST";
   this.postdata =  '<?xml version="1.0" encoding="ISO-8859-1" ?>'+
                    '<SOAP-ENV:Envelope xmlns:SOAP-ENC="http://schemas.xmlsoap.org/soap/encoding/"'+
                    ' SOAP-ENV:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/" '+
                    ' xmlns:xsi="http://www.w3.org/1999/XMLSchema-instance" '+
                    ' xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/" '+
                    ' xmlns:xsd="http://www.w3.org/1999/XMLSchema"><SOAP-ENV:Body>'+
                    '<namepsaceRed:'+this.call+' xmlns:namepsaceRed="'+this.nameSpace+'">'+
                      this.body+
                    '</namepsaceRed:'+this.call+'>'+
                    '</SOAP-ENV:Body></SOAP-ENV:Envelope>';

   var res = this.doRequest();

}
        

The SoapRequest class has a constructor and a 'doRequest' method - that's all. The constructor takes the host, port and path method for use in the underlying HttpRequest object. It also takes the SOAP namespace to use along with the method being invoked on the remote server.

A simple example of using this class is shown below. It reads some stock quotes from a public SOAP server.

         // Build request.
         var req = new SoapRequest("www.velocigen.com", 82, "/vx_engine/soap-trigger.pperl", "urn:vgx-stock", "getXMLQuote");

         req.body = '<stockticker><symbol>coms+ibm+intc+a+palm</symbol></stockticker>';
         req.port = 82;

         req.execute();

         rb.debug.write("<h1>Contents of the SoapRequest AFTER execution</h1>\n");
         dumpObj(req, "SoapRequest");
        

This example dumps the contents of the SOAP response - which is text. It could equally have been the source for an XML parser from which could be built an XML tree that in turn could be queried using XPath.