<?xml version="1.0" standalone="no"?>
<!DOCTYPE s1 SYSTEM "../../style/dtd/document.dtd">
<!--
 * The Apache Software License, Version 1.1
 *
 *
 * Copyright (c) 1999 The Apache Software Foundation.  All rights 
 * reserved.
 *
 * Redistribution and use in source and binary forms, with or without
 * modification, are permitted provided that the following conditions
 * are met:
 *
 * 1. Redistributions of source code must retain the above copyright
 *    notice, this list of conditions and the following disclaimer. 
 *
 * 2. Redistributions in binary form must reproduce the above copyright
 *    notice, this list of conditions and the following disclaimer in
 *    the documentation and/or other materials provided with the
 *    distribution.
 *
 * 3. The end-user documentation included with the redistribution,
 *    if any, must include the following acknowledgment:  
 *       "This product includes software developed by the
 *        Apache Software Foundation (http://www.apache.org/)."
 *    Alternately, this acknowledgment may appear in the software itself,
 *    if and wherever such third-party acknowledgments normally appear.
 *
 * 4. The names "Xalan" and "Apache Software Foundation" must
 *    not be used to endorse or promote products derived from this
 *    software without prior written permission. For written 
 *    permission, please contact apache@apache.org.
 *
 * 5. Products derived from this software may not be called "Apache",
 *    nor may "Apache" appear in their name, without prior written
 *    permission of the Apache Software Foundation.
 *
 * THIS SOFTWARE IS PROVIDED ``AS IS'' AND ANY EXPRESSED OR IMPLIED
 * WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
 * OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
 * DISCLAIMED.  IN NO EVENT SHALL THE APACHE SOFTWARE FOUNDATION OR
 * ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
 * SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
 * LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF
 * USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND
 * ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
 * OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT
 * OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
 * SUCH DAMAGE.
 * ====================================================================
 *
 * This software consists of voluntary contributions made by many
 * individuals on behalf of the Apache Software Foundation and was
 * originally based on software copyright (c) 1999, Lotus
 * Development Corporation., http://www.lotus.com.  For more
 * information on the Apache Software Foundation, please see
 * <http://www.apache.org/>.
 -->
<s1 title="Using XSLTC">

<ul>
<li><link anchor="intro">Introduction</link></li>
  <li><link anchor="classpath">Setting the system classpath for XSLTC</link></li>
  <li><link anchor="compile">Compiling translets from the command line</link></li>
  <li><link anchor="run">Running translets from the command line</link></li>
  <li><link anchor="api">Calling XSLTC with the TrAX/JAXP API</link></li>
  <li><link anchor="native_api">Calling XSLTC with the native API</link></li>
  <li><link idref="samples" anchor="translets">Sample translets</link></li>
  <li><link idref="xsltc_constraints">XSLTC release notes</link></li>  
</ul>
<p>See also: <jump href="xsltc/index.html">XSLTC Design</jump></p>
<anchor name="intro"/>
<s2 title="Introduction">
<p>XSLTC provides a compiler and a runtime processor. Use the compiler to compile an XSL stylesheet into a translet, a set of Java classes. Use the runtime processor to apply the translet to an XML document and perform a transformation.</p>
<note>To compile translets, you must be running the JDK or JRE 1.2 or higher. You can run translets with the JDK or JRE 1.1.8 or higher.</note>
</s2><anchor name="classpath"/>
<s2 title="Setting the system classpath for XSLTC">

<p>
The jar file structure of the XSLTC component has changed. In the original
structure the xsltc.jar file contained only the XSLTC classes, and the
other support jar files needed to be in the user's class path.
 If you want to use this model refer to the subsection below 
'Unbundled System Classpath'.  In the newer model, all of the support 
classes have been bundled with the XSLTC classes into one xsltc.jar file. 
The size of the bundled jar file is significantly
larger, around 1.2MB. However classpath setup is significantly easier.
Refer to the subsection 'Bundled System Classpath' below.
</p>
</s2>

<s3 title="Bundled System Classpath">
<p>
To use this newer approach, simply put xsltc.jar in your classpath.
No need to mention the others (BCEL.jar, JLex.jar, regexp.jar, java_cup.jar,
runtime.jar). 
<note>Be sure to also a JAXP XML parser, such as xercesImpl.jar and xml-apis.jar, which are in our distribution.</note>
</p>
</s3>

<s3 title="Unbundled System Classpath">
<p>To compile translets, run translets, and use the XSLTC API, put the following on the system classpath:</p>
<table>
<tr>
  <th>Classes or JAR</th>
  <th>To compile a translet</th>
  <th>To run a translet</th>
  <th>To use the XSLTC API</th>
</tr>
<tr>
  <td>the translet</td>
  <td></td>
  <td>required</td>
  <td>required</td>  
</tr>
<tr>
  <td>xsltc.jar</td>
  <td>required</td>
  <td>required</td>
  <td>required</td>  
</tr>
<tr>
  <td>runtime.jar</td>
  <td>required</td>
  <td></td>
  <td>required</td>  
</tr>
<tr>
  <td>BCEL.jar</td>
  <td>required</td>
  <td></td>
  <td>required</td>  
</tr>
<tr>
  <td>JLex.jar</td>
  <td></td>
  <td></td>
  <td>required</td>  
</tr>
<tr>
  <td>java_cup.jar</td>
  <td></td>
  <td></td>
  <td>required</td>  
</tr>
<tr>
  <td>regexp.jar</td>
  <td>required</td>
  <td></td>
  <td>required</td>  
</tr>
</table>
<p>The JAR files listed above are in the &xslt4j; bin directory. The translet is the set of class files or the JAR file that you generate with the compiler; see <link anchor="compile">Compiling translets</link>.</p>
<p>If you are using JDK or JRE 1.1.8, also include classes.zip on the classpath. If you are using JDK or JRE 1.2, include tools.jar on the classpath.</p>
<note>For the time being, the Xalan processor and XSLT do not yet use the same DOM, SAX, and parser infastructures. Accordingly, you may find it necessary to reset the system classpath each time you switch between the Xalan processor and XSLTC. For information on setting the classpath for the Xalan processor, see <link idref="getstarted" anchor="classpath">Setting the system classpath for Xalan</link>.</note>
</s3>
<anchor name="compile"/>
<s2 title="Compiling translets from the command line">
    <ul>
      <li><link anchor="comp-synopsis">Synopsis</link></li>
      <li><link anchor="comp-args">Flags and arguments</link></li>
      <li><link anchor="comp-examples">Examples</link></li>
    </ul>
	<p>The XSLT Compiler is a Java-based tool for compiling XSLT
	stylesheets into lightweight and portable Java byte codes 
	called translets.</p>  

	<p>The XSLT Compiler can be run on any platform including UNIX,
	Windows, NT, or Mac that supports Java 1.2.x or later. The generated
	translets can be run on any platform that supports a Java
	Runtime Environment, including a Palm Pilot with J2ME CLDC 
	(Java 2 Micro Edition, Connected Limited Device Configuration).</p>
    
    <p>To run the compiler from the command line or a script, <link anchor="classpath">set the classpath</link> and 
    run the XSLTC class with the appropriate flags and arguments (described below).</p>
    <anchor name="comp-synopsis"/>
<s3 title="Synopsis">
<p>
<code>java org.apache.xalan.xsltc.cmdline.Compile</code><br/>
<code>&nbsp;&nbsp;&nbsp;&nbsp;[-o &lt;output&gt;] [-d &lt;directory&gt;] [-j &lt;jarfile&gt;]</code><br/>
<code>&nbsp;&nbsp;&nbsp;&nbsp;[-p &lt;package name&gt;] [-u] &lt;stylesheet&gt;...</code></p> 

</s3><anchor name="comp-args"/>
<s3 title="Flags and arguments">
	<p>The following flags and arguments are supported:</p>

<source>-o &lt;output&gt;
   Specifies the name of the generated translet class.
   If you omit this argument, the translet class is
   named &lt;stylesheet&gt;. Translets are written as 
   .class files.

-d &lt;directory&gt;
   Specifies the destination directory. If you omit
   this argument, the translet class files are placed
   in the current working directory.

-j &lt;jarfile&gt;
   Outputs the generated translet class files into a 
   jar file named &lt;jarfile&gt;.jar. When this option is 
   used, only the jar file is output.

-p &lt;package name&gt;
   Specifies a package name for the generated translet
   classes.		

-u  &lt;stylesheet&gt;
  Specifies the stylesheet with a URI such as 
  'http://myserver/stylesheet1.xsl'.

   &lt;stylesheet&gt;
   (No flag) The pathname of the stylesheet file.</source>

</s3><anchor name="comp-examples"/>
<s3 title="Examples">
	<p>The following examples assume that you have already set the classpath to include the translet and the required JAR
    files (see <link anchor="classpath">setting the system classpath</link>).</p>

	<p><em>Example 1:</em>  Creating a translet from the hamlet.xsl stylesheet.</p>
	<p><code>java org.apache.xalan.xsltc.cmdline.Compile</code><br/>
    <code>&nbsp;&nbsp;&nbsp;&nbsp; hamlet.xsl</code></p>    
    <p>Example 1 produces a set of class files such as hamlet.class, hamlet$0.class, hamlet$1.class.</p>	

	<p><em>Example 2:</em>  Outputting to a JAR file.</p>
    <p><code>java org.apache.xalan.xsltc.cmdline.Compile</code><br/>
    <code>&nbsp;&nbsp;&nbsp;&nbsp; -j hamlet.jar hamlet.xsl</code></p>
    <p>Example 2 produces hamlet.jar, which contains the translet class files.</p>	

	<p><em>Example 3:</em> Specifying the translet class name. </p> 
	<p><code>java org.apache.xalan.xsltc.cmdline.Compile</code><br/>
    <code>&nbsp;&nbsp;&nbsp;&nbsp; -o newhamlet hamlet.xsl</code></p>
    <p>Example 3 producs a set of class files such as newhamlet.class, newhamlet$0.class, etc., rather than hamlet.class,
    hamles$0.class, etc.</p>


	<p><em>Example 4:</em> Compiling multiple stylesheets.</p>
	<p><code>java org.apache.xalan.xsltc.cmdline.Compile</code><br/>
    <code>&nbsp;&nbsp;&nbsp;&nbsp; hamlet1.xsl hamlet2.xsl hamlet3.xsl</code></p>
    <p>Example 4 produces three translets and set of class files derived from the three stylesheets.</p>

	<p><em>Example 5:</em> Package Specification.</p>
	<p><code>java org.apache.xalan.xsltc.cmdline.Compile</code><br/>
    <code>&nbsp;&nbsp;&nbsp;&nbsp; -p com.mycompany.translets hamlet.xsl</code></p>
    <p>Example 5 produces a set of class files such as com/mycompany/translets/hamlet.class,
	com/mycompany/translets/hamlet$0.class', etc.</p>
</s3>
</s2><anchor name="run"/>
<s2 title="Running translets from the command line">
    <ul>
      <li><link anchor="run-synopsis">Synopsis</link></li>
      <li><link anchor="run-args">Flags and arguments</link></li>
      <li><link anchor="run-examples">Examples</link></li>
    </ul>

    <p>The XSLT runtime processor is a Java-based tool for 
	transforming XML document files using a translet (compiled 
	stylesheet). </p>

	<p>The XSLT processor can be run on any platform including UNIX,
	Windows, NT, Mac that supports Java, including a Palm Pilot
	with J2ME CLDC (Java 2 Micro Edition, Connected Limited Device
	Configuration).</p>
    
    <p>To run a  translet from the command line or a script, <link anchor="classpath">set the classpath</link> (be sure to include
     the translet) and run the translet with the appropriate flags and arguments (described below).</p>
<anchor name="run-synopsis"/>
<s3 title="Synopsis">
<p><code>java org.apache.xalan.xsltc.cmdline.Transform</code><br/>
<code>&nbsp;&nbsp;&nbsp;&nbsp; {-u &lt;document_url&gt; | &lt;document&gt;} &lt;class&gt;</code><br/>
<code>&nbsp;&nbsp;&nbsp;&nbsp; [&lt;name1&gt;=&lt;value1&gt; ...]</code></p>

</s3><anchor name="run-args"/>
<s3 title="Flags and arguments">

	<p>The following flags and arguments are supported:</p>

<source>-u
   Specifies the XML input &lt;document&gt; with a URI,
   such as 'http://myserver/hamlet.xml'.		

Arguments wirhout flags:

   &lt;document&gt;     		
   Filename of the XML input document. 
   
   &lt;document_url&gt;     	
   URI of the XML input document (see the -u flag above). 

   &lt;class&gt;
   The translet that performs the transformation. The translet
   may take a set of stylesheet parameters specified as
   name-value pairs. The format for a name-value pair is
   &lt;name&gt;=&lt;value&gt;.</source>
</s3><anchor name="run-examples"/>
<s3 title="Examples">

	<p>The following examples assume that you have already set the classpath to include the translet and the required JAR
    files (see <link anchor="classpath">setting the system classpath</link>).</p>
    <p>A possible variation: You have set the classpath to include the required JAR files, but when you run the translet,
    you use the java -cp flag to add the current working directory (containing the translet class files you have just generated)
    to the classpath.</p>
    <p><ref>Windows:</ref><code> java -cp .;%CLASSPATH% ...</code><br/>
       <ref>UNIX:&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;</ref><code> java -cp .:$CLASSPATH ...</code></p>
    
    <p><em>Example 1:</em> Processing an XML document.</p>

	<p><code>java org.apache.xalan.xsltc.cmdline.Transform</code><br/>
       <code>&nbsp;&nbsp;&nbsp;&nbsp;  hamlet.xml hamlet</code></p> 

	<p>Example 1 uses the specified translet (hamlet) to transform the specified XML input document (hamlet.xml). 
    The XML input document is in the current working directory. The translet was created by using
    org.apache.xalan.xslt.cmdline.Compile to compile an XSL stylesheet (hamlet.xsl). </p>

	<p><em>Example 2:</em> Passing stylesheet parameters to the translet.</p>

	<p><code>java org.apache.xalan.xsltc.cmdline.Transform</code><br/>
       <code>&nbsp;&nbsp;&nbsp;&nbsp; hamlet.xml hamlet</code><br/>
       <code>&nbsp;&nbsp;&nbsp;&nbsp; speaker=HAMLET 'scene=SCENE IV'</code></p>

	<p>Example 2 passes "HAMLET" to the stylesheet for the stylesheet parameter named speaker, and "SCENE IV" for the
    stylesheet parameter named scene. The second name-value pair was placed in single quotes to 
    specify a value containing a space.</p>
    
    <p><em>Example 3:</em> Processing an XML input document specified with a URI.</p>

	<p><code>java org.apache.xalan.xsltc.cmdline.Transform</code><br/>
       <code>&nbsp;&nbsp;&nbsp;&nbsp;  -u http://zarya.east/test.xml hamlet</code></p>

	<p>Example 3 applies the translet (hamlet) to the XML input document (http://zarya.east/test.xml hamlet). Inclusion of
    the flag (-u) is optional.</p>
</s3>
</s2><anchor name="api"/>
<s2 title="Calling XSLTC with the TrAX/JAXP API">
<p>XSLTC translets are integrated with the TrAX/JAXP 1.1 API. See <jump href="xsltc/xsltc_trax.html">The Translet API &amp; TrAX</jump>. Accordingly, it is now possible to set a system property and use a TransformerFactory to generate a Transformer that performs a transformation by compiling and running a translet.</p>


<p>When you use the JAXP 1.1 API to run &xslt4j;, the <code>javax.xml.transform.TransformerFactory</code> system property is set to <code>org.apache.xalan.processor.TransformerFactoryImpl</code>. As it currently stands, this Xalan implementation of TransformerFactory always uses the Xalan Transformer to perform transformations. To use translets to perform transformations, set this system property to <code>org.apache.xalan.xsltc.trax.TransformerFactoryImpl</code>. For information on setting this and related system properties designating XML parsere and XSL transformer, see <link idref="usagepatterns" anchor="plug">Plugging in a Transformer and XML parser</link>.</p>
<p>To Use the JAXP 1.1 API to perform transformations with translets do the following:</p>
<ol>
  <li>Set the <code>javax.xml.transform.TransformerFactory</code> system property as indicated above.<br/><br/></li>
  <li>Instantiate a TransformerFactory.<br/><br/></li>
  <li>Assuming you want to perform a series of transformations with the same translet, use the TransformerFactory and a
   StreamSource XSL stylesheet to generate a Templates object (the translet). If you are performing a single
   transformation, use the TransformerFactory and the StreamSource object to instantiate a Transformer.<br/><br/></li>
  <li>Perform the transformation, using a StreamSource object for the XML input and a StreamResult object to hold the
   transformation output.</li>
</ol>
<s3 title="Examples">
<p><em>Example 1:</em> Using a translet/Templates object for multiple transformations</p>
<source>import java.util.Properties;
import javax.xml.transform.Transformer;
import java.io.FileOutputStream;
import javax.xml.transform.TransformerFactory;
import javax.xml.transform.Templates;
import javax.xml.transform.stream.StreamSource;
import javax.xml.transform.stream.StreamResult;
...
// Set the TransformerFactory system property.
// Note: For more flexibility, load properties from a properties file.
String key = "javax.xml.transform.TransformerFactory";
String value = "org.apache.xalan.xsltc.trax.TransformerFactoryImpl";
Properties props = System.getProperties();
props.put(key, value);
System.setProperties(props);
...
String xslInURI;
// Instantiate the TransformerFactory, and use it along with a SteamSource
// XSL stylesheet to create a translet as a Templates object.
TransformerFactory tFactory = TransformerFactory.newInstance();
Templates translet = tFactory.newTemplates(new StreamSource(xslInURI));
...
String xmlInURI;
String htmlOutURI;
...
// For each transformation, instantiate a new Transformer, and perform
// the transformation from a StreamSource to a StreamResult;
Transformer transformer = translet.newTransformer();
transformer.transform(new StreamSource(xmlInURI),
                      new StreamResult(new FileOutputStream(htmlOutURI)));
...</source>
<p>For a working sample that illustrates this usage pattern, see <link idref="samples" anchor="xsltc1">JAXPTransletOneTransformation</link>.</p>
<p><em>Example 2:</em> Compiling a translet/Templates object for a single transformation</p>
<source>import java.util.Properties;
import javax.xml.transform.TransformerFactory;
import java.io.FileOutputStream;
import javax.xml.transform.Transformer;
import javax.xml.transform.stream.StreamSource;
import javax.xml.transform.stream.StreamResult;
...
// Set the TransformerFactory system property.
// Note: For more flexibility, load properties from a properties file.
String key = "javax.xml.transform.TransformerFactory";
String value = "org.apache.xalan.xsltc.trax.TransformerFactoryImpl";
Properties props = System.getProperties();
props.put(key, value);
System.setProperties(props);
...
String xslInURI;
String xmlInURI;
String htmlOutURI;
// Instantiate the TransformerFactory, and use it along with a SteamSource
// XSL stylesheet to create a Transformer.
TransformerFactory tFactory = TransformerFactory.newInstance();
Transformer transformer = tFactory.newTransformer(new StreamSource(xslInURI));
// Perform the transformation from a StreamSource to a StreamResult;
transformer.transform(new StreamSource(xmlInURI),
                      new StreamResult(new FileOutputStream(htmlOutURI)));</source>
<p>For a working sample that illustrates this usage pattern, see <link idref="samples" anchor="xsltc2">JAXPTransletMultipleTransformations</link>.</p>
</s3>
</s2><anchor name="native_api"/>
<s2 title="Calling XSLTC with the native API">
<p>This section demonstrates how to use the native XSLTC API in a standalone Java application.</p> 
<p>Processing an XML document with a translet involves three main steps:</p>
<ol> 
  <li><link anchor="native_compile">Compile the stylesheet to a translet</link>.</li>
  <li><link anchor="native_parse">Parse the input XML document</link>.</li> 
  <li><link anchor="native_transform">Use the translet to transform the XML document</link>.</li>
</ol><anchor name="native_overview"/>
<s3 title="Code overview">
<p>XsltApp.java illustrates the basic structure for coding a transformation with the native XSLTC API. In the following listing, the method for performing each of the three steps is an empty shell. The methods are filled in the listings in subsequent sections.</p>
<source>import org.apache.xalan.xsltc.Translet;
import org.apache.xalan.xsltc.dom.DOMImpl;

public class XsltApp {
  public static void main(String[] args) {
    XsltApp proc = new XsltApp();
    proc.run(args);
  }

  public void run(String[] args) {
    if (args.length != 2) {
      System.err.println("Usage:\n\tprocessor &lt;xmlfile&gt; &lt;xslfile&gt;" +
            "\n\n\twhere &lt;xmlfile&gt; = xml input filename, and" +
            "\n\t      &lt;xslfile&gt; = stylesheet filename.");
      System.exit(1);
    }
    String xmldocFilename     = args[0];
    String stylesheetFilename = args[1];

    // Compile the stylesheet to a translet
    Translet translet = compileStylesheet(stylesheetFilename);

    // Parse the input XML document
    DOMImpl dom = getDOM(xmldocFilename);

    // Transform the XML document against the translet
    doTransform(translet, dom);
    System.exit(0);
  }
  
  // compile the stylesheet [Empty shell: see below]
  private Translet compileStylesheet(String stylesheetName) { return null; }

  // parse the input XML document [Empty shell: see below]
  private DOMImpl getDOM(String xmldocname) { return null; }

  // transform the XML document [Empty shell: see below]
  private void doTransform(Translet translet, DOMImpl dom) { }
}</source>

<p>XsltApp takes two command line arguments: the input XML document filename, and the
XSL stylesheet filename. The public run() method processes the commandline args,
and then carries out the three steps.</p> 
<p>The first step is accomplished by calling the compileStylesheet() method. This method
takes the stylesheet filename as input (String), and returns an instance
of the translet, as type org.apache.xalan.xsltc.Translet.</p>

<p>The input XML document now needs to be parsed. This is accomplished by the getDOM() method. This method takes the XML document's filename (String)
and returns the Document Object Model for the document, as an object of
type org.apache.xalan.xsltc.dom.DOMImpl. </p>

<p>Finally, the transformation prescribed by the stylesheet is carried out by
calling the doTransform() method. This method takes the translet (compiled
stylesheet) and the dom (Document Object Model for the XML document) as
input parameters. In this example, the results of the transformation are
output to standard output, so this method returns nothing. </p>

<p>If all three steps are carried out successfully, the application exits with
a successful (zero) value.</p>

<p>The following sections examine each of the three steps in detail.</p>
</s3><anchor name="native_compile"/>
<s3 title="1. Compiling the Stylesheet to a Translet">
<p>The 'compileStylesheet' method:</p>

<source>import java.io.File;
import java.net.MalformedURLException; 
import org.apache.xalan.xsltc.compiler.XSLTC;
...
  private Translet compileStylesheet(String stylesheetName) {
    Translet retval = null;
    String transletName = stylesheetName.substring(0,
                              stylesheetName.indexOf('.'));
    try {
      XSLTC xsltc = new XSLTC();
      xsltc.init();
      File stylesheet = new File(stylesheetName);
      xsltc.compile(stylesheet.toURL());
      Class clazz = Class.forName(transletName);
      retval = (Translet)clazz.newInstance();
    } 
    catch (MalformedURLException e) {
      System.err.println("Could not create URL to stylesheet file: " +
                          stylesheetName + ".\n" + e.getMessage());
      System.exit(1);
    } 
    catch (ClassNotFoundException e) {
      System.err.println("Could not find class file: " +
                          transletName + ".class .\n" + e.getMessage());
      System.exit(1);
    } 
    catch (InstantiationException e) {
      System.err.println("Could not instantiate class file: " +
                          transletName + ".class .\n" + e.getMessage());
      System.exit(1);
    } 
    catch (IllegalAccessException e) {
      System.err.println("Could not instantiate class file: " +
            transletName + ".class, illegal access.\n" + e.getMessage());
      System.exit(1);
    }
    return retval;
  }</source>

<p>This method reads in the stylesheet file, compiles it to Java bytecodes 
(the translet), and then writes the bytecodes to the filesystem, as a 
series of .class files. Their base name is derived from the name of the 
stylesheet. </p>

<p>The XSLT compiler object (org.apache.xalan.xsltc.compiler.XSLTC), is created,
initialized and then its compile() method is called passing in a URL
to the stylesheet itself. Once the .class files have been written,
the translet is instantiated using Java reflection to create the Class
and then a new instance of the Class as 'retval' of type 
org.apache.xalan.xsltc.Translet. </p>

<p>Notice all of the various exceptions that could be thrown in the process
have been handled with explicit warning messages and a System.exit with a non-zero return value. 
In your applications, you may want to handle these exceptions differently.</p>

</s3><anchor name="native_parse"/>
<s3 title="2. Parsing the XML Document">

<p>Parsing the input XML document is handled in the getDOM() method:</p>

<source>import java.io.IOException;
import javax.xml.parsers.SAXParserFactory;
import javax.xml.parsers.SAXParser;
import javax.xml.parsers.ParserConfigurationException;
import org.apache.xalan.xsltc.compiler.Constants;
import org.apache.xalan.xsltc.dom.DTDMonitor;
import org.xml.sax.XMLReader;
import org.xml.sax.SAXException;
...
  private DTDMonitor _dtdMonitor = null;

  private DOMImpl getDOM(String xmldocname) {
    final SAXParserFactory factory = SAXParserFactory.newInstance();
    try {
      factory.setFeature(Constants.NAMESPACE_FEATURE, true);
    } 
    catch (Exception e) {
      factory.setNamespaceAware(true);
    }
    final DOMImpl dom = new DOMImpl();
    dom.setDocumentURI(xmldocname);
    XMLReader reader = null;
    SAXParser parser = null;
    _dtdMonitor = new DTDMonitor();
    try {
      parser = factory.newSAXParser();
      reader = parser.getXMLReader();
      reader.setContentHandler(dom.getBuilder());
      _dtdMonitor.handleDTD(reader);
      reader.parse(xmldocname);
    } 
    catch (ParserConfigurationException e) {
      System.err.println("SAX Parser is not configured properly.\n"+
                          e.getMessage());
      System.exit(1);
    } 
    catch (SAXException e ) {
      System.err.println("SAX Parser could not be created.\n"+
                          e.getMessage());
      System.exit(1);
    } 
    catch (IOException e ) {
      System.err.println("XML Reader could not read xml document '"+
                          xmldocname + "'," + e.getMessage());
      System.exit(1);
    }
    return dom;
  }</source>

<p>The method parses the input XML document and creates a Document
Object Model to return to the run() method for later use. To parse the 
document we use a javax.xml.parsers.SAXParser, from the JAXP.  The JAXP
model uses a factory method; accordingly we first create the factory,
which is of type javax.xml.parsers.SAXParserFactory. After configuring 
the factory to handle namespaces, the procedure gets an org.xml.sax.XMLReader
from the SAXParser. The reader is registered
with the class DTDMonitor, and then the reader is instructed to parse
the XML document. The DOMImpl object is returned to the main() method.</p> 

<note>Before the document is parsed, the DOMImpl is configured with the
XML document's URI with a call to the setDocumentURI() method. This
is necessary to define the origin of the document from which the DOM tree
is built. This information is needed for xsl:import, xsl:include, and
the document() function.</note>
</s3><anchor name="native_transform"/>
<s3 title="3. Doing the Transformation">

<p>Now everything is set to carry out the XSL transformation. The doTransform()
method takes a reference to the Translet object generated 
from the stylesheet, and the DOMImpl object created from the XML document.</p>

<source>import java.io.IOException;
import org.apache.xalan.xsltc.runtime.DefaultSAXOutputHandler;
import org.apache.xalan.xsltc.runtime.TextOutput;
import org.apache.xalan.xsltc.runtime.AbstractTranslet;
import org.apache.xalan.xsltc.TransletException;
...
  private void doTransform(Translet translet, DOMImpl dom) {
    DefaultSAXOutputHandler outputhandlr = null;
    TextOutput textoutput = null;
    try {
      outputhandlr= new DefaultSAXOutputHandler(System.out, "utf-8");
      textoutput = new TextOutput(outputhandlr, "utf-8");
    } 
    catch (IOException e) {
      System.err.println("Could not create SAX Output Handler."+
                          e.getMessage());
      System.exit(1);
    }
  
    // for XSL keys
    AbstractTranslet absTranslet = (AbstractTranslet)translet;
    absTranslet.setIndexSize(dom.getSize());
    _dtdMonitor.buildIdIndex(dom, 0, absTranslet);

    try {
      absTranslet.transform(dom, textoutput);
    } 
    catch (TransletException e) {
      System.err.println("Could not transform XML document."+
                          e.getMessage());
      System.exit(1);
    }
  }</source>

<p>The Translet's transform() method takes two arguments: the DOMImpl
reference created in the getDOM() method, and an xsltc.runtime.TextOutput
object. TextOutput is a ContentHandler wrapper class that implements the
xsltc.TransletOutputHandler interface. In this example, the content
handler (DefaultSAXOutputHandler) is wrapped.</p>     

<p>Translet is an interface. AbstractTranslet is a class that implements that
interface. Before the transform() method is called, setIndexSize(int)
is called to pass in the maximum DOM size to the translet and the DTDMonitor
is called to build the node index that the Key (xsl:key implementation)
class uses. This is a general case, if you are not using keys, then you
do not need to set the index size, consequently you would not need to
work with the AbstractTranslet either. In that case, you can  use the
Translet directly by calling translet.transform(dom, textoutput). </p>
</s3><anchor name="native_conclusion"/>
<s3 title="Conclusion">
<p>The native XSLT compiler API provides a way to compile an XSL stylesheet
into a translet. The translet can then be used to transform the DOMImpl
of an input XML document.   This example demonstrated how to compile a
stylesheet into a translet, parse an input XML document, and then transform
the XML document using the translet.</p>
</s3></s2><anchor name="constraints"/>
<s2 title="XSLTC usage constraints">
<p>See <link idref="xsltc_constraints" anchor="xsltcconf">Conformance issues</link> and <link idref="xsltc_constraints" 
anchor="xsltcknownproblems">Known problems</link>.</p>
</s2>
</s1>