Notes on Porting an XSLT/HTML Application to XForms/SOAP

Motivation

Several years ago, I wrote a front-end to 4Suite that fullfilled the following requirements:

  • Default Content management
  • System management
  • Adhoc RDF Query interface

It was to be written as a set of XSLT stylesheets which generated HTML pages composed mostly of HTML forms. The 4Suite repository consists of user-specified content (XML/RDF and otherwise) as well as system resources: XML documents that provide repository-functionality such as user-management, servers, XML-to-RDF mapping, etc. The idea was to build special user interface for managing these system documents. The less satisfactory alternative is to modify the raw XML. This would require an understanding of the structure of these documents as they were being modified and introduced the possibility of creating invalid documents which broke their expected functionality.

At the time, I thought that XSLT alone was the perfect means to do this because of the whole slew of extensions available for managing resources in the underlying 4Suite repository. Mike Brown wrote a very concise overview of what the 4Suite repository is, available here. There is also a useful overview on the architecture of 4Suite's XSLT-based web application framework.

In the end, this project (called the 4Suite Dashboard) became very difficult to maintain because of the spaghetti-like nature of the XSLT. There are two factors in this:

  • At the time when I wrote it, I was less adept at using XSLT to its strengths
  • The cumbersome, ad-hoc processing of form data - which was the primary component of the user interface

As a result, it has slowly lagged behind with the rest of 4Suite and is essentially unusable because of the inordinate amount of effort that would be neccessary to refactor it to a more maintainable state. Motivated mostly by the great success we have had in the Cleveland Clinic Foundation with research regarding the use of XForms as the primary means of serving user-interfaces to a semi-structured, metadata-driven database, I decided to port the old Dashboard code to an XForms/SOAP-based solution.

The XForm 'sweet-spot'

The primary motivating factor was the idea that with XForms you kill several birds with one stone:

  1. You move a majority of XML processing to the client
  2. You reduce the complexity of request processing by piggy-backing on the XForms approach to Web applications
  3. Makes for an overall cleaner architecture by seperating what the user sees from the actual processing (by the application) of the user's actions within the user-interface
  4. Session management: SOAP messages can be submitted within an existing session.

The result was a cleaner, leaner application that was much easier to implement, given my better appreciation for XSLT as the framework for an application as well as my familiarity with XForms. Below is a high-level diagram of the main components:

XDashboard Architecture

Secure, remote service invokations

One of the goals of the port was to demonstrate the submission of session-managed SOAP messages. By having a session created at the server when a request to manage a resource came, the session id can be passed along with the resulting XForm so all subsequent service requests will authenticate at the repository using this session id (generated at the server). Since the session is specific to the 4Suite user that requested the XDashboard screen (an HTTP authentication request is sent when the application is originally loaded, requiring a valid 4Suite user to enter their credentials), service requests on resources not available to the user will fail with an appropriate SOAP Fault detailing the server-side security violation.

Base64 encoded XML content from an XForm

The other interesting thing I was able to demonstrate was the usefullness of submitting XML strings as base64 encoded content via SOAP. One of the primary arguments against SOAP as a remote procedure protocol is it's use of a verbose syntax as the medium for communciation (XML). Now imagine a SOAP message whose purpose was for modifying the content of an existing XML resource. The instinctive first solution would probably be to submit the XML document as a fragment within the SOAP envelope like so:

[SOAP:Envelope]
   [SOAP:Body]
     [foo:setContent]
       [path] .. path to document [/path]
       [src]... new document as a fragment ...[/src]
     [/foo:setContent]
   [/SOAP:Body]
[/SOAP:Envelope]

But imagine the extra processing that the SOAP endpoint must contend with when you consider the SOAP message as a whole. 4Suite's SOAP server allows content to be submitted as plain text or as Base64 encoded content. In addition, the XForm's upload component is restricted only for nodes with the following datatypes:

  • xsd:anyURI
  • xsd:base64Binary
  • xsd:hexBinary

The result of this is that for nodes bound to xsd:base64Binary, an XForms processor is responsible for Base64 encoding data selected via the xforms:upload component for submission, which simplifies the problem for the case where the XML content you wish to submit is uploaded from a file on the local filesystem of the client. However, the previous dashboard allowed XML content for an arbitrary resource in the repository to be submitted from a textarea. In the XForms scenario, this caused the requirement of having a javascript function do this encoding explicitely and binding the encoding to text collected from a textarea.

Ironically, at the time when I was dealing with this problem there was an ongoing thread in the W3C's www-forms list about the ins/outs of encoding XML content as strings for submission from an XForm.

The XDashboard Services

The following is the list of services setup and used by the application (with an accompanying description of what each does):

  • addAcl (Add an acl identifier to the acl key. If the specified key does not exist on the resource this function has the same functionality of setAcl)
  • createContainer (Create's a 4Suite repository Container)
  • createDocument (Creates a document with the given document definition name, path, type, and source. if the type is not specified it will attempt to infer the type based on IMT and the src)
  • createRawFile (Creates a raw file resource, using the specified, path, internet media type, and source string.)
  • delete (Delete this object from the repository)
  • fetchResource (Fetch a resource from the system. path is a string)
  • getContent (Get the string content of this resource)
  • removeAcl (Remove the acl identifier from the acl key. If the specified aclKey is not present on the resource or the specified aclIdent is not in the key, then do nothing. Remember that entries inherited from the parent are not included in the acl on the actual resurce. In order to override inherited permissions, set to no access rather than trying to remove)
  • setAcl (Replace the aclKey with a single entry of aclIdent)
  • setContent (Set the string content of this resource)
  • setImt (Sets the Internet Media Type of the raw file resource)
  • setPassword (Change the password of the specified user to the SHA-1 hashed value)
  • setServerRunning (change the state of a 4Suite repository server to running/stopped. This operation is executed as an XUpdate at the server-side modifying the Server document to reflect the correct state. The XUpdate document is serialized from the client and submitted to the repository).
  • xUpdate (Allows XML content to be updated with the XUpdate protocol. updateSrc is a string that represents the XUpdate to be applied to the resource. extraNss is a dict of additional namespace bindings to pass to the XUpdate processor, if necessary)

Compliance Notes

As FormsPlayer is probably the most mature of all the XForms processors available (the list is growing), it was the targeted XForms processor for this application. For the most part, this doesn't introduce any issues of non-compliance with XForms as everything was done using mostly XForms 1.0, a little XForms 1.1 (xforms:duplicate action, primarily), and 2 FormsPlayer specific capabilities.

It must be mentioned, however, that FormsPlayer is an Internet Explorer plugin solution to XForms. The tradeoff, essentially, is browser compatibility for the full complement of XForms functionality that comes with FormsPlayer. Below is a briefing of the deviations from pure XForms 1.0:

XForms 1.1 constructs

xforms:duplicate was used for the copying of nodes from a source to an origin

Forms Player specific capabilities

  • xforms:setvalue was used for deep-copying nodes to a target location without destroying existing childnodes (the limitation of it's XForms 1.0 counterpart: xforms:copy)
  • fp:serialise function was used to facilitate the retrival of a node's XML representation in order to Base64 encode for submission
  • fp:HTMLserialise was used for debugging purposes
  • Forms Player's inline capability was used in order to access external javascript functions from within XPath expressions

Resources

This application relies on the most recent version of 4Suite's SOAP server (can be retrieved from CVS). A listing of the most recent version of this SOAP server can be found here. The XDashboard is bundled as a 4Suite repository application and so must be installed to a running repository using the 4ss install command. It should be sufficient to unpack the tar / zip ball and run 4ss install against the setup.xml file.

The XDashboard application can be downloaded from as a tgz archive or zip archive from:

Bear in mind, this application is a proof of concept / demo, so it's likely to have undiscovered typos/bugs

This demo/application makes use of and refers to the following third-party resources:

  • Mike Brown and Jeni Tennison's tree-view.xslt - For rendering a decorated view of an XML document
  • Micah Dubinko's XForms Relax NG schema
  • MSXML's default IE XML DHTML stylesheet [see]: - For rendering a decorated view of an XML document
  • xslt2xform's 'Powered by XForm' logo - Pending a winner to Micah's logo contest

[Chimezie Ogbuji]

via Copia