Rabbit blowing horn Work the Web

Release Notes for LotusXSL

Document Author: Scott Boag
Document Date: Wed Jul 14 13:03:41 GMT-0400 (EDT) 1999
Software Version: 0.17.4 [14-July-1999]

1. Introduction

XSL is a language for expressing stylesheets. It consists of two parts:

  1. XSLT is a language for transforming XML documents into other XML documents, and
  2. an XML vocabulary for specifying formatting semantics (called Formatting Objects).

The Lotus XSL Processor implements only the first part of XSL, the April 21 XSL Transformations (XSLT) Draft Specification.

An XSLT stylesheet specifies the transformation of a class of XML documents by describing how an instance of the class is transformed into another XML tree of nodes.

LotusXSL uses Version 1.1.16 or 2.0.9 of IBM's XML for Java (called "XML4J") to parse an input XML document, or it can be adapted to other DOM-producing mechanisms. LotusXSL produces SAX events, an output DOM, or XML result document based on the transformations specified in the XSL stylesheet.

The processor can be used from the command line, from a servlet, or from a wrapper applet.

New code provides base servlet support to apply XSL stylesheets (retrieved from various sources) to XML (also retrieved from various sources). See the DefaultApplyXSL documentation. (Many thanks to the WebSphere folks for this.)

Stylesheets that worked with the previous version of LotusXSL will have to be upgraded to match the new draft. Watch for stylesheets that declared <xsl:stylesheet> with the xmlns:xsl="http://www.w3.org/TR/WD-xsl" namespace declaration. The namespace should now be xmlns:xsl="http://www.w3.org/XSL/Transform/1.0".

LotusXSL contains a DTD for XSL when used for HTML. (Thanks be to Henrique M. Holschuh for this). This DTD should not be used for run-time production when performance is a concern, but is useful during the development stages. It is used in the readme XSL.

A local copy of the IBM LotusXSL Comercial License Agreement is included.

This version has had low-hanging-fruit performance enhancements over version 0.17.0. Future versions will take more radical steps to obtain the kind of performance needed for production environments.

Processing with validation turned on does not work when using the 2.0.9 version of XML4J. This is an issue with XML4J, and is being addressed by that team.

Thanks goes to Thomas Rowe, Sanjiva Weerawarana, Don Day, David Marston, David A Epstein, Noah Mendelsohn, Dean Burson, Joseph Kesselman, Pat O'Connor, Mike Pogue, Chip Faulkner, Paul Dick, Adam Peller, David Bertoni, the XSL WG, and others, for the support, help, and feedback they have given! Also, many thanks for all the folks who have downloaded LotusXSL so far, and given me feedback, whether good or bad, and bug reports! Special thanks to Dan, Henrique, and Craig!


2. Installation Instructions

  1. Install Sun's JDK-1.2 or Sun's JRE-1.2 (it will work fine with 1.1.6 or 1.1.7 versions of the Java runtime also).
  2. Install Version 1.1.16 or 2.0.9 of IBM's XML for Java
  3. Unzip Lotus XSL Processor to your hard drive (Assuming you haven't already.)
  4. Either have XML4J on the system class path, or copy the XML4J jar into the LotusXSL directory. I recommend having it on the system class path. To install XML4J and LotusXSL onto the system class path, do something like:
    set CLASSPATH=\xml4j_2_0_6\xml4j.jar;lotusxsl.jar;js.jar;%CLASSPATH%
    in your autoexec.bat.

To test, you can go into the 'testSuite\xml4j2dom' directory and type 'test accp\accp01'. You should see it process the files with no complaints. If it complains, you may have to adjust the command name or classpath setup in the testsuite\xml4j2dom\test.bat file.

In the LotusXSL root directory there is a 'run' batch file, which you pass command line parameters. These instructions use version 2.0.9 of XML4J with the DOM classes. To use XML4J 1.1.16 you'll need to change the batch files to call com.lotus.xsl.xml4j.ProcessXSL or, to use the 2.0.9 version with the TX classes, call com.lotus.xsl.xml4j2tx.XML4JLiaison.

The command line utility is com.lotus.xsl.xml4j.ProcessXSL. It can take the following command line switches:

        -IN inputXMLURL
        -XSL XSLTransformationURL
        -OUT outputFileName
        -PARSER fully qualified class name of parser liaison
        -E (Do not expand entity refs)
        -V (Version info)
        -QC (Quiet Pattern Conflicts Warnings)
        -Q  (Quiet Mode)
        -LF (Use linefeeds only on output {default is CR/LF})
        -CR (Use carriage returns only on output {default is CR/LF})
        -ESCAPE (Which characters to escape {default is <>&"'\r\n}
        -INDENT (Control how many spaces to indent {default is 0})
        -TT (Trace the templates as they are being called)
        -TS (Trace each select.)
        -TTC (Trace the template children as they are being processed)
        -VALIDATE (Set whether validation occurs.  Validation is off by default)
        -EDUMP (Do stackdump on error)
        -XML (Use XML formatter and add XML header)
        -TEXT (Use simple Text formatter)
        -HTML (Use HTML formatter)
        -STRIPCDATA (Simply strip CDATA sections. Must have -XML or -HTML)
        -ESCAPECDATA (Escape characters in CDATA.  Must have -XML)
        -PARAM name expression (Set a stylesheet parameter)
      

There are now UNIX Bourne shell script files:

run.sh
run processor (with 2.0.9 version of XML4J) in the form of: run -in foo.xml -xsl foo.xsl -out foo.out
testSuite/xml4j1tx/test.sh
Test LotusXSL with XML4J 1.1.16.
testSuite/xml4j2dom/test.sh
Test LotusXSL with XML4J 2.0.9 Generic DOM.
testSuite/xml4j2tx/test.sh
Test LotusXSL with XML4J 2.0.9 TX compatibility classes.

You may have to edit these in order to have the correct path to the XML4J jars. There are, of course, corresponding .bat files.


3. Samples

See the Demonstration Page for some fairly simple examples of producing XML-styled HTML. [NOTE: This requires Java 1.1 and so will not work on earlier versions of browsers that only support Java 1.0.] Most of the XML and XSL files that are used, are in the 'samples' directory. However, probably the best sample is the XSL and XML that produced this file. It is located in the 'readme_production' directory.

I hope to be getting some more work done on better samples over time. If you come up with something cool that you wouldn't mind sharing, please let me know!


4. Test Suite

Our test suite, while not comprehensive, it is an attempt to work towards some methodical testing of features. It's also a good place for XSL users to go when they need to figure out how to do something. The test suite files are in the 'testSuite' directory.

We've been reorganizing the testsuite. Currently, the suite is incomplete. We're working towards migration of the previous test cases to the new scheme.

We've been working towards testing interoperability between this and other XSL processors. If you find an inconsistency, please let us know.

The testsuite directory has 3 parser-aware subdirectories for testing with the various XML4J parser options:

'testSuite\xml4j1tx' directory
Test LotusXSL with XML4J 1.1.16.
'testSuite\xml4j2dom' directory
Test LotusXSL with XML4J 2.0.9 Generic DOM.
'testSuite\xml4j2tx' directory
Test LotusXSL with XML4J 2.0.9 TX compatibility classes.

In each of these directories, testall.bat will run through the entire testsuite. Output files will be created in the current directory.

Please: if you have stylesheet fragments that you think are good tests, please donate them to the cause...


5. API

Please see the API Overview document for information about the LotusXSL Application Programmer's Interface.

The API Documentation is in the 'apidocs' directory.


6. Source Code

The source code is in the 'com\lotus\xsl' directory.

The XSLProcessor class is where the main stuff is going on. This is a big file with lots of nested classes, so I highly recommend using an IDE. To get an overview of the tree walks and general process flow, look at the file header in this class.

Both the pattern matching and the queries are handled in the QueryEngine.

The XML4J liaison stuff is handled in the XMLParserLiaison for XML4J 1.1.16, the XMLParserLiaison for XML4J 2.0.9 DOM classes, and the XMLParserLiaison for XML4J 2.0.9 TX classes.


7. XML to HTML Conversion

I now support HTML special knowledge when the result namespace is HTML, when writing to a PrintWriter. When you pass a PrintWriter to one of the process functions, LotusXSL calls the toMarkup function in the supplied Formatter interface, passing in the URI for the result namespace. If it is the URI for the HTML namespace ("http://www.w3.org/TR/REC-html40"), it then prints the result tree using HTML rules. For instance:

<?xml version="1.0"?>
<xsl:stylesheet xmlns:xsl="http://www.w3.org/TR/WD-xsl"
xmlns="http://www.w3.org/TR/REC-html40" result-ns="">
<xsl:template match="/">
<HTML>
<script><![CDATA[
document.write("<P>Hi Oren");
]]></script>
<BODY>
Some text.<BR/>
Some more text.
</BODY>
</HTML>
</xsl:template>
</xsl:stylesheet>

will produce:

<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN">
<HTML><SCRIPT>
document.write("<P>Hi Oren");
</SCRIPT><BODY>
Some text.<BR>
Some more text.
</BODY></HTML>

Notice the removal of the CDATA brackets, the removal of the '/' from the BR tag, and the addition of the HTML doc type.

You can also take a look at the source to this file to see how well it does.

This will only work when using one of the process interfaces that stream to a PrintWriter.


8. Tips


9. Extension Mechanism

You can use the xsl:functions element to declare Java or JavaScript functions that can then be called from the XSLT expressions. In order to use JavaScript, you must have js.jar on your class path.

The ns attribute on xsl:functions tells the processor which namespace to associate with the extension. The value of the ns attribute must be a prefix that is declared via the xmlns mechanism.

An example of calling a Java function:

<xsl:stylesheet xmlns:xsl="http://www.w3.org/XSL/Transform/1.0"
                xmlns:lxslt="http://xsl.lotus.com/">

  <xsl:functions ns="lxslt" type="application/java" classid="testSuite.EXT.CurrentDate"/>

  <xsl:template match="/">
    <HTML>
      <H1>Simple test for Java extension.</H1>
      <HR/>
      <P>Should print the current date:</P>
      <P><xsl:value-of select="lxslt:currentDate()"/></P>
    </HTML>
  </xsl:template>
 
</xsl:stylesheet>

See the Tips section for an example of calling JavaScript.

Parameters are passed to the extensions as strings, NodeLists, or DocumentFragments (result tree fragments). Automatic type conversion from nodes to strings and numbers is not very good, so you may need to cast the parameter in the calling expression.

Result tree fragments are passed as DocumentFragments. You can call the getOwnerDocument() method to get an appropriate factory for creating result tree nodes. You can also cast the DocumentFragment to a com.lotus.xsl.ResultTreeFrag. Having some sort of result tree fragment is the only good way of creating nodes for insertion into the result tree. Otherwise you can simply return a string or number. In the future we will have a way to write directly into the output stream.

XSLT variables can hold any return from an extension function, and can be used later for passing into other extension functions.

In Java, you can call static functions or member functions. If you wish to call a member function, the first argument will be used as the this reference. An example:

<xsl:stylesheet xmlns:xsl="http://www.w3.org/XSL/Transform/1.0"
                xmlns:date="http://java.sun.com/products/jdk/1.1/docs/api/java.util.Date.html">

  <xsl:functions ns="date" type="application/java" classid="java.util.Date"/>

  <xsl:template match="/">
    <HTML>
      <H1>Simple test for creating an instance of a Java object.</H1>
      <HR/>
      <P>Should print the current date:</P>
      <P><xsl:value-of select="date:toString(date:new())"/></P>
    </HTML>
  </xsl:template>
 
</xsl:stylesheet>

Notice that new() is used to construct a new instance.

You can see more examples of calling extensions in the testsuite\ext directory.


10. Proprietary Extensions

The previous proprietary features of LotusXSL have been replaced by standard features in XSLT.


11. Version Notes

11.1. Not Yet Implemented

This section will give you an idea of what I haven't implemented yet.

11.2. Known Bugs

Bugs I haven't been able to fix yet for one reason or the other.

11.3. Features and Enhancements To Do

There are lots of potential features that will be going into the draft. Rather than trying to enumerate these, I'll enumerate what I plan to do that is not driven by the draft.

11.4. Changes Since Last Version

July 14, 1999 (Version 0.17.4)

June 24, 1999 (Version 0.17.3)

June 15, 1999 (Version 0.17.2)

May 24, 1999 (Version 0.17.1)

May 3, 1999 (Version 0.17.0)

April 7, 1999 (Version 0.16.4)

April 2, 1999 (Version 0.16.4)

March 22, 1999 (Version 0.16.4)

March 11, 1999

March 11, 1999 (Version 0.16.4d1)

March 11, 1999 (Version 0.16.3)

March 10, 1999

March 8, 1999

March 3, 1999

March 2, 1999

February 28, 1999

February 26, 1999

February 08, 1999 (Version 0.16.2)

February 01, 1999

January 25, 1999

January 21, 1999

January 15, 1999

December 20, 1998

December 17, 1998

December 15, 1998

December 11, 1998

November 28, 1998 to 18-May-1998

  1. Details deleted.

18-May-1998 to 30-June-1998

  1. Old submission version. Details deleted.

12. Contact Info and Bug Reports

  1. Lotus XML Contact Person: Noah Mendelsohn
  2. IBM Representatives to the XSL W3C Working Group: Sanjiva Weerawarana and Don Day
  3. Contact information for myself: Scott Boag
          Lotus Development Corporation 
          One Rogers Street 
          Cambridge, MA, 02142-1245 
          (voice) 617-693-5295 
          (fax) 617-693-8676 
          (email) scott_boag@lotus.com
        

13. Glossary

XSL Instruction
Any tag with an XSL namespace prefix.
XSL Template Instruction
Any tag with an XSL namespace prefix that occurs inside an xsl:template element.
Template Child
Any node that is a child of an xsl:template element.
Source Tree
The tree input to the XSL process.
Result Tree
The tree that is output by the XSL process.
Stylesheet Tree
The stylesheet tree produced from the XSL file.
Pattern List
A parsed query or match pattern.