LotusXSL API Overview
Document Author: Scott BoagDocument Date: August 29, 1999
Software Version: 0.18.1 [02-September-1999]
|
LotusXSL API OverviewDocument Author: Scott BoagDocument Date: August 29, 1999 Software Version: 0.18.1 [02-September-1999] |
This is meant as a general overview for the LotusXSL API. See the API Documentation for more specific information, or the Version Documentation for use and version information.
LotusXSL takes as primary input a source XML document and a stylesheet document. It sends output events to a derivative of a SAX org.xml.sax.DocumentHandler, called a FormatterListener.
LotusXSL is composed of two main packages: com.lotus.xpath, and com.lotus.xsl. The XPath package is meant to be used on it's own, but for convenience is packaged in the same JAR as the main processor.
The main XSLT and XPath engines are meant to be independent from any given DOM implementation or XML implementation. It does this by bottle-necking all parser-dependent calls through the XMLParserLiaison interface.
LotusXSL provides base servlet support to apply XSL stylesheets (retrieved from various sources) to XML (also retrieved from various sources). See the DefaultApplyXSL class.
LotusXSL also provides a simple Applet for hosting the LotusXSL processor. See the LotusXSLControl class.
The primary api in LotusXSL is implemented in the XSLProcessor class, which is responsible for processing an input source tree through a stylesheet.
The XSLProcessor's process(...) methods are the primary
public entry points. The combination of inputs and outputs
form a three dimensional array of source-tree inputs (URLs/Filenames, Readers, DOM nodes),
XSL stylesheet inputs (URLs/Filenames, Readers, DOM Document, pre-processed stylesheet,
none (get the stylesheet from the xml-stylesheet PI)),
and result-tree options (DOM nodes, writers, SAX Document handlers). Thus there
are 35 basic input/stylesheet/output combinations. I've tried to represent the
most used of these in the process() functions. If you can't find the combo you need,
you can always use the primary process() function that takes all 11 arguments -- pass
null for those you don't specify.
Example:
foo.xml:
<?xml version="1.0"?>
<doc>Hello</doc>
foo.xsl:
<?xml version="1.0"?>
<xsl:stylesheet xmlns:xsl="http://www.w3.org/XSL/Transform/1.0">
<xsl:template match="doc">
<out><xsl:value-of select="."/></out>
</xsl:template>
</xsl:stylesheet>
transform.java:
package uri2stream;
import org.xml.sax.SAXException;
import com.lotus.xpath.XPathException;
import com.lotus.xsl.XSLProcessor;
import java.io.PrintWriter;
import java.io.FileWriter;
public class transform
{
public static void main(String[] args)
throws java.io.IOException, java.net.MalformedURLException, org.xml.sax.SAXException
{
XSLProcessor processor = new XSLProcessor();
PrintWriter pw = new PrintWriter( new FileWriter("foo.out") );
processor.process("foo.xml", "foo.xsl", pw);
}
}
foo.out:
<out>Hello</out>
In order for the XSLProcessor class to work it must have an object that implements a XMLParserLiaison interface and normally a Formatter class.
At this time there are 3 classes that implement the XMLParserLiaison interface and the Formatter interface:
If you don't pass a liaison via the XSLProcessor constructor, it will default to the XML4JLiaison4dom class.
All of these liaison classes derive from the XMLParserLiaisonDefault class, which can be used by itself for any DOM, including programatically created DOMs, as long as XML parser services are not required to handle xsl:include and the like.
LotusXSL process the input XSLT document into an internal representation, the Stylesheet class. You can compile the stylesheet separately, before the transformation is complete, via the processStylesheet method. This is especially useful when you need to get information from the stylesheet before the tranformation occurs, for instance, when you need to find out the output encoding in order to construct the right kind of Writer. You can also serialize the stylesheet object to disk, but I wouldn't, if I were you. The serialized stylesheet is very big, and the read negates any performance improvement you might get. The size of the serialization might be a bug, or it might just be the nature of the beast... we're not sure yet. We'll work on a sane serialization format for the next version of LotusXSL.
Stylesheet parameters can be set via the setStylesheetParam method. This method takes as input an XObject class or derivative. The XObject class itself can hold any kind of Java object, if you need to pass it to an extension. Each XObject type has a convenience function on the XSLProcessor class to make it easy to create:
LotusXSL is thread-safe for one instance per thread. However, if you reuse the processor instance, you should call reset() between calls.
The XPath engine has pluggable backend drivers called XLocator interfaces. The default implementation of the XLocator is the SimpleNodeLocator class. Though users of the API can implement their own XLocators for custom data access, it is not for the faint of heart. An example of implementing a custom XLocator for SQL data access, that derives from the SimpleNodeLocator class, can be found in the sql folder in this distribution.
LotusXSL now contains a debugger interface in the trace package. These interfaces should be looked upon as a work in progress, possibly to be replace by a more standard interface in the future. The source code information given is somewhat limited by what the SAX interface give me... the line and column numbers at the *end* of the event. I'll have to work on obtaining the character selection of the executing event. Also, at this time there is no source tree line information available. Again, I'll be working on this. The interfaces are:
The source code is in the 'com/lotus/xsl' directory.
The XSLProcessor class class is where the main stuff is going on. This is a big file, so I highly recommend using an IDE.
The XPaths are parsed in the XPathProcessorImpl class, the result XPath object is performed in the XPath class, and the query and pattern match is performed in the SimpleNodeLocator class.