xdocs/sources/xalan/faq.xml - xalan-java - Git at Google

 <?xml version="1.0" standalone="no"?>
 <!DOCTYPE faqs SYSTEM "../../style/dtd/faqs.dtd">

 <faqs title="Frequently asked questions">

   <faq title="Where do I go to learn about XSLT">
     <q>Where do I go to learn about XSLT?</q>
     <a><p>The definitive sources are the W3C XSLT and XPath recommendations: <resource-ref idref="xslt"/> and
     <resource-ref idref="xpath"/>.</p>
     <p>For a brief listing of tutorials, discussion forums, and other materials, see <link idref="overview"
      anchor="uptospeed">Getting up to speed with XSLT</link>.</p></a>
   </faq>

   <faq title="Which version of Xerces should I be using?">
     <q>Which version of Xerces should I be using?</q>
     <a><p>&xslt4j-current; has been tested with &xml4j-used;. See <link idref="readme" anchor="status">Status</link>.</p></a>
   </faq>

   <faq title="Compatibility with &xslt4j; version 1">
    <q>How do I run applications that use the &xslt4j; version 1 API with &xslt4j2;</q>
    <a><p>The Xalan-Java 1 compatibility API has been deprecated and now purged, so you must use the &xslt4j2; API. We strongly encourage you to
    use the JAVAX 1.1/TrAX API. For more information ,see the next FAQ.</p></a>
   </faq>

   <faq title="TrAX and JAXP">
     <q>What are TrAX and JAXP, and are they related?</q>
     <a><p>TrAX is the Transformation API for XML. In November 2000, TrAX was revised and incorporated into JAXP, the JAVA API for XML
     Processing. JAXP (including TrAX) provides users a standard, vendor-neutral API for working with (and transforming) XML documents.
     You can use this API to build applications that are not bound to the particular implementation details of a given XML parser or XSL
     transformer.</p>
     <p>&xslt4j; includes the JAXP packages, implements the TrAX portion of that API (javax.xml.transform....), and includes &xml4j-jar; from
     &xml4j;, which implements the parser portion of the API (javax.xml.parser....).</p>
 <p>For more information, see <link idref="trax">TRaX (Transformation API for XML)</link> and <resource-ref idref="jaxp11"/>.</p></a>
   </faq>
   <faq title="Chaining transformations">
     <q>How do you chain together a series of transformations?"</q>

     <a><p>&xslt4j; supports two strategies for chaining together a series of transformations such that the output of each
     transformation provides input for the next transformation.</p>
     <ul>
       <li>For each transformation in the series, you can set one SAX ContentHandler to process the input, and another ContenHandler to process
        the output.<br/><br/></li>
       <li>You can also set up a series of parent-child relationships between an XMLReader and one or more XMLFilters.</li>
     </ul>
     <p>For the details and links to examples, see <link idref="usagepatterns" anchor="outasin">Using transformation output as input for
     another transformation</link>.<anchor name="jdk13"/></p></a>
   </faq>

   <faq title="Issues running Xalan on JDK 1.3">
   <q>I'm having a problem building or running &xslt4j; on the JDK 1.3.</q>
   <a><p>The JDK 1.3 automatically places everything in the lib/ext directory in front of everything you place on the classpath. If this directory contains a version of DOM, JAXP, or Xerces that predates the &xslt4j; distribution you are using, you may have problems!</p>
 <p>The IBM JDK 1.3 includes an earlier version of xerces.jar in the lib/ext directory, a version that does not implement the JAXP 1.1 interfaces and therefore does not work with the current Xalan release. Accordingly, you must either purge the xerces.jar that is in that directory or replace it with the &xml4j-jar; that is included with the Xalan distribution.</p>
 <p>The SUN JDK 1.3 includes a pre-1.1 version of the JAXP in crimson.jar. Either purge the crimson.jar in that directory or overwrite it with a newer crimson.jar that includes and implements the JAXP 1.1 interfaces.</p></a>
   </faq>
   <faq title="a &quot;DOM006 Hierarchy request error&quot;">
   <q>Why do I get a "DOM006 Hierarchy request error" when I try to transform into a DOM Document node?</q>
   <a>
   <p>This error occurs when Xalan tries to add a Node to a Document node where it isn't allowed. For example, attempting to add non-whitespace
   text to the DOM Document node produces this error.</p>
    <p>The error can also occur when a Document node is created with the DOMImplementation createDocument() method, which takes a qualified name
     as an argument and creates an element node.  If you then pass the returned Document node to Xalan, you get a "DOM006 Hierarchy request
     error" when Xalan tries to add a second element to the Document node. The solution is to either use the DocumentBuilder newDocument() method
     to create a Document that does not contain an element node, or use a DocumentFragment. It should be noted that the
     DocumentBuilder newDocument() method is "Non-preferred" according to the JAXP 1.1 documentation.</p>
   </a>
   </faq>

   <faq title="Speeding up transformations">

     <q>What can I do to speed up transformations?</q>

     <a><p>In the ongoing development of &xslt4j;, enhancing performance is the primary goal of the &xslt4j; team.
     Here are some preliminary suggestions for you to keep in mind as you set up your applications:</p><ul>
     <li>Use a Templates object (with a different Transformers for each transformation) to perform multiple transformations with the same
     set of stylesheet instructions (see <link idref="usagepatterns" anchor="multithreading">Multithreading</link>).<br/><br/></li>
     <li>Set up your stylesheets to function efficiently.<br/><br/></li>
        <ul>
          <li>Don't use "//" (descendant axes) patterns near the root of a large document.<br/><br/></li>
          <li>Use xsl:key elements and the key() function as an efficient way to retrieve node sets.<br/><br/></li>
          <li>Where possible, use pattern matching rather than xsl:if or xsl:when statements.<br/><br/></li>
          <li>xsl:for-each is fast because it does not require pattern matching.<br/><br/></li>
          <li>Keep in mind that xsl:sort prevents incremental processing.<br/><br/></li>
          <li>When you create variables, &lt;xsl:variable name="fooElem" select="foo"/&gt; is usually faster than
          &gt;xsl:variable name="fooElem"&gt;&lt;xsl:value-of-select="foo"/&gt;&lt;/xsl:variable&gt;.<br/><br/></li>
          <li>Be careful using the last() function.<br/><br/></li>
          <li>The use of index predicates within match patterns can be expensive.<br/><br/></li>
          <li>Decoding and encoding is expensive.<br/><br/></li>
        </ul>
      <li>For the ultimate in server-side scalability, perform transform operations on the client. For examples, see
      <link idref="samples" anchor="appletxmltohtml">appletXMLtoHTML</link> and <link idref="samples"
      anchor="get-todo-list">get-todo-list</link>.</li>
     </ul></a>
   </faq>

   <faq title="NoClassDefFound errors">

     <q>I'm getting a NoClassDefFound error. What has to be on the classpath?</q>

     <a><ol>
     <li>xalan.jar, xml-apis.jar, and &xml4j-jar; -- or the XML parser you are using -- must always be on the classpath.<br/><br/></li>
     <li>To run the samples in the samples subdirectories, xalansamples.jar must be on the classpath. To run the servlet (in
     samples/servlet), xalanservlet.jar must be on the classpath along with the javax.servlet and javax.servlet.http packages. Sun distributes
     the javax.servlet packages in the JSWDK servlet.jar file.<br/><br/></li>
     <li>To run extensions (including the samples in samples/extensions), bsf.jar, and bsfengines.jar must be on the
     classpath. To run extensions implemented in JavaScript, js.jar must also be on the classpath. For information on what
     you need to run extensions implemented in other scripting languages, see <link idref="extensions"
     anchor="supported-lang">Supported languages</link>.<br/><br/></li>
     <li>To run applications that use the &xslt4j; version 1 API, you must put xalanj1compat.jar on the classpath, recompile the application,
     and be sure xalanj1compat.jar is on the classpath at run time (see <link idref="usagepatterns" anchor="compat">Using the &xslt4j; version 1
     API)</link>.</li>
     </ol>
     <p>For more information, see <link idref="getstarted" anchor="classpath">Setting up the system classpath</link>.</p>
     <p><anchor name="environmentcheck"/><em>Using the EnvironmentCheck utility:</em> To help diagnose classpath problems, try running Xalan's environment checking utility, checked in at
     xml-xalan/java/src/org/apache/xalan/xslt/EnvironmentCheck.</p>
     <p>You can run this utility from the command line as follows:</p>
     <p><code>java org.apache.xalan.xslt.EnvironmentCheck [-out outFile]</code></p>
     <p>You can also call this utility from within your application. For example,</p>
     <p><code>boolean environmentOK = (new EnvironmentCheck()).checkEnvironment (yourPrintWriter);</code></p>
     <p>Be sure to run EnvironmentCheck in the environment where you are experiencing the problem. For example, if you get a
     NoClassDefFound error from a command-line application, run EnvironmentCheck on the command line with exactly the same
     classpath. If the error occurs inside your Java application (or in a servlet, etc.), be sure to call the
     EnvironmentCheck checkEnvironment(...) method from within your running application.</p>
     </a>
    </faq>

 	<faq title="Stylesheet validation">
 		<q>How do I validate an XSL stylesheet?</q>
 		<a>
       <p>An XSL stylesheet is an XML document, so it can have a DOCTYPE and be subject to validation, right? </p>
       <p>The XSLT Recommendation includes a <jump href="http://www.w3.org/TR/xslt#dtd">DTD Fragment
       for XSL Stylesheets</jump> with some indications of what you need to do to create a complete DTD for a given
       stylesheet. Keep in mind that stylesheets can include literal result elements and produce output that is not valid
       XML.</p>
       <p>You can use the xsl:stylesheet doctype defined in xsl-html40s.dtd for stylesheets that generate HTML.</p>
 		</a>
 	</faq>

     <faq title="Retrieving nodes in the default namespace">
      <q>XPath isn't retrieving nodes that are in the default namespace I defined. How do I get them?</q>
      <a><p>If you are looking for nodes in a namespace, the XPath expression must include a namespace prefix that you have mapped to the
        namespace with an xmlns declaration. If you have declared a default namespace, it does not have a prefix (see
        <jump href="http://www.w3.org/TR/xpath.html#node-tests">XPath Node Tests</jump>). In order to construct XPath expressions
        to retrieve nodes from this namespace, you must add a namespace declaration that provides a prefix you can include in the XPath
         expressions.</p>
        <p>Suppose, for example, you you want to locate nodes in a default namespace declared as follows:<br/>
        <code>xmlns="http://my-namespace"</code></p>
        <p>Add a nampespace declaration with a prefix:<br/>
        <code>xmlns:foo="http://my-namespace"</code></p>
        <p>Then you can use foo: in your XPath expression.</p>
        <p>Hint: Don't use default namespaces, and the problem doesn't arise.</p></a>
     </faq>

     <faq title="Using the 'signature' file to verify a download">
       <q>How do I use the "signature" file to verify my download?</q>
       <a>
         <p>For each Xalan download file in <resource-ref idref="xslt4j-distdir"/>, there is a corresponding signature file.
         The signature file for xalan-j_2_0_1.tar.gz, for example, is xalan-j_2_0_1.tar.gz.sig.</p>
         <p>The .sig files are PGP signatures of the actual .zip or .tar.gz
         download files.  You can use these files to verify the authenticiy of the download. You do not need the .sig file to
         use the corresponding donwload file.</p>
         <p>To check the authenticity of a Xalan distribution, you need a copy of
         PGP which is available in a number of licenses, including some free
         non-commercial licenses, either from an mit.edu site or on
         the pgp.com site. Once you have a version of PGP installed, you
         should be able to 'verify the signature' of the .sig file, which basically verifies that the corresponding
         .zip or tar.gz file has not been changed since we signed it.</p>
       </a>
     </faq>
     <faq title="Setting output encoding">
     <q>Why is the output character encoding I set in the stylesheet not being used?</q>
     <a>
     <p>If you use a character output stream to instantiate the
     <jump href="apidocs/javax/xml/transform/stream/StreamResult.html">StreamResult</jump> object which holds the
     transformation output, the Writer uses its own encoding, not the encoding you specify
     in the stylesheet.</p>
     <p>If you want to use the stylesheet output encoding, do not use StreamResult(java.io.Writer) to
     instantiate the holder for the output. Alternatively, you can specify the encoding when you create a Writer
     (java.io.OutputStreamWriter). Once the Writer exists, you cannot change its encoding.</p>
     </a>
     </faq>
     <faq title="Servlet unable to find classes for extension functions/elements">
     <q>My servlet cannot find classes that implement extension functions or elements. What can I do?</q>
     <a>
     <p>If you install xalan.jar in the servlet engine's lib directory (e.g., tomcat/lib), as opposed to the servlet's
     lib directory, then the Xalan classes are loaded by a classloader that does not see the classes in the servlet's
     classloader (i.e., the extension classes, if you placed them there). The Xalan classes try to load the extension
     classes using their own classloader, and that attempt fails.</p>
     <p>Workaround: place xalan.jar in the servlet's lib directory and NOT in the servlet engine's lib directory.
     Another workaround is to place the extension classes also in the servlet engine's lib directory, but you
     generally want to avoid cluttering that directory.</p>
     <p>Thanks to Gunnlauger Thor Briem (gthb@dimon.is) for providing this information. </p>
     </a>
   </faq>
   <faq title="Namespace not supported by SAXParser">
   <q>Why am I getting a "Namespace not supported by SAXParser exception?</q>
   <a>
   <p>We have seen this probem arise for two quite different reasons:</p>
   <ul>
   <li>SAX1 interfaces are on your classpath in front of the SAX2 interfaces provided with your XML
   parser.<br/><br/>
   or<br/><br/></li>
   <li>The parser you are using to process a stylesheet Source and generate a Transformer does not have the
   namespaceAware property set to true.</li>
   </ul>
   <p><em>SAX1 on the classpath</em></p>
   <p>SAX1 should not be on your classpath. The SAX1 interfaces and implementations of the SAX1 SAXPparser
   are not namespace aware.</p>
   <p>To help diagnose your classpath, you can use the <link anchor="environmentcheck">EnvironmentCheck
   utility</link>. If you are running under JDK 1.3, see <link anchor="jdk13">Issues running Xalan on JDK
   1.3</link>. If you are running a servlet, make sure the servlet engine is not placing SAX1 on the
   classpath.</p>
   <p><em>Setting the parser to be namespace aware</em></p>
   <p>When you create a Transformer, you must use a namespace-aware parser to parse the stylesheet.</p>
   <p>If you use a TransformerFactory to process a stylesheet Source and generate a Transformer, the
   TransformerFactory instructs the  SAXParserFactory to set the parser's namespaceAware property to true.
   But if you call the parser directly, you may need to set the namespaceAware property yourself. For
   example:</p>
 <source>javax.xml.parsers.SAXParserFactory spFactory =
   javax.xml.parsers.SAXParserFactory.newInstance();
 spFactory.setNamespaceAware(true);</source>
 <note>For more information about setting the namespaceAware property, and SAX2 vs. JAXP default settings, see <jump href="http://xml.apache.org/~edwingo/jaxp-faq.html#nsDefaults">JAXP FAQ: Warning about namespace processing defaults</jump>.</note>
 </a>
 </faq>
 <faq title="Getting line and column numbers for errors in XML input documents and XSL stylesheets">
 <q>How do I get line numbers for errors in the XML or XSL input when I am performing a transformation?</q>
 <a>
 <p>Use or mimic the command-line processor (<jump href="apidocs/org/apache/xalan/xslt/Process.html">org.apache.xalan.xslt.Process</jump>).</p>
 <p>A <jump href="apidocs/javax/xml/transform/TransformerException.html">TransformerException</jump> generally wraps another exception, often a SAXParseException. The command-line processor uses the static <jump href="apidocs/org/apache/xml/utils/DefaultErrorHandler.html">org.apache.xml.utils.DefaultErrorHandler</jump> printLocation() method to chase down the exception cause and get a <jump href="apidocs/javax/xml/transform/SourceLocator.html">SourceLocator</jump> that can usually report line and column number.</p>
 <p>Suppose you wanted to modify the ValidateXMLInput sample in the samples/Validate subdirectory to include line and column numbers . All you
 need to do is call DefaultErrorHandler.printLocation() in the the Handler internal class error() and warning() methods. For example, replace</p>
 <source>public void error (SAXParseException spe)
   throws SAXException
 {
   System.out.println("SAXParseException error: " + spe.getMessage());
 }</source>
 <p>with</p>
 <source>public void error (SAXParseException spe)
   throws SAXException
 {
   PrintWriter pw = new PrintWriter(System.out, true);
   org.apache.xml.utils.DefaultErrorHandler.printLocation(pw, spe);
   pw.println("SAXParseException error: " + spe.getMessage());
 }</source>
 <p>You can also replicate code from the printLocation() method to obtain a SourceLocator, and then use the SourceLocator getLineNumber() and getColumnNumber() methods. The getRootSourceLocator() method below returns a SourceLocator.</p>
 <source>
 import javax.xml.transform.SourceLocator;
 import javax.xml.transform.TransformerException;
 import org.xml.sax.SAXException;
 import org.xml.sax.SAXParseException;
 import org.apache.xml.utils.SAXSourceLocator;
 import org.apache.xml.utils.WrappedRuntimeException;
 ....
 public static SourceLocator getRootSourceLocator(Throwable exception)
 {
   SourceLocator locator = null;
   Throwable cause = exception;

   // Try to find the locator closest to the cause.
   do
   {
     if(cause instanceof SAXParseException)
     {
       locator = new SAXSourceLocator((SAXParseException)cause);
     }
     else if (cause instanceof TransformerException)
     {
       SourceLocator causeLocator =
                     ((TransformerException)cause).getLocator();
       if(null != causeLocator)
         locator = causeLocator;
     }
     if(cause instanceof TransformerException)
       cause = ((TransformerException)cause).getCause();
     else if(cause instanceof WrappedRuntimeException)
       cause = ((WrappedRuntimeException)cause).getException();
     else if(cause instanceof SAXException)
       cause = ((SAXException)cause).getException();
     else
       cause = null;
   }
   while(null != cause);

   return locator;
 }</source>

 <note><em>Xalan exception handling:</em>  The exception architecture in Xalan and with transforms in general is tricky because of multiple layers of exception handling, involving movement back and forth between SAX and Transformer exceptions and across pipes. Xalan often uses a WrappedRuntimeException to throw over many layers of checked exceptions, in order not to have every possible checked exception be declared for every function in the stack, which means it has to catch this exception at the upper levels and unwrap the exception to pass it on as a TransformerException.
 <br/><br/>
 A JAXP 1.1 TransformerException often wraps another exception. Two of the TransformerException structures that are frequently used to construct contained exceptions in JAXP 1.1 do not set the locator.  The locator is not set because we don't know the type of exception that the Throwable argument represents.  The solution is to chase up the contained exceptions to find the root cause, which will usually have a location set for you.  This can be somewhat tricky, as not all the exceptions may be TransformerExceptions.  A good sample is in the DefaultHandler static printLocation() method, which the Xalan command-line processor uses to report errors. You can also roll your own functions along the lines of the getRootSourceLocator() example above.</note>
 </a>

 </faq>
 </faqs>
	<?xml version="1.0" standalone="no"?>
	<!DOCTYPE faqs SYSTEM "../../style/dtd/faqs.dtd">

	<faqs title="Frequently asked questions">

	<faq title="Where do I go to learn about XSLT">
	<q>Where do I go to learn about XSLT?</q>
	<a><p>The definitive sources are the W3C XSLT and XPath recommendations: <resource-ref idref="xslt"/> and
	<resource-ref idref="xpath"/>.</p>
	<p>For a brief listing of tutorials, discussion forums, and other materials, see <link idref="overview"
	anchor="uptospeed">Getting up to speed with XSLT</link>.</p></a>
	</faq>

	<faq title="Which version of Xerces should I be using?">
	<q>Which version of Xerces should I be using?</q>
	<a><p>&xslt4j-current; has been tested with &xml4j-used;. See <link idref="readme" anchor="status">Status</link>.</p></a>
	</faq>

	<faq title="Compatibility with &xslt4j; version 1">
	<q>How do I run applications that use the &xslt4j; version 1 API with &xslt4j2;</q>
	<a><p>The Xalan-Java 1 compatibility API has been deprecated and now purged, so you must use the &xslt4j2; API. We strongly encourage you to
	use the JAVAX 1.1/TrAX API. For more information ,see the next FAQ.</p></a>
	</faq>

	<faq title="TrAX and JAXP">
	<q>What are TrAX and JAXP, and are they related?</q>
	<a><p>TrAX is the Transformation API for XML. In November 2000, TrAX was revised and incorporated into JAXP, the JAVA API for XML
	Processing. JAXP (including TrAX) provides users a standard, vendor-neutral API for working with (and transforming) XML documents.
	You can use this API to build applications that are not bound to the particular implementation details of a given XML parser or XSL
	transformer.</p>
	<p>&xslt4j; includes the JAXP packages, implements the TrAX portion of that API (javax.xml.transform....), and includes &xml4j-jar; from
	&xml4j;, which implements the parser portion of the API (javax.xml.parser....).</p>
	<p>For more information, see <link idref="trax">TRaX (Transformation API for XML)</link> and <resource-ref idref="jaxp11"/>.</p></a>
	</faq>
	<faq title="Chaining transformations">
	<q>How do you chain together a series of transformations?"</q>

	<a><p>&xslt4j; supports two strategies for chaining together a series of transformations such that the output of each
	transformation provides input for the next transformation.</p>
	<ul>
	<li>For each transformation in the series, you can set one SAX ContentHandler to process the input, and another ContenHandler to process
	the output.<br/><br/></li>
	<li>You can also set up a series of parent-child relationships between an XMLReader and one or more XMLFilters.</li>
	</ul>
	<p>For the details and links to examples, see <link idref="usagepatterns" anchor="outasin">Using transformation output as input for
	another transformation</link>.<anchor name="jdk13"/></p></a>
	</faq>

	<faq title="Issues running Xalan on JDK 1.3">
	<q>I'm having a problem building or running &xslt4j; on the JDK 1.3.</q>
	<a><p>The JDK 1.3 automatically places everything in the lib/ext directory in front of everything you place on the classpath. If this directory contains a version of DOM, JAXP, or Xerces that predates the &xslt4j; distribution you are using, you may have problems!</p>
	<p>The IBM JDK 1.3 includes an earlier version of xerces.jar in the lib/ext directory, a version that does not implement the JAXP 1.1 interfaces and therefore does not work with the current Xalan release. Accordingly, you must either purge the xerces.jar that is in that directory or replace it with the &xml4j-jar; that is included with the Xalan distribution.</p>
	<p>The SUN JDK 1.3 includes a pre-1.1 version of the JAXP in crimson.jar. Either purge the crimson.jar in that directory or overwrite it with a newer crimson.jar that includes and implements the JAXP 1.1 interfaces.</p></a>
	</faq>
	<faq title="a "DOM006 Hierarchy request error"">
	<q>Why do I get a "DOM006 Hierarchy request error" when I try to transform into a DOM Document node?</q>
	<a>
	<p>This error occurs when Xalan tries to add a Node to a Document node where it isn't allowed. For example, attempting to add non-whitespace
	text to the DOM Document node produces this error.</p>
	<p>The error can also occur when a Document node is created with the DOMImplementation createDocument() method, which takes a qualified name
	as an argument and creates an element node. If you then pass the returned Document node to Xalan, you get a "DOM006 Hierarchy request
	error" when Xalan tries to add a second element to the Document node. The solution is to either use the DocumentBuilder newDocument() method
	to create a Document that does not contain an element node, or use a DocumentFragment. It should be noted that the
	DocumentBuilder newDocument() method is "Non-preferred" according to the JAXP 1.1 documentation.</p>
	</a>
	</faq>

	<faq title="Speeding up transformations">

	<q>What can I do to speed up transformations?</q>

	<a><p>In the ongoing development of &xslt4j;, enhancing performance is the primary goal of the &xslt4j; team.
	Here are some preliminary suggestions for you to keep in mind as you set up your applications:</p><ul>
	<li>Use a Templates object (with a different Transformers for each transformation) to perform multiple transformations with the same
	set of stylesheet instructions (see <link idref="usagepatterns" anchor="multithreading">Multithreading</link>).<br/><br/></li>
	<li>Set up your stylesheets to function efficiently.<br/><br/></li>
	<ul>
	<li>Don't use "//" (descendant axes) patterns near the root of a large document.<br/><br/></li>
	<li>Use xsl:key elements and the key() function as an efficient way to retrieve node sets.<br/><br/></li>
	<li>Where possible, use pattern matching rather than xsl:if or xsl:when statements.<br/><br/></li>
	<li>xsl:for-each is fast because it does not require pattern matching.<br/><br/></li>
	<li>Keep in mind that xsl:sort prevents incremental processing.<br/><br/></li>
	<li>When you create variables, <xsl:variable name="fooElem" select="foo"/> is usually faster than
	>xsl:variable name="fooElem"><xsl:value-of-select="foo"/></xsl:variable>.<br/><br/></li>
	<li>Be careful using the last() function.<br/><br/></li>
	<li>The use of index predicates within match patterns can be expensive.<br/><br/></li>
	<li>Decoding and encoding is expensive.<br/><br/></li>
	</ul>
	<li>For the ultimate in server-side scalability, perform transform operations on the client. For examples, see
	<link idref="samples" anchor="appletxmltohtml">appletXMLtoHTML</link> and <link idref="samples"
	anchor="get-todo-list">get-todo-list</link>.</li>
	</ul></a>
	</faq>

	<faq title="NoClassDefFound errors">

	<q>I'm getting a NoClassDefFound error. What has to be on the classpath?</q>

	<a><ol>
	<li>xalan.jar, xml-apis.jar, and &xml4j-jar; -- or the XML parser you are using -- must always be on the classpath.<br/><br/></li>
	<li>To run the samples in the samples subdirectories, xalansamples.jar must be on the classpath. To run the servlet (in
	samples/servlet), xalanservlet.jar must be on the classpath along with the javax.servlet and javax.servlet.http packages. Sun distributes
	the javax.servlet packages in the JSWDK servlet.jar file.<br/><br/></li>
	<li>To run extensions (including the samples in samples/extensions), bsf.jar, and bsfengines.jar must be on the
	classpath. To run extensions implemented in JavaScript, js.jar must also be on the classpath. For information on what
	you need to run extensions implemented in other scripting languages, see <link idref="extensions"
	anchor="supported-lang">Supported languages</link>.<br/><br/></li>
	<li>To run applications that use the &xslt4j; version 1 API, you must put xalanj1compat.jar on the classpath, recompile the application,
	and be sure xalanj1compat.jar is on the classpath at run time (see <link idref="usagepatterns" anchor="compat">Using the &xslt4j; version 1
	API)</link>.</li>
	</ol>
	<p>For more information, see <link idref="getstarted" anchor="classpath">Setting up the system classpath</link>.</p>
	<p><anchor name="environmentcheck"/><em>Using the EnvironmentCheck utility:</em> To help diagnose classpath problems, try running Xalan's environment checking utility, checked in at
	xml-xalan/java/src/org/apache/xalan/xslt/EnvironmentCheck.</p>
	<p>You can run this utility from the command line as follows:</p>
	<p><code>java org.apache.xalan.xslt.EnvironmentCheck [-out outFile]</code></p>
	<p>You can also call this utility from within your application. For example,</p>
	<p><code>boolean environmentOK = (new EnvironmentCheck()).checkEnvironment (yourPrintWriter);</code></p>
	<p>Be sure to run EnvironmentCheck in the environment where you are experiencing the problem. For example, if you get a
	NoClassDefFound error from a command-line application, run EnvironmentCheck on the command line with exactly the same
	classpath. If the error occurs inside your Java application (or in a servlet, etc.), be sure to call the
	EnvironmentCheck checkEnvironment(...) method from within your running application.</p>
	</a>
	</faq>

	<faq title="Stylesheet validation">
	<q>How do I validate an XSL stylesheet?</q>
	<a>
	<p>An XSL stylesheet is an XML document, so it can have a DOCTYPE and be subject to validation, right? </p>
	<p>The XSLT Recommendation includes a <jump href="http://www.w3.org/TR/xslt#dtd">DTD Fragment
	for XSL Stylesheets</jump> with some indications of what you need to do to create a complete DTD for a given
	stylesheet. Keep in mind that stylesheets can include literal result elements and produce output that is not valid
	XML.</p>
	<p>You can use the xsl:stylesheet doctype defined in xsl-html40s.dtd for stylesheets that generate HTML.</p>
	</a>
	</faq>

	<faq title="Retrieving nodes in the default namespace">
	<q>XPath isn't retrieving nodes that are in the default namespace I defined. How do I get them?</q>
	<a><p>If you are looking for nodes in a namespace, the XPath expression must include a namespace prefix that you have mapped to the
	namespace with an xmlns declaration. If you have declared a default namespace, it does not have a prefix (see
	<jump href="http://www.w3.org/TR/xpath.html#node-tests">XPath Node Tests</jump>). In order to construct XPath expressions
	to retrieve nodes from this namespace, you must add a namespace declaration that provides a prefix you can include in the XPath
	expressions.</p>
	<p>Suppose, for example, you you want to locate nodes in a default namespace declared as follows:<br/>
	<code>xmlns="http://my-namespace"</code></p>
	<p>Add a nampespace declaration with a prefix:<br/>
	<code>xmlns:foo="http://my-namespace"</code></p>
	<p>Then you can use foo: in your XPath expression.</p>
	<p>Hint: Don't use default namespaces, and the problem doesn't arise.</p></a>
	</faq>

	<faq title="Using the 'signature' file to verify a download">
	<q>How do I use the "signature" file to verify my download?</q>
	<a>
	<p>For each Xalan download file in <resource-ref idref="xslt4j-distdir"/>, there is a corresponding signature file.
	The signature file for xalan-j_2_0_1.tar.gz, for example, is xalan-j_2_0_1.tar.gz.sig.</p>
	<p>The .sig files are PGP signatures of the actual .zip or .tar.gz
	download files. You can use these files to verify the authenticiy of the download. You do not need the .sig file to
	use the corresponding donwload file.</p>
	<p>To check the authenticity of a Xalan distribution, you need a copy of
	PGP which is available in a number of licenses, including some free
	non-commercial licenses, either from an mit.edu site or on
	the pgp.com site. Once you have a version of PGP installed, you
	should be able to 'verify the signature' of the .sig file, which basically verifies that the corresponding
	.zip or tar.gz file has not been changed since we signed it.</p>
	</a>
	</faq>
	<faq title="Setting output encoding">
	<q>Why is the output character encoding I set in the stylesheet not being used?</q>
	<a>
	<p>If you use a character output stream to instantiate the
	<jump href="apidocs/javax/xml/transform/stream/StreamResult.html">StreamResult</jump> object which holds the
	transformation output, the Writer uses its own encoding, not the encoding you specify
	in the stylesheet.</p>
	<p>If you want to use the stylesheet output encoding, do not use StreamResult(java.io.Writer) to
	instantiate the holder for the output. Alternatively, you can specify the encoding when you create a Writer
	(java.io.OutputStreamWriter). Once the Writer exists, you cannot change its encoding.</p>
	</a>
	</faq>
	<faq title="Servlet unable to find classes for extension functions/elements">
	<q>My servlet cannot find classes that implement extension functions or elements. What can I do?</q>
	<a>
	<p>If you install xalan.jar in the servlet engine's lib directory (e.g., tomcat/lib), as opposed to the servlet's
	lib directory, then the Xalan classes are loaded by a classloader that does not see the classes in the servlet's
	classloader (i.e., the extension classes, if you placed them there). The Xalan classes try to load the extension
	classes using their own classloader, and that attempt fails.</p>
	<p>Workaround: place xalan.jar in the servlet's lib directory and NOT in the servlet engine's lib directory.
	Another workaround is to place the extension classes also in the servlet engine's lib directory, but you
	generally want to avoid cluttering that directory.</p>
	<p>Thanks to Gunnlauger Thor Briem (gthb@dimon.is) for providing this information. </p>
	</a>
	</faq>
	<faq title="Namespace not supported by SAXParser">
	<q>Why am I getting a "Namespace not supported by SAXParser exception?</q>
	<a>
	<p>We have seen this probem arise for two quite different reasons:</p>
	<ul>
	<li>SAX1 interfaces are on your classpath in front of the SAX2 interfaces provided with your XML
	parser.<br/><br/>
	or<br/><br/></li>
	<li>The parser you are using to process a stylesheet Source and generate a Transformer does not have the
	namespaceAware property set to true.</li>
	</ul>
	<p><em>SAX1 on the classpath</em></p>
	<p>SAX1 should not be on your classpath. The SAX1 interfaces and implementations of the SAX1 SAXPparser
	are not namespace aware.</p>
	<p>To help diagnose your classpath, you can use the <link anchor="environmentcheck">EnvironmentCheck
	utility</link>. If you are running under JDK 1.3, see <link anchor="jdk13">Issues running Xalan on JDK
	1.3</link>. If you are running a servlet, make sure the servlet engine is not placing SAX1 on the
	classpath.</p>
	<p><em>Setting the parser to be namespace aware</em></p>
	<p>When you create a Transformer, you must use a namespace-aware parser to parse the stylesheet.</p>
	<p>If you use a TransformerFactory to process a stylesheet Source and generate a Transformer, the
	TransformerFactory instructs the SAXParserFactory to set the parser's namespaceAware property to true.
	But if you call the parser directly, you may need to set the namespaceAware property yourself. For
	example:</p>
	<source>javax.xml.parsers.SAXParserFactory spFactory =
	javax.xml.parsers.SAXParserFactory.newInstance();
	spFactory.setNamespaceAware(true);</source>
	<note>For more information about setting the namespaceAware property, and SAX2 vs. JAXP default settings, see <jump href="http://xml.apache.org/~edwingo/jaxp-faq.html#nsDefaults">JAXP FAQ: Warning about namespace processing defaults</jump>.</note>
	</a>
	</faq>
	<faq title="Getting line and column numbers for errors in XML input documents and XSL stylesheets">
	<q>How do I get line numbers for errors in the XML or XSL input when I am performing a transformation?</q>
	<a>
	<p>Use or mimic the command-line processor (<jump href="apidocs/org/apache/xalan/xslt/Process.html">org.apache.xalan.xslt.Process</jump>).</p>
	<p>A <jump href="apidocs/javax/xml/transform/TransformerException.html">TransformerException</jump> generally wraps another exception, often a SAXParseException. The command-line processor uses the static <jump href="apidocs/org/apache/xml/utils/DefaultErrorHandler.html">org.apache.xml.utils.DefaultErrorHandler</jump> printLocation() method to chase down the exception cause and get a <jump href="apidocs/javax/xml/transform/SourceLocator.html">SourceLocator</jump> that can usually report line and column number.</p>
	<p>Suppose you wanted to modify the ValidateXMLInput sample in the samples/Validate subdirectory to include line and column numbers . All you
	need to do is call DefaultErrorHandler.printLocation() in the the Handler internal class error() and warning() methods. For example, replace</p>
	<source>public void error (SAXParseException spe)
	throws SAXException
	{
	System.out.println("SAXParseException error: " + spe.getMessage());
	}</source>
	<p>with</p>
	<source>public void error (SAXParseException spe)
	throws SAXException
	{
	PrintWriter pw = new PrintWriter(System.out, true);
	org.apache.xml.utils.DefaultErrorHandler.printLocation(pw, spe);
	pw.println("SAXParseException error: " + spe.getMessage());
	}</source>
	<p>You can also replicate code from the printLocation() method to obtain a SourceLocator, and then use the SourceLocator getLineNumber() and getColumnNumber() methods. The getRootSourceLocator() method below returns a SourceLocator.</p>
	<source>
	import javax.xml.transform.SourceLocator;
	import javax.xml.transform.TransformerException;
	import org.xml.sax.SAXException;
	import org.xml.sax.SAXParseException;
	import org.apache.xml.utils.SAXSourceLocator;
	import org.apache.xml.utils.WrappedRuntimeException;
	....
	public static SourceLocator getRootSourceLocator(Throwable exception)
	{
	SourceLocator locator = null;
	Throwable cause = exception;

	// Try to find the locator closest to the cause.
	do
	{
	if(cause instanceof SAXParseException)
	{
	locator = new SAXSourceLocator((SAXParseException)cause);
	}
	else if (cause instanceof TransformerException)
	{
	SourceLocator causeLocator =
	((TransformerException)cause).getLocator();
	if(null != causeLocator)
	locator = causeLocator;
	}
	if(cause instanceof TransformerException)
	cause = ((TransformerException)cause).getCause();
	else if(cause instanceof WrappedRuntimeException)
	cause = ((WrappedRuntimeException)cause).getException();
	else if(cause instanceof SAXException)
	cause = ((SAXException)cause).getException();
	else
	cause = null;
	}
	while(null != cause);

	return locator;
	}</source>

	<note><em>Xalan exception handling:</em> The exception architecture in Xalan and with transforms in general is tricky because of multiple layers of exception handling, involving movement back and forth between SAX and Transformer exceptions and across pipes. Xalan often uses a WrappedRuntimeException to throw over many layers of checked exceptions, in order not to have every possible checked exception be declared for every function in the stack, which means it has to catch this exception at the upper levels and unwrap the exception to pass it on as a TransformerException.
	<br/><br/>
	A JAXP 1.1 TransformerException often wraps another exception. Two of the TransformerException structures that are frequently used to construct contained exceptions in JAXP 1.1 do not set the locator. The locator is not set because we don't know the type of exception that the Throwable argument represents. The solution is to chase up the contained exceptions to find the root cause, which will usually have a location set for you. This can be somewhat tricky, as not all the exceptions may be TransformerExceptions. A good sample is in the DefaultHandler static printLocation() method, which the Xalan command-line processor uses to report errors. You can also roll your own functions along the lines of the getRootSourceLocator() example above.</note>
	</a>

	</faq>
	</faqs>