XML/XSL

How It Works

Architecture

The XML/XSL plugin consists of a chain of document editors that analyze and (if necessary) modify and process XML resources that were requested by the web browser. The XML/XSL plugin illustrates how WBI can be used as a transcoding platform and how the Meg architecture modularizes an intermediary web application. This documentation focuses on three issues:

1. How to use WBI as a transcoding platform to build a modular web intermediary that can easily be extended.
2. How to control the flow of data and the order in which Megs are invoked.
3. How to pass objects from one Meg to another.

Meg Model

First, let's take a look at the Meg model of the XML/XSL plugin:

The XML/XSL plugin consists of three different editors that analyze and/or modify the response. Each editor lies along the path of a response that is sent back to the client. The stylesheet identification editor is always invoked by WBI when the response contains an XML resource. The next two editors, the XSL processing editor and the XML error editor, are invoked depending on the results of the stylesheet identification. Their main task is to convert the XML source into HTML so that it can be displayed by standard browsers. Though in the diagram it looks like all the editors will be invoked for each request, in fact only the stylesheet identification editor will always be invoked. Whether or not the other two editors will be invoked depends on how the response is routed through the plugin's Megs.

Implementation Details

• The Stylesheet Identification Editor (class StylesheetIdentEditor) determines whether the XML resource of the response is associated with a stylesheet. First, to make sure that the SIE is invoked on any response that contains a XML resource, we have to set the editor's rule:

  content-type text/xml | path *.xml

  Second, the SIE needs to find the statement within the XML source that specifies the stylesheet(s) with which the XML sources are associated. This is done by parsing the XML resource with IBM's XML 4 Java parser. The parser returns an object tree that conforms with the Document Object Model (DOM) and allows easy access to the stylesheet information. The stylesheet can be XSL or any other stylesheet format. If the XML source contains stylesheet information, the SIE downloads the necessary stylesheet file and parses it with the XML parser to ensure well-formedness. Depending on whether the XML source could be parsed and the stylesheet could be downloaded and parsed, the SIE controls the further flow of the response through the remaining Megs of the XML/XSL plugin. There are two cases:

  1. The XML sources and stylesheet information could be parsed and they are both well-formed. In this case, the SIE will force the invocation of the XSL Processing Editor, which converts XML into HTML according to a specified stylesheet.
  2. The XML source does not contain any stylesheet information or either the XML source or stylesheet information could not be parsed. The SIE will then force the invocation of the XML Error Editor, which is used to produce an HTML page explaining why the XML source could not be converted such that it can be displayed by the browser.

  To summarize, the StylesheetIdentEditor (SIE) is the entry point of the XML/XSL plugin. It analyzes the incoming XML source and controls the further processing of the XML source. The two issues that are of interest in this context are the control over the invocation of Megs and the transport of objects between Megs.

• How to control the invocation of a particular Meg from within another Meg
  There are two ways to invoke a Meg or to control the invocation of a Meg. The first is the direct invocation through the method

  forwardRequest(Meg Meg, RequestEvent e)

  of class Meg. By calling this method, WBI will forward the request to the specified Meg. The Meg needs to be of the same type as the calling Meg, that is, an editor can only forward requests to an editor, and a generator can only forward requests to other generators. In forwarding requests, the Meg's conditions and WBI's rule engine is ignored. Note that to use forwardRequest(...) the calling Meg needs a handle to the Meg that is to be invoked.
  The alternative to forwardRequest(...) is to use extra rule keys. As we already know from the programming overview, each Meg has a condition property. In addition to the more common rule statements, such as specifying the content-type or the host of a response, extra rule keys can be used to define a key-value pair. This pair must be matched by the request/response if the Meg is to be invoked. Extra conditions are specified when setting up a Meg:

  xee.setup( "XmlErrorEditor", 
             "$stylesheetprocessing errorXML ...", 
             50 );
  

  This code fragment specifies that the Meg named XmlErrorEditor can only be invoked by WBI when the current request event contains the key-value pair $stylesheetprocessing=errorXML. Such extra rule keys are set by preceeding Megs to make sure that the particular Meg is invoked later in the processing chain. Extra rule keys can be set using the method

    setExtraRuleKey("$stylesheetprocessing", 
                    "errorXML")
  

  of class RequestInfo. The main difference between extra rule keys and forwardRequest(...) is that by using extra rule keys, the Meg that sets the keys has no control as to when the downstream Meg is invoked. The time the target Meg is invoked depends on the other Megs in the system and the target Meg's priority, which is considered by WBI when invoking the next Meg from the processing chain.

• How to transport data from one Meg to another
  Now that we know how to control the invocation of Megs, we need to pass data or objects from one Meg to another. One of the ideas behind the transport of data or objects from one Meg to another is to make a plugin more efficient and have subsequent Megs benefit from the work that preceeding Megs have already done. In the case of the XML/XSL plugin, the SIE checks well-formedness and existence of stylesheet information by parsing the XML source and producing object trees according to the DOM. These trees are also needed to convert XML into HTML according to a stylesheet. To avoid the same computation in different Megs, WBI offers a way to transport data or objects from one Meg to another. Each Meg that wants to transport objects to one of the next Megs in the Meg chain can add transaction data to the request event.

  The method to use is

  setTransactionData( "$XSL_DATA", dataObject )

  of class RequestInfo. Following Megs in the chain can access this data by calling the

  getTransactionData( "$XSL_DATA" )

  of RequestInfo. In the XML/XSL plugin, we use this mechanism to transport the two object trees for the XML and stylesheet sources to XSL Processing Editor, and to transport an error message to the XML Error Editor.

• The XML Error Editor (class XmlErrorEditor) is used to display an error message of an XML source when either no stylesheet information was found or the information found was neither well-formed nor a known stylesheet format. This editor is setup that it can only be invoked by WBI when the extra rule key $stylesheetprocessing = errorXML is set. Once this editor was invoked, it will write an error message that explains why the XML source could not be converted to HTML according to stylesheet. This error message was added to the request event by the StylesheetIdentificationEditor using the WBI data transport mechanism. Before writing the modified XML source to the MegOutputStream, the content-type of the current request event is set to text/html and the content-length is updated according to the additional bytes that were added/replaced in the XML source.

• The XSL Processing Editor (class XslProcessingEditor) is used to produce HTML code from a XML source and its associated XSL stylesheet. Both sources are accessible as object trees (DOM) from the request event by WBI's data transport mechanism. This editor is setup such that it can only be invoked by WBI when the extra rule key $stylesheetprocessing = errorXML is set. Once this editor was invoked, the two object trees from the request event will be processed using the Lotus XSL processor. This creates a new object tree that contains the HTML source. This object tree can then be written to the request event's output stream. Furthermore, the editor updates the content-type to text/html and content-length field according to the new HTML source. If the XSL processing fails and no HTML source can be produced, the XslProcessingEditor sets an extra rule key to allow the invocation of the XmlErrorEditor, and writes the original XML source back to the request event's output stream so it is accessible by the following Megs.

• Sample Meg chains: Now let's take a look at some sample XML transaction as they flow through the XML/XSL plugin. The first image shows the ideal case: an XML source was requested, it contains XSL stylesheet information, and both XML and XSL are well-formed.

  

  First, the StylesheetIdentificationEditor is invoked and analyzes the XML source. Because everything is fine (i.e., XML contains XSL info, and XSL and XML are well-formed) the appropriate extra rule key ($stylesheetprocessing = processXSL) is set and the two object trees are added to the request event. Because the extra rule key was set, at some point downstream, WBI will invoke the XslProcessingEditor which then produces the HTML source that can be displayed by the browser.

  

  The second image shows the sequence of Megs that WBI goes through when the XML source is not well-formed, does not contains stylesheet information, or the stylesheet source is not well-formed or could not be downloaded. In this case, the StylesheetIdentificationEditor, which is always invoked on an XML source, sets the appropriate extra rule key ($stylesheetprocessing = errorXML) and adds an error message to the to the request event. There is no need to route the request event through the XslProcessingEditor because the necessary object trees could not be produced.

  

  Last, there is the case in which the XML and XSL sources are well-formed and the XslProcessingEditor was invoked, but XSL processing failed. In this case, the XslProcessingEditor will set the appropriate extra rule key ($stylesheetprocessing = errorXML) and add an error message to the request event to allow the invocation of the XML error editor.

  Note: All these images are simplified illustrations of a Meg chain. For clarity and simplicity default Megs and Megs of other plugins were omitted.

• Why don't we have just one Meg do it all?
  Theoretically, all this functionality could have been implemented in just one Meg. We did otherwise because:

  • Smaller, well defined Megs increase clarity and simplicity of an application.
  • Small Megs are easier to change, modify and debug.
  • Well defined Megs can be reused in other applications.
  • The current XML/XSL plugin architecture can easily be extended if other stylesheet formats need to be supported. This can be done by writing a new Meg to handle the new stylesheet format (similar to the XslProcessingEditor), and updating the StylesheetIdentificationEditor to acknowledge the new format. This makes changing things easier than working with a single, monolithic aaplication.

• Some key WBI classes that were used:

  Package com.ibm.wbi.protocol.http
  HttpEditor	Extended by StylesheetIdentEditor, XmlErrorEditor and XslProcessingEditor.
  HttpResponse	Used by the plugin editors to modify request event properties, such as content-type and content-length.
  DocumentInfo	Used to access and set different properties of a request event (e.g., set extra rule keys and use WBI's data transport mechanism).