| 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();

| 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 `URL`s 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();

| 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);

| 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.

| Debug settings |

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

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

| 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.

| 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`

| 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.

| 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.)

| 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);

| 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);

| 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();

Copyright © 2004 The Apache Software Foundation. All Rights Reserved.