Architecture

WBI is a programmable HTTP request and HTTP response processor. It embodies a rich model for processing HTTP streams, which offers the programmer considerable power and flexibility in designing a intermediary application. To most effectively use WBI's power, you must understand WBI's data model and WBI's processing model. Briefly, the data model describes the way requests and responses are accessed and manipulated. WBI's processing model describes (a) the way different modules within WBI are activated when requests are received from the browser or other client, and (b) the way these different modules work together to produce the response that is sent back to the browser.

Data Model

WBI's data model is based on the request/response structure of HTTP version 1.0. Each request and each response consists of a structured part and a stream part. The structured part corresponds to the header and the stream part corresponds to the body.

HEADER (DocumentInfo)

POST http://www.ibm.com/java HTTP/1.0
User-agent: MyBrowser
Accept: text/html
Content-length: 15

BODY (MegInputStream)

My name is Paul

Figure 1. An HTTP request containing both a header (structured) part and a body (stream) part.

Figure 1 shows an HTTP request that contains both a header and a body. When WBI receives this request, it is parsed into these two parts. The header information is stored in an object of class DocumentInfo. The body information is made available through an object of class MegInputStream. The body information can then be read from the MegInputStream using its read(...) methods. This technique is used because the body portion of a request or a response can be very long and it is not practical to store it in memory as a string.

HEADER (DocumentInfo)

HTTP/1.0 200 Ok
Server: MyWebServer
Content-type: text/html
Content-length: 36

BODY (MegInputStream)

<html>
<h1>Hello, world</h1>
</html>

Figure 2. An HTTP response containing both a header (structured) part and a body (stream) part.

Figure 2 shows a typical HTTP response. When WBI receives this response, it is parsed in the same way as a request. The header information is stored in a DocumentInfo object and the body is made available through a MegInputStream object.

To produce new requests and responses, a WBI module is given a DocumentInfo object and a MegOutputStream object to manipulate. Simply set a property of the DocumentInfo object using either the setRequestHeader(...) or setResponseHeader(...) methods. The HttpHeader, HttpRequest and HttpResponse classes are designed to make producing such headers easier.

When the header information has been set appropriately, the WBI module may begin writing the body content to the MegOutputStream using its write(...) methods.

In summary, WBI divides both HTTP requests and HTTP responses into two parts: the structured header portion and the unstructured body portion. The header is manipulated through a DocumentInfo object and the body is manipulated through MegInputStream and MegOutputStream objects.

Processing Model

WBI is a programmable HTTP request and response processor. It receives an HTTP request from a client, such as a web browser, and produces an HTTP response that is returned to the client. The processing that happens in between is controlled by the modules programmed into WBI.

Figure 3. A transaction (request/response) flows through a series of WBI MEGs (monitors, editors, generators).

Figure 3 shows the flow through a typical WBI transaction. It goes through three basic stages: request editors, generators, and editors (which would be more appropriately called "document editors"). RequestEditors receive a request and have the freedom to modify the request before passing it along. Generators receive a request and produce a corresponding response (i.e., a document). Editors receive a response and have the freedom to modify the response before passing it along. When all the steps are completed, the response is sent to the originating client. A fourth type of element, the Monitor, can be designated to receive a copy of the request and response but cannot otherwise modify the data flow. The Monitor, Editor, Request Editor and Generator modules are collectively referred to as MEGs.

WBI dynamically constructs a data path through the various MEGs for each transaction. To configure the route for a particular request, WBI has a rule and a priority number associated with each MEG. The rule specifies a boolean condition that indicates whether the MEG should be involved in a transaction. The boolean condition may test any aspect of the request header or response header, including the URL, content-type, client address, server name, etc. Priority numbers are used to order the MEGs whose rules are satisfied by a given request/response.

When it receives a request, WBI follows these steps:

The original request is compared with the rules for all Request Editors. The Request Editors whose rule conditions are satisfied by the request are allowed to edit the request in priority order.
The request that results from this Request Editor chain is compared with the rules for all Generators. The request is sent to the highest priority Generator whose rule is satisfied. If that Generator rejects the request, subsequent valid Generators are called in priority order until one produces a document.
The request and response are used to determine which Editors and Monitors should see the document on its way back to the client. The document is modified by each Editor whose rule condition is satisfied, in priority order. Monitors are also configured to monitor the document either (a) as it is produced from the generator, (b) as it is delivered back to the client, or (c) after a particular Editor.
Finally, the response is delivered to the requester.

MEGs

Together, monitors, editors, and generators are powerful building blocks for intermediary applications.

Request Editor

	Input	Request
	Output	Request
	Action	Modify request
	Examples	Redirect request to a new URL, modify header, insert form data, add/remove cookies

Generator

	Input	Request
	Output	Document
	Action	Produce document that satisfies request, or reject request
	Examples	Read document from local file, forward request to another intermediary or server, dynamically compute document (like CGI), compose document from database, produce control page such as "document moved"

Document Editor

	Input	Request and Document
	Output	Document
	Action	Modify document
	Examples	Add annotations, highlight links, add toolbars, translate document format (e.g., RTF to HTML), change form data, add scripts

Monitor

	Input	Request and Document
	Output	Non
	Action	Receive request and response, and perform computation
	Examples	Gather usage statistics, record user trail, store documents in cache, record filled-out forms

WBI Plugins

A WBI application is usually composed of a number of MEGs that operate together to produce a new function. Such a group of MEGs is a WBI Plugin. Plugins define the basic unit of granularity for installation, configuration, and enable/disable.

The lifecycle of a plugin

A plugin bears some resemblance to a Java Applet. It is a class that WBI instantiates at start-up, similar to how a browser loads an applet. When the plugin class has been instantiated as an object, WBI then calls the plugin's initialize(...) method. After all of the plugins have been initialized, WBI calls the enable() methods for each enabled plugin. The plugin's disable() method is called whenever WBI is disconnecting the plugin (either because the system operator has chosen to disable it, or if WBI is powering down). Finally, the plugin's terminate(...) method is called before the object is destroyed so that it may perform any cleanup operations.

Plugins and MEGs

WBI maintains a single pool of MEGs that are all available to be involved in transactions. This arrangement allows several web applications to all work together inside of WBI simultaneously. Each MEG is associated with one particular plugin. In a plugin's initialize(...) method, the plugin registers its MEGs with WBI, which adds them to this pool. When a plugin is enabled or disabled, all of its MEGs are likewise enabled or disabled. But when WBI is handling a transaction, it only considers the pool of MEGs and is unconcerned with which plugin created them. Note that MEGs have access to the member variables and other resources of their parent plugin. Since only one instance of a plugin exists, and since that plugin is persistant across the entire execution of WBI, the MEGs can then share data and other resources through their parent plugin. MEGs can also decide to alter the set of registered MEGs by enabling and disabling themselves or other MEGs from their plugin. They can even add new MEGs if they choose.

Figure 4. WBI instantiates registered plugins at startup. These plugins then register MEGs (monitors, editors, generators) with WBI, along with their conditions for firing. When a request comes into WBI, it routes the request through the various MEGs according to the conditions. The final result is returned to the client.