Enterprise Software

Perform server-side updates with ASP using SOAP

SOAP gives you an easy, flexible way to provide server-side communication in an ASP application. Find out how to leverage SOAP with the XMLHTTP object.

A custom protocol can be used for communication between the client and the server. SOAP, however, can provide a flexible, scalable, and simple alternative. The XMLHTTP object makes this possible by allowing the client’s browser to execute an Active Server Page upon the server and wait for the server’s response before continuing. Because the original client-side page isn’t unloaded, this entire process is essentially transparent to the client and, typically, very fast.

Let’s examine this technique by walking through a few sample pages. Since XMLHTTP is supported only by Microsoft Internet Explorer version 5 and later, you’ll need to meet that minimum requirement on the client side for any of these examples to work properly.

In the interest of scalability I don’t like to pass the SOAP request in a query string, which has a 2,048-byte limit. Instead, I prefer to pass the request in the HTTP header, which has no such limitation. Listing A demonstrates sending basic information to the server via the HTTP header using client-side JavaScript.

SOAP simplified
The functionality in Listing A is provided by making a SOAP request to the server. SOAP requests are composed of four parts:
  • The envelope encloses the entire request and identifies the enclosed information as a SOAP request.
  • The package schema provides a description of the information that comprises the SOAP package.
  • The body contains the SOAP package.
  • The package contains the actual information regarding the server request.

Because a SOAP document is also an XML document, it is subject to the same restrictions as any XML document. The most important of these restrictions is that the document must be well formed, which means two things.

First, the tags in a well-formed XML document must always be closed. The easiest way to demonstrate this is to look at the differences between HTML and XHTML. In an XML document, all tags are container tags. While this doesn’t present a problem for container tags such as <span>, it does require some thought for a noncontainer tag such as <hr>.

There are two ways to make noncontainer tags into container tags. The first and most obvious method is that for every tag such as <hr>, there should be a </hr>. There is, however, another method: XML tags can be self-closing, so <hr></hr> becomes <hr />. It is also important to remember that, in an XML document, case matters. So, while <hr></hr> is well formed, <HR></hr> is not.

The second requirement for a well-formed XML document is that attributes must always be enclosed in single or double quotes. Because of this, while <input type=text name=stuff /> would be perfectly valid HTML, it would not be well-formed XHTML: The input tag would instead have to be coded as <input type='text' name='stuff' />.

There is one additional restriction a SOAP document has that most other XML documents do not have: SOAP documents must be described by an XML schema. A schema is an abstract representation of a document’s structure and contents written in XML. Its purpose is to define and describe the document’s structure to the XML parser.

Remedial XML
If you find all this well-formed and XML schema stuff to be a little confusing, you might want to check out the Builder.com remedial XML series and get yourself up to speed on XML.

Creating a SOAP document on the client side
Creating a SOAP document can be as simple as concatenating strings, but this method holds the potential for error. Instead, I prefer to use the MSXML XML Document Object Model’s (DOM's) methods to create the SOAP document. Creating the document in this manner ensures that the document is always well formed. With this in mind, I created six JavaScript functions to wrap MSXML’s DOM object and create a SOAP document to set, get, respond to set or get session variable requests, send a SOAP document to the server, and parse a SOAP document. You'll find these functions in Listing B and referenced via an include statement in the actual ASP page.

The functions xmlDOM, fault, and collection are primarily designed to be called by other functions. The purpose of the xmlDOM function is to return an instance of the most current version of the MSXML XML DOM object. The purpose of the fault function is to create a fault SOAP document to indicate that an error has occurred. The function collection is a class constructor that defines a JavaScript associative array.

The fourth function, sessionSOAP, also acts as a class constructor, insulating the developer from the details required to create a SOAP document to process session variables. The fifth function, sessionVariable, handles the XMLHTTP logic required to interact with the server. The sixth function, sessionParser, is also a class constructor. Its purpose is to parse a session variable SOAP document to retrieve the session variable key/item pairs. Listing C illustrates the use of these functions and classes.

On the server side
With the exception of sessionSOAP and sessionVariable, the same client-side JavaScript functions and classes can be used on the server side. My reason for doing it this way is to avoid having to code separate client-side and server-side functions to accomplish the same tasks. Listing D shows the complete SoapTestClient.asp page that handles the setting and retrieving of session variables.

The techniques I’ve discussed provide a complete example of how to use XMLHTTP, MSXML, and SOAP to access and update server-side information. These techniques can be employed for other purposes as well, such as the updating of an Active Server Page without the usual unload/reload process, which speeds up applications by reducing server traffic.