ASF: XSLTC Native API Documentation

	XSLTC Design
XSLTC Native API Documentation

XSLTC Native API Documentation

XSLTC Compiler API

XSLTC's native API is represented by the org.apache.xalan.xsltc.compiler.XSLTC class. Any application using XSLTC's native API should only have to access methods in this class in order to compile a stylesheet (or a set or stylesheets) into one or more Java classes. The XSLTC has an empty constructor. The class needs to be initialized before each compilation by a call to:

    public void init();

(top)

Compile methods

There is a set of methods for compiling one or more stylesheets into a set of Java classes. The stylesheet can be specified either as a URL, InputStream, InputSource or a Vector containing a set of URLs pointing to stylesheets:

    public boolean compile(URL url);
    public boolean compile(URL url, String transletName);
    public boolean compile(InputStream stream, String transletName);
    public boolean compile(InputSource input, String transletName);
    public boolean compile(Vector stylesheets);

The default behaviour is to output the compiled Java class(es) to one or more Java classes in the current working directory. The name of the main translet class will be obtained from (in order of priority):

that specified in the compile() method
if none is specified (if the parameter is 'null') the name will be generated from the filename specified by the input URL/file/stream
the default translet name (set by setClassName())
the built-in default class name "GregorSamsa"

Additional Java classes will be generated for complex stylesheets. These classes represent elements such as predicates, sort-records, etc. in the stylesheet. Additional classes share the same root name as the main translet class, with a suffix containing a '$'-sign and a sequence number. The result of a single compilation of a complex stylesheet could be:

    GregorSamsa.java
    GregorSamsa$0.java
    GregorSamsa$1.java
    GregorSamsa$2.java
    GregorSamsa$3.java

It is not always desireable having these classes dumped to files in the current working directory. There is one compile() method that will return the Java class definitions as bytecodes. The bytecodes are returned in a two-dimmensional byte array. Each byte-array contains the bytecodes for one Java class:

    public byte[][] compile(String name, InputSource input);

Alternatively, one can first compile the stylesheet into one or more Java class files, and then also retrieve the bytecodes from the compiler:

    public byte[][] getBytecodes();

(top)

Output settings

The default (root) name for the generated Java classes can be set and retrieved by calls to these methods:

    public void setClassName(String className);
    public String getClassName();

One can also specify a package to place the classes in:

    public void setPackageName(String package);

The generated classes can also be wrapped inside a single Java archive (JAR-file):

    public void setJarFileName(String jarFileName);
    public String getJarFileName();

The result file(s) need not be output in the current working directory. Specify the directory to output to by calling:

    public boolean setDestDirectory(String directory);

‌

(top)

Input document locator interface

XSLTC's compiler has an interface that a client application can implement to provide XSL input from alternative sources. Implementing and using this interface is necessary when the top-level stylesheet contains one or more <xsl:include> and <xsl:import> elements that reference stylesheets that cannot be read using standard File or URL classes. The interface that a client must implement is org.apache.xalan.xsltc.compiler.SourceLoader, and its only method is:

    public InputSource loadSource(String href, String context, XSLTC xsltc);

The compiler class, XSLTC, has a method for specifying the implementation of this interface:

    public void setSourceLoader(SourceLoader loader);

This interface shares the same purpose as the URIResolver interface in the JAXP/TrAX API.

(top)

Debug settings

XSLTC can be forced to output debug messages and stack dumps:

    public void setDebug(boolean debug);
    public boolean debug();

(top)

Error handling

All compile() methods return 'true' if the compilation succeeded. The compiler could in such case still generate warning messages. These message could be retrieved a Vector of strings or output directlry to stderr:

    public Vector getWarnings();
    public void printWarnings();

All compile() methods will return 'false' if any serious errors prevented the compiler from generating any Java classes. Error messages are handled similar to warning messages:

    public Vector getErrors();
    public void printErrors();

Note that warning messages are not returned/output by these two methods. A client application should pass both warning and error messages to its user.

(top)

XSLTC Transform API

The steps described in this chapter are covered in these sample source code files:

org.apache.xalan.xsltc.cmdline.Transform
xml-xalan/java/samples/CompiledApplet/TransformApplet.java
xml-xalan/java/samples/CompiledBrazil/TransformHandler.java
xml-xalan/java/samples/CompiledEJB/TransformBean.java
xml-xalan/java/samples/CompiledEJB/TransformHome.java
xml-xalan/java/samples/CompiledEJB/TransformRemote.java
xml-xalan/java/samples/CompiledEJB/TransformServlet.java
xml-xalan/java/samples/CompiledServlet/CompileServlet.java
xml-xalan/java/samples/CompiledServlet/TransformServlet.java

(top)

Transformation input handling

The main input document must be parsed using a SAX handler. The main SAX events (ContentHandler) and lexical declarations (LexicalHandler) are handled by the internal DOM builder. The classes that make up the internal DOM are:

    org.apache.xalan.xsltc.DOM;             - DOM interface
    org.apache.xalan.xsltc.dom.DOMImpl;     - DOM implementation
    org.apache.xalan.xsltc.dom.DOMAdapter;  - DOM-to-translet mapper
    org.apache.xalan.xsltc.dom.MultiDOM;    - DOM multiplexer
    org.apache.xalan.xsltc.dom.DOMBuilder;  - DOM builder interface

The DOMBuilder interface is a wrapper for the standard SAX ContentHandler and LexicalHandler interfaces. The DOMBuilder contains both these interfaces, and it is implemented by an inner class of the DOMImpl class. To build the internal DOM, one has to go through these steps:

    // Create a SAX parser and get the XMLReader object it uses
    final SAXParserFactory factory = SAXParserFactory.newInstance();
    try {
	factory.setFeature(Constants.NAMESPACE_FEATURE,true);
    }
    catch (Exception e) {
	factory.setNamespaceAware(true);
    }
    final SAXParser parser = factory.newSAXParser();
    final XMLReader reader = parser.getXMLReader();

     // Set the DOM's DOM builder as the XMLReader's SAX2 ContentHandler
    final DOMImpl dom = new DOMImpl();
    DOMBuilder builder = dom.getBuilder();
    reader.setContentHandler(builder);

     // Set the DOM's DOM builder as the XMLReader's SAX2 LexicalHandler
    try {
	String prop = "http://xml.org/sax/properties/lexical-handler";
	reader.setProperty(prop, builder);
    }
    catch (SAXException e) {
	 // Can be quitely ignored...
    }

     // Pass the document URI or file-name to the DOM
    dom.setDocumentURI(uri);
     // Parse the input document to populate the DOM
    reader.parse(uri);

The input XML document may contain of reference a DTD. A DTD must be processed by XSLTC in order to support the id() and unparsed-entity-uri() functions. The org.apache.xalan.xsltc.dom.DTDMonitor class can handle DTD declarations and aggregate them for use by a translet. Create your DTDMonitor instance by passing it a reference to your SAX parser:

     // Create a DTD monitor and pass it to the XMLReader object
    final DTDMonitor dtd = new DTDMonitor(reader);

This call ensures that an index is built for all ID attributes described in the DTD:

     // If there are any elements with ID attributes, build an index
    dtd.buildIdIndex(dom, 0, _translet);

And this call ensures that the translet is passed all unparsed entities described in the DTD:

    translet.setDTDMonitor(dtd);

We'll tell you how to create the translet instance in the next section.

(top)

The translet instance

All compiled translets inherit from the AbstractTranslet class, so it is safe to cast your tranlet instance to that class:

    Class transletClass = Class.forName(transletName);
    AbstractTranslet translet = (AbstractTranslet)transletClass.newInstance();

Note that the translet instance is not reusable, so you would benefit from keeping the reference to the translet class.

Once you have your translet instance you can start playing around with it. First you want to pass parameters to it:

    // Pass global parameters
    translet.addParameter("my-param", "my-value");

You also want to remember to pass your DTD handler to the translet. (See previous section.)

(top)

Preparing the output handler

The compiled translet does not contain all the functionality needed to format the output document. This is handled by our output post-processor org.apache.xalan.xsltc.runtime.TextOutput. This class needs to be instanciated with three parameters; a SAX ContentHandler, a LexicalHandler and a string containing the desired output encoding. The user should normally provide the two handlers, and the output encoding can be obtained from a field in the translet:

    // Get the output encoding (from any <xsl:output> element
    String encoding = translet._encoding;

    // Create a translet output handler and plug in the SAX handlers
    TextOutput textOutput = new TextOutput(myContentHandler, myLexicalHandlere, encoding);

(top)

Transformation

With the internal DOM built, the DTD monitor in place, and the output handler set up, we're ready to run the actual transformation:

    // Transform and pass output to the translet output handler
    translet.transform(dom, textOutput);

(top)

The DOM cache interface

Parsing the input document and building the internal DOM is a fairly expensive operation, and it is often desireable to build a cache holding frequently accessed internal DOMs. An application using XSLTC's native API can accomplish this by implementing the org.apache.xalan.xsltc.DOMCache interface. The application will still have to call the translet's transform() method with a DOM from the cache. But, the translet may have to load additional documents if the original stylesheet contained calls to the document() function. The translet can be instructed to read DOMs from a cache by calling this method:

    public void setDOMCache(DOMCache cache);
    public DOMCache getDOMCache();

(top)