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 URLs pointing to
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:

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:

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:

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:

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:

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:

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:

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: