You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@xalan.apache.org by sh...@apache.org on 2014/05/16 18:11:35 UTC
svn commit: r1595253 [6/18] - in /xalan/java/branches/WebSite: ./ xalan-j/
xalan-j/design/ xalan-j/design/resources/ xalan-j/resources/ xalan-j/xsltc/
xalan-j/xsltc/resources/
Added: xalan/java/branches/WebSite/xalan-j/faq.html
URL: http://svn.apache.org/viewvc/xalan/java/branches/WebSite/xalan-j/faq.html?rev=1595253&view=auto
==============================================================================
--- xalan/java/branches/WebSite/xalan-j/faq.html (added)
+++ xalan/java/branches/WebSite/xalan-j/faq.html Fri May 16 16:11:33 2014
@@ -0,0 +1,1187 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
+<html>
+<head>
+<title>ASF: Frequently asked questions</title>
+<meta http-equiv="content-type" content="text/html; charset=UTF-8" />
+<meta http-equiv="Content-Style-Type" content="text/css" />
+<link rel="stylesheet" type="text/css" href="resources/apache-xalan.css" />
+</head>
+<!--
+ * Licensed to the Apache Software Foundation (ASF) under one
+ * or more contributor license agreements. See the NOTICE file
+ * distributed with this work for additional information
+ * regarding copyright ownership. The ASF licenses this file
+ * to you under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ -->
+<body>
+<div id="title">
+<table class="HdrTitle">
+<tbody>
+<tr>
+<th rowspan="2">
+<a href="../index.html">
+<img alt="Trademark Logo" src="resources/XalanJ-Logo-tm.png" width="190" height="90" />
+</a>
+</th>
+<th text-align="center" width="75%">
+<a href="index.html">Xalan XSL Transformer User's Guide</a>
+</th>
+</tr>
+<tr>
+<td valign="middle">Frequently asked questions</td>
+</tr>
+</tbody>
+</table>
+<table class="HdrButtons" align="center" border="1">
+<tbody>
+<tr>
+<td>
+<a href="http://www.apache.org">Apache Foundation</a>
+</td>
+<td>
+<a href="http://xalan.apache.org">Xalan Project</a>
+</td>
+<td>
+<a href="http://xerces.apache.org">Xerces Project</a>
+</td>
+<td>
+<a href="http://www.w3.org/TR">Web Consortium</a>
+</td>
+<td>
+<a href="http://www.oasis-open.org/standards">Oasis Open</a>
+</td>
+</tr>
+</tbody>
+</table>
+</div>
+<div id="navLeft">
+<ul>
+<li>
+<a href="resources.html">Resources</a>
+<br />
+</li>
+<li>
+<a href="http://xalan.apache.org/index.html">Home</a>
+</li></ul><hr /><ul>
+<li>
+<a href="index.html">Xalan-J 2.7.2</a>
+</li>
+<li>
+<a href="charter.html">Charter</a>
+</li></ul><hr /><ul>
+<li>
+<a href="whatsnew.html">What's New</a>
+</li>
+<li>
+<a href="readme.html">Release Notes</a>
+</li></ul><hr /><ul>
+<li>
+<a href="overview.html">Overview</a>
+</li>
+<li>
+<a href="downloads.html">Download/Build</a>
+</li>
+<li>
+<a href="getstarted.html">Getting Started</a>
+</li>
+<li>
+<a href="xsltc_usage.html">Using XSLTC</a>
+</li></ul><hr /><ul>
+<li>FAQs<br />
+</li></ul><hr /><ul>
+<li>
+<a href="samples.html">Sample Apps</a>
+</li>
+<li>
+<a href="commandline.html">Command Line</a>
+</li></ul><hr /><ul>
+<li>
+<a href="features.html">Features</a>
+</li>
+<li>
+<a href="trax.html">Transform API</a>
+</li>
+<li>
+<a href="xpath_apis.html">XPath API</a>
+</li>
+<li>
+<a href="usagepatterns.html">Usage Patterns</a>
+</li></ul><hr /><ul>
+<li>
+<a href="apidocs/index.html">Xalan-J API</a>
+</li>
+<li>
+<a href="public_apis.html">Public APIs</a>
+</li>
+<li>
+<a href="dtm.html">DTM</a>
+</li></ul><hr /><ul>
+<li>
+<a href="extensions.html">Extensions</a>
+</li>
+<li>
+<a href="extensionslib.html">Extensions Library</a>
+</li>
+<li>
+<a href="extensions_xsltc.html">XSLTC Exts</a>
+</li></ul><hr /><ul>
+<li>
+<a href="design/design2_0_0.html">Xalan 2 Design</a>
+</li>
+<li>
+<a href="xsltc/index.html">XSLTC Design</a>
+</li></ul><hr /><ul>
+<li>
+<a href="builds.html">Building a release</a>
+</li>
+<li>
+<a href="http://xml.apache.org/xalan-j/test/overview.html">Testing</a>
+</li>
+<li>
+<a href="bugreporting.html">Bug Reporting</a>
+</li></ul><hr /><ul>
+<li>
+<a href="contact_us.html">Contact us</a>
+</li>
+</ul>
+</div>
+<div id="content">
+<h2 class="faqSubHead">Questions</h2>
+<h3>General XSLT</h3>
+<ol start="1">
+<li>
+<a href="#faq-1">Where do I go to learn about XSLT</a>
+</li>
+<li>
+<a href="#faq-2">Where can I ask questions about XSLT</a>
+</li>
+<li>
+<a href="#faq-3">TrAX and JAXP</a>
+</li>
+</ol>
+<h3>Versions</h3>
+<ol start="4">
+<li>
+<a href="#faq-4">Determining Xalan-Java Version</a>
+</li>
+<li>
+<a href="#faq-5">Determining the Serializer Version</a>
+</li>
+<li>
+<a href="#faq-6">Which version of Xerces should I be using?</a>
+</li>
+<li>
+<a href="#faq-7">Compatibility with Xalan-Java version 1</a>
+</li>
+<li>
+<a href="#faq-8">Issues running Xalan-Java on JDK 1.3</a>
+</li>
+<li>
+<a href="#faq-9">Issues running Xalan-Java on JDK/JRE 1.4 or higher</a>
+</li>
+<li>
+<a href="#faq-10">Issues running Xalan-Java on Tomcat with JDK 1.4</a>
+</li>
+<li>
+<a href="#faq-11">Issues running Applets with XSLTC in Web Browsers with JAVA Plug-in (JRE 1.4)</a>
+</li>
+<li>
+<a href="#faq-12">Using the 'signature' file to verify a download</a>
+</li>
+</ol>
+<h3>Performance Issues</h3>
+<ol start="13">
+<li>
+<a href="#faq-13">Speeding up transformations</a>
+</li>
+<li>
+<a href="#faq-14">JAXP factory lookup procedure</a>
+</li>
+</ol>
+<h3>Namespace Related</h3>
+<ol start="15">
+<li>
+<a href="#faq-15">Retrieving nodes in the default namespace</a>
+</li>
+<li>
+<a href="#faq-16">Setting the parser to be namespace aware</a>
+</li>
+</ol>
+<h3>Common Errors</h3>
+<ol start="17">
+<li>
+<a href="#faq-17">NoClassDefFound errors</a>
+</li>
+<li>
+<a href="#faq-18">a "DOM006 Hierarchy request error"</a>
+</li>
+<li>
+<a href="#faq-19">Namespace not supported by SAXParser</a>
+</li>
+<li>
+<a href="#faq-20">Missing xsl:version attribute error</a>
+</li>
+<li>
+<a href="#faq-21">StackOverflowError with recursive stylesheet</a>
+</li>
+<li>
+<a href="#faq-22">OutOfMemoryError processing multiple documents</a>
+</li>
+<li>
+<a href="#faq-23">File Not Found error</a>
+</li>
+<li>
+<a href="#faq-24">No more DTM IDs are available</a>
+</li>
+<li>
+<a href="#faq-25">IllegalAccessError or could not load output_xml.properties on JDK 1.4</a>
+</li>
+</ol>
+<h3>Miscellaneous</h3>
+<ol start="26">
+<li>
+<a href="#faq-26">Chaining transformations</a>
+</li>
+<li>
+<a href="#faq-27">Stylesheet validation</a>
+</li>
+<li>
+<a href="#faq-28">Setting output encoding</a>
+</li>
+<li>
+<a href="#faq-29">Getting line and column numbers for errors in XML input documents and XSL stylesheets</a>
+</li>
+<li>
+<a href="#faq-30">Servlet unable to find classes for extension functions/elements</a>
+</li>
+<li>
+<a href="#faq-31">Translet name doesn't match stylesheet name</a>
+</li>
+</ol>
+<h2 class="faqSubHead">Answers</h2>
+<h3 id="faq-1" class="faqTitle">1. Where do I go to learn about XSLT</h3>
+<div class="faqQuestion">Where do I go to learn about XSLT?</div>
+<br />
+<hr />
+<div class="faqAnswer">
+ <p>The definitive sources are the W3C XSLT and XPath recommendations:
+ <a href="http://www.w3.org/TR/xslt">XSL Transformations (XSLT) Version 1.0</a> and
+ <a href="http://www.w3.org/TR/xpath">XML Path Language (XPath) Version 1.0</a>.
+ </p>
+ <p>For a brief listing of tutorials, discussion forums, and other materials, see
+ <a href="overview.html#uptospeed">Getting up to speed with XSLT</a>.
+ </p>
+ </div>
+<p align="right" size="2">
+<a href="#content">(top)</a>
+</p>
+<h3 id="faq-2" class="faqTitle">2. Where can I ask questions about XSLT</h3>
+<div class="faqQuestion">Where can I ask questions about XSLT?</div>
+<br />
+<hr />
+<div class="faqAnswer">
+ <p>
+<a href="http://marc.theaimsgroup.com/?l=xalan-dev&r=1&w=2">xalan-dev</a> and
+ <a href="http://marc.theaimsgroup.com/?l=xalan-j-users&r=1&w=2">xalan-j-users</a>
+ are for Xalan-Java questions only. This is not the best
+ forum to ask general XSLT questions. The <a href="http://mulberrytech.com/xsl/xsl-list/index.html">Mulberry XSL Mailing List</a> is an
+ excellent place to ask XSLT questions; please search
+ <a href="http://www.dpawson.co.uk/xsl/">XSL Frequently Asked Questions</a> to ensure your question has not been already asked.
+ </p>
+ </div>
+<p align="right" size="2">
+<a href="#content">(top)</a>
+</p>
+<h3 id="faq-3" class="faqTitle">3. TrAX and JAXP</h3>
+<div class="faqQuestion">What are TrAX and JAXP, and are they related?</div>
+<br />
+<hr />
+<div class="faqAnswer">
+ <p>
+<a name="trax">â</a>
+</p>
+ <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>Xalan-Java includes the JAXP packages, implements the TrAX portion of
+ that API (javax.xml.transform....), implements the XPath API of JAXP (javax.xml.xpath....),
+ and includes xercesImpl.jar from
+ <a href="http://xerces.apache.org/xerces2-j/index.html">Xerces-Java 2.11.0</a>, which implements the parser portion of the API
+ (javax.xml.parser....).</p>
+ <p>For more information, see <a href="trax.html">Using the JAXP Transform APIs</a> and
+ <a href="https://jaxp.java.net/">Java API for XML Processing (JAXP) 1.3</a>.
+ </p>
+ </div>
+<p align="right" size="2">
+<a href="#content">(top)</a>
+</p>
+<h3 id="faq-4" class="faqTitle">4. Determining Xalan-Java Version</h3>
+<div class="faqQuestion">How do I see what version of Xalan-Java I'm running? How do I determine
+ which parser I'm using?</div>
+<br />
+<hr />
+<div class="faqAnswer">
+ <p>
+ <a name="environmentcheck">â</a>
+ </p>
+ <p>
+ <b>Using the EnvironmentCheck utility:</b> To help diagnose classpath problems and also
+ determine which version of Xalan-Java is being used, try running
+ Xalan-Java's environment checking utility.
+ </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>
+ <p>Best of all, you can call checkEnvironment from a stylesheet using extensions:</p>
+ <blockquote class="source">
+<pre>
+<?xml version="1.0"?>
+<xsl:stylesheet xmlns:xsl="http://www.w3.org/1999/XSL/Transform" version="1.0"
+ xmlns:xalan="http://xml.apache.org/xalan"
+ exclude-result-prefixes="xalan">
+<xsl:output indent="yes"/>
+
+<xsl:template match="/">
+ <out>
+ <xsl:copy-of select="xalan:checkEnvironment()"/>
+ </out>
+</xsl:template>
+</xsl:stylesheet></pre>
+</blockquote>
+ </div>
+<p align="right" size="2">
+<a href="#content">(top)</a>
+</p>
+<h3 id="faq-5" class="faqTitle">5. Determining the Serializer Version</h3>
+<div class="faqQuestion">How do I see what version of the Serializer I'm running? </div>
+<br />
+<hr />
+<div class="faqAnswer">
+ <a name="serlializercheck">â</a>
+ <p>
+ Xalan's serialier is now shared with Xerces. It may be packaged in Xalan, or Xerces,
+ or in the JRE itself. You can run the serializer's <b>Version</b> utility from the command line as follows:
+ </p>
+ <p>
+ <code>java org.apache.xml.serializer.Version</code>
+ </p>
+ The output should indicate which serializer you are using.
+ </div>
+<p align="right" size="2">
+<a href="#content">(top)</a>
+</p>
+<h3 id="faq-6" class="faqTitle">6. Which version of Xerces should I be using?</h3>
+<div class="faqQuestion">Which version of Xerces-Java should I be using?</div>
+<br />
+<hr />
+<div class="faqAnswer">
+ <p>
+<a href="http://xalan.apache.org/xalan-j">Xalan-Java Version 2.7.2</a> has been tested with <a href="http://xerces.apache.org/xerces2-j/index.html">Xerces-Java 2.11.0</a>.
+ See <a href="readme.html#status">Status</a>.
+ </p>
+ </div>
+<p align="right" size="2">
+<a href="#content">(top)</a>
+</p>
+<h3 id="faq-7" class="faqTitle">7. Compatibility with Xalan-Java version 1</h3>
+<div class="faqQuestion">How do I run applications that use the Xalan-Java version 1 API with Xalan-Java</div>
+<br />
+<hr />
+<div class="faqAnswer">
+ <p>The Xalan-Java version 1 compatibility API has been deprecated and removed, so you
+ must use the Xalan-Java version 2 API. We strongly encourage you to use the
+ <a href="https://jaxp.java.net/">Java API for XML Processing (JAXP) 1.3</a>. For more information, see
+ the FAQ on <a href="#trax">TrAX and JAXP.</a>
+</p>
+ </div>
+<p align="right" size="2">
+<a href="#content">(top)</a>
+</p>
+<h3 id="faq-8" class="faqTitle">8. Issues running Xalan-Java on JDK 1.3</h3>
+<div class="faqQuestion">I'm having a problem building or running Xalan-Java on the JDK 1.3.</div>
+<br />
+<hr />
+<div class="faqAnswer">
+ <p>
+<a name="jdk13">â</a>
+</p>
+ <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 Xalan-Java 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.3 interfaces and therefore does not work with the
+ current Xalan-Java release. Accordingly, you must either remove the
+ xerces.jar that is in that directory or replace it with the xercesImpl.jar that is included
+ with the Xalan-Java distribution.</p>
+ <p>The SUN JDK 1.3 includes a pre-1.1 version of the JAXP in crimson.jar. Either remove the
+ crimson.jar in that directory or overwrite it with a newer crimson.jar that includes and
+ implements the JAXP 1.3 interfaces.</p>
+ </div>
+<p align="right" size="2">
+<a href="#content">(top)</a>
+</p>
+<h3 id="faq-9" class="faqTitle">9. Issues running Xalan-Java on JDK/JRE 1.4 or higher</h3>
+<div class="faqQuestion">I'm having a problem running Xalan-Java on JDK/JRE 1.4 or higher</div>
+<br />
+<hr />
+<div class="faqAnswer">
+ <p>
+<a name="jdk14">â</a>
+</p>
+ <p>JDK/JRE 1.4, and JDK/JRE 5.0 is packaged with an old version of Xalan-Java. The JDK/JRE
+ will attempt to use this version instead of any on the classpath. Unfortunately,
+ this causes problems when attempting to use a newer version of Xalan-Java.</p>
+ <p>You can always determine which version of Xalan-Java you are running
+ by using the <a href="#environmentcheck">EnvironmentCheck</a> class or by using the
+ xalan:checkEnvironment extension function. It is highly recommended that you use this
+ method to verify the version of Xalan-Java you are running, especially
+ before opening a bug report.</p>
+ <p>To use a newer version of Xalan-Java and override the one packaged with the JDK:</p>
+ <ul>
+ <li>use the
+ <a href="http://java.sun.com/j2se/1.4.2/docs/guide/standards/">Endorsed Standards Override Mechanism</a>. Place the xalan.jar, serializer.jar, xercesImpl.jar
+ and xml-apis.jar in the
+ <java-home>\lib\endorsed directory, where
+ <java-home> is where the runtime software is installed.
+ </li>
+ </ul>
+ <p>The following methods
+ <b>do not work</b>:
+ </p>
+ <ul>
+ <li>Using the CLASSPATH environment variable or using -classpath to place the new classes
+ in the classpath.</li>
+ <li>Using the -jar option to explicitly execute the classes inside the new jar files.</li>
+ </ul>
+ </div>
+<p align="right" size="2">
+<a href="#content">(top)</a>
+</p>
+<h3 id="faq-10" class="faqTitle">10. Issues running Xalan-Java on Tomcat with JDK 1.4</h3>
+<div class="faqQuestion">I got java.lang.IllegalAccessError running Xalan-Java on Tomcat with JDK 1.4.</div>
+<br />
+<hr />
+<div class="faqAnswer">
+ <p>
+<a name="tomcat">â</a>
+</p>
+ <p>
+<a href="http://tomcat.apache.org/index.html">jakarta-tomcat 4.1.*</a> is packed
+ with an old version of xercesImpl.jar. Based on the <a href="http://java.sun.com/j2se/1.4.2/docs/guide/standards/">Endorsed Standards Override Mechanism</a>, you should
+ replace it with the newer xercesImpl.jar. You should add a newer xalan.jar and serializer.jar
+ to Tomcat as well.
+ Read the FAQ about <a href="#jdk14">Issues running Xalan-Java on JDK/JRE 1.4 or higher</a>. Place the
+ xalan.jar, serializer.jar, and xercesImpl.jar in the <Tomcat_Home>\common\endorsed directory, where
+ <Tomcat_Home> is where the Tomcat application server is installed.</p>
+ </div>
+<p align="right" size="2">
+<a href="#content">(top)</a>
+</p>
+<h3 id="faq-11" class="faqTitle">11. Issues running Applets with XSLTC in Web Browsers with JAVA Plug-in (JRE 1.4)</h3>
+<div class="faqQuestion">I got javax.xml.transform.TransformerException running my applet which uses XSLTC in JRE 1.4.</div>
+<br />
+<hr />
+<div class="faqAnswer">
+ <p>
+<a name="applet">â</a>
+</p>
+ <p>To overwrite an older version of Xalan Java; packaged with JRE 1.4 or higher you can add a newer
+ xalan.jar and serializer.jar to the <jre-home>\lib\endorsed directory. Read the FAQ about
+ <a href="#jdk14">Issues running
+ Xalan-Java on JDK/JRE 1.4 or higer</a>. If there is a META-INF/services/javax.xml.transform.TransformerFactory
+ file in xalan.jar (as there is in the Xalan Java distributions), then the TransformerFactoryImpl
+ setting in this file will be used by the JVM during the factory finder lookup procedure.
+ The TransformerFactoryImpl for the Xalan Java Interpretive processor is the default setting in the
+ META-INF/services/javax.xml.transform.TransformerFactory file, therefore, you will get an error
+ when your applet attempts to use the XSLTC implementation.</p>
+ <p>To work around this problem, you can change the contents of the
+ META-INF/services/javax.xml.transform.TransformerFactory file in xalan.jar so that it refers to the
+ transformer factory class implementation for XSLTC, org.apache.xalan.xsltc.trax.TransformerFactoryImpl. </p>
+ <p>Another solution is to create a jar that contains a META-INF/services/javax.xml.transform.TransformerFactory file
+ containing the value org.apache.xalan.xsltc.trax.TransformerFactoryImpl. Place the jar in the
+ <jre-home>\lib\endorsed directory. When you name your jar file, the ASCII code of the first
+ character should be smaller than the ASCII code of "X" to ensure that your jar will be loaded before
+ xalan.jar</p>
+ </div>
+<p align="right" size="2">
+<a href="#content">(top)</a>
+</p>
+<h3 id="faq-12" class="faqTitle">12. Using the 'signature' file to verify a download</h3>
+<div class="faqQuestion">How do I use the "signature" file to verify my download?</div>
+<br />
+<hr />
+<div class="faqAnswer">
+ <p>For each Xalan-Java download file 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 authenticity of the download. You do not
+ need the .sig file to use the corresponding download file.</p>
+ <p>To check the authenticity of a Xalan-Java 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>
+ <p>The PGP key can be found in
+ <a href="http://svn.apache.org/viewvc/xalan/java/trunk/KEYS">KEYS.</a>
+</p>
+ </div>
+<p align="right" size="2">
+<a href="#content">(top)</a>
+</p>
+<h3 id="faq-13" class="faqTitle">13. Speeding up transformations</h3>
+<div class="faqQuestion">What can I do to speed up transformations?</div>
+<br />
+<hr />
+<div class="faqAnswer">
+ <p>In the ongoing development of Xalan-Java, enhancing performance is
+ the primary goal of the Xalan-Java 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
+ <a href="usagepatterns.html#multithreading">Multithreading</a>).
+ <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, <br />
+<code><xsl:variable name="fooElem" select="foo"/></code>
+<br /> is usually faster than
+ <br />
+<code><xsl:variable name="fooElem"><xsl:value-of-select="foo"/></xsl:variable></code>
+ <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
+ <a href="samples.html#appletxmltohtml">appletXMLtoHTML</a> and
+ <a href="samples.html#get-todo-list">get-todo-list</a>.
+ </li>
+ </ul>
+ </div>
+<p align="right" size="2">
+<a href="#content">(top)</a>
+</p>
+<h3 id="faq-14" class="faqTitle">14. JAXP factory lookup procedure</h3>
+<div class="faqQuestion">What is the JAXP factory lookup procedure and does it affect performance?</div>
+<br />
+<hr />
+<div class="faqAnswer">
+ <p>JAXP uses an ordered lookup procedure to find factory implementations, such as
+ an implementation of javax.xml.transform.TransformerFactory. For information
+ on this procedure, refer to Section 3 Plugability in <a href="https://jaxp.java.net/">JAXP 1.3</a>.
+ </p>
+ <p>In most cases, Factory classes need only be looked up once for an application, so
+ performance is not an issue. However, there may be scenarios where the lookup
+ procedure executes multiple times which could impact performance. In these cases,
+ users may want to set system properties or populate the jaxp.properties file in order
+ to shorten the time spent in the lookup procedure.
+ </p>
+ </div>
+<p align="right" size="2">
+<a href="#content">(top)</a>
+</p>
+<h3 id="faq-15" class="faqTitle">15. Retrieving nodes in the default namespace</h3>
+<div class="faqQuestion">XPath isn't retrieving nodes that are in the default namespace I defined. How do I get them?</div>
+<br />
+<hr />
+<div class="faqAnswer">
+ <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
+ <a href="http://www.w3.org/TR/xpath.html#node-tests">XPath Node Tests</a>). 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 namespace 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: Avoiding the use of default namespaces will prevent this problem from occuring.</p>
+ </div>
+<p align="right" size="2">
+<a href="#content">(top)</a>
+</p>
+<h3 id="faq-16" class="faqTitle">16. Setting the parser to be namespace aware</h3>
+<div class="faqQuestion">
+ How do I set my parser to be namespace aware?
+ </div>
+<br />
+<hr />
+<div class="faqAnswer">
+ <p>
+<a name="namespace-aware">â</a>
+</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>
+ <blockquote class="source">
+<pre>javax.xml.parsers.SAXParserFactory spFactory =
+ javax.xml.parsers.SAXParserFactory.newInstance();
+spFactory.setNamespaceAware(true);</pre>
+</blockquote>
+ <table class="note">
+<tr>
+<td class="noteImg">
+<img src="resources/note.gif" alt="note" />
+</td>
+<td class="noteTxt">For more information about setting the namespaceAware property, and SAX2 vs. JAXP default
+ settings, see <a href="http://people.apache.org/~edwingo/jaxp-faq.html#nsDefaults">JAXP FAQ:
+ Warning about namespace processing defaults</a>.
+ </td>
+</tr>
+</table>
+ </div>
+<p align="right" size="2">
+<a href="#content">(top)</a>
+</p>
+<h3 id="faq-17" class="faqTitle">17. NoClassDefFound errors</h3>
+<div class="faqQuestion">I'm getting a NoClassDefFound error. What has to be on the classpath?</div>
+<br />
+<hr />
+<div class="faqAnswer">
+ <ol>
+ <li>xalan.jar, serializer.jar, xml-apis.jar, and xercesImpl.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 samples, you must place xalanservlet.war
+ on a web server with a servlet engine and you must put the javax.servlet and
+ javax.servlet.http packages on the classpath. These packages
+ are available via the servlet.jar file found in Apache Tomcat ( see <a href="http://tomcat.apache.org/">The Jakarta Site - Apache Tomcat</a> ).
+ <br />
+ <br />
+ </li>
+ <li>To run extensions which use the component and script extension elements (including the
+ samples in samples/extensions), bsf.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
+ <a href="extensions.html#supported-lang">Supported languages</a>.
+ </li>
+ </ol>
+ You can check the correctness of your environment with the
+ <a href="#environmentcheck">EnvironmentCheck</a> feature.
+ <p>For more information, see
+ <a href="getstarted.html#classpath">Setting up the system classpath</a>.
+ </p>
+ </div>
+<p align="right" size="2">
+<a href="#content">(top)</a>
+</p>
+<h3 id="faq-18" class="faqTitle">18. a "DOM006 Hierarchy request error"</h3>
+<div class="faqQuestion">Why do I get a "DOM006 Hierarchy request error" when I try to transform into a DOM Document node?</div>
+<br />
+<hr />
+<div class="faqAnswer">
+ <p>This error occurs when Xalan-Java 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-Java, you
+ get a "DOM006 Hierarchy request error" when Xalan-Java 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.3 documentation.</p>
+ </div>
+<p align="right" size="2">
+<a href="#content">(top)</a>
+</p>
+<h3 id="faq-19" class="faqTitle">19. Namespace not supported by SAXParser</h3>
+<div class="faqQuestion">Why am I getting a "Namespace not supported by SAXParser exception?</div>
+<br />
+<hr />
+<div class="faqAnswer">
+ <p>We have seen this problem 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>
+ <b>SAX1 on the classpath</b>
+ </p>
+ <p>SAX1 should not be on your classpath. The SAX1 interfaces and implementations of the SAX1
+ SAX parser are not namespace aware.</p>
+ <p>To help diagnose your classpath, you can use the
+ <a href="#environmentcheck">EnvironmentCheck
+ utility</a>. If you are running under JDK 1.3, see
+ <a href="#jdk13">Issues running Xalan-Java on JDK
+ 1.3</a>. If you are running a servlet, make sure the webserver is not placing SAX1 on the
+ classpath.
+ </p>
+ <p>When you create a Transformer, you must use a
+ <a href="#namespace-aware">namespace-aware</a> parser to parse the stylesheet.
+ </p>
+ </div>
+<p align="right" size="2">
+<a href="#content">(top)</a>
+</p>
+<h3 id="faq-20" class="faqTitle">20. Missing xsl:version attribute error</h3>
+<div class="faqQuestion">I'm getting an error about my stylesheet missing the xsl:version attribute - what's wrong?</div>
+<br />
+<hr />
+<div class="faqAnswer">
+ <p>There are two common causes for this error.</p>
+ <ol>
+ <li>Using the wrong URI for the xsl: prefix will cause this message. URIs, and namespace
+ URIs in particular, are case sensitive. Ensure the URI for the xsl namespace is
+ "http://www.w3.org/1999/XSL/Transform".<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.<br />
+ When you create a Transformer, you must use a <a href="#namespace-aware">namespace-aware</a> parser to parse the stylesheet.</li>
+ </ol>
+ </div>
+<p align="right" size="2">
+<a href="#content">(top)</a>
+</p>
+<h3 id="faq-21" class="faqTitle">21. StackOverflowError with recursive stylesheet</h3>
+<div class="faqQuestion">Xalan-Java dies with a java.lang.StackOverflowError when I run a deeply
+ recursive stylesheet. The same stylesheet worked fine in the past (or on other machines).
+ What's happening?</div>
+<br />
+<hr />
+<div class="faqAnswer">
+ <p>That may not be our fault. As of JDK 1.3.x, many Java Virtual Machine publishers reduced
+ the default size of a thread's call stack from 1MB to 256KB. This allows more threads to
+ run simultaneously, but it means that each thread is more limited in how deeply its function
+ calls can be nested.</p>
+ <p>Some JVMs may offer an option that allows you to raise this limit. For example, in Sun
+ JDK 1.3.1 you can start JVM with the -Xss1m option to allow each thread to use a full
+ megabyte. In IBM's JDK you can start with the -Xss1m and -Xoss1m options. Other JVMs
+ may set this in other ways, or may not allow you to control it at all; check the
+ documentation on your system for details.</p>
+ <p>Note too that on some platforms 1MB is an architectural upper limit on the stack size, so
+ setting -Xss2m (or equivalent) may not allow deeper recursion than -Xss1m.</p>
+ </div>
+<p align="right" size="2">
+<a href="#content">(top)</a>
+</p>
+<h3 id="faq-22" class="faqTitle">22. OutOfMemoryError processing multiple documents</h3>
+<div class="faqQuestion">I get a java.lang.OutOfMemoryError when I try to process multiple documents with the
+ document() function. What can I do?</div>
+<br />
+<hr />
+<div class="faqAnswer">
+ <p>As a general rule, Xalan-Java currently caches all of the documents
+ that you read in with the document() function during a transformation.</p>
+ <p>If your objective is to transform a series of documents, you can break the process into a
+ series of transformations. The
+ <a href="extensionslib.html#pipedocument">PipeDocument</a> extension element
+ provides one strategy for batching a series of parallel transformations.</p>
+ <p>Another alternative is to place your document() call in the select attribute of an
+ xsl:for-each instruction element and use a custom PI (Processing Instruction) to turn off
+ document caching. Include an XPath expression in your document() call if you do not
+ need to process the entire document.</p>
+ <p>Sample stylesheet fragment:</p>
+ <blockquote class="source">
+<pre>
+<xsl:template match="doc">
+ <xsl:for-each select="document(@href)/bar/zulu">
+ <?xalan-doc-cache-off?>
+ <!-- process each document -->
+ <xsl:for-each>
+</xsl:template></pre>
+</blockquote>
+ <table class="note">
+<tr>
+<td class="noteImg">
+<img src="resources/note.gif" alt="note" />
+</td>
+<td class="noteTxt">PIs do not ordinarily uses namespaces, so "xalan:" is a 'fake' namespace we have
+ included to indicate that this is not a standard PI.</td>
+</tr>
+</table>
+ <p>If you include an XPath expression in your document() call, you can also turn on
+ <a href="dtm.html#incremental">incremental transform</a> to eliminate the need
+ to read in the entire document. In fact, you can take advantage of the incremental transform
+ feature even if you are not turning off document caching.
+ </p>
+ <p>You can also increase your JVM heap size with the -Xmx or -mx flag, depending on which JVM
+ you are using (you can include both flags, and the JVM will ignore the one it doesn't
+ understand). For example, to give your JVM 64 meg, try
+ <br />
+ <code> java -Xmx64m -mx64m
+ <b>
+<i>Class</i>
+</b>
+ </code>
+ </p>
+ </div>
+<p align="right" size="2">
+<a href="#content">(top)</a>
+</p>
+<h3 id="faq-23" class="faqTitle">23. File Not Found error</h3>
+<div class="faqQuestion">Why do I get 'file not found' when I pass c:\path\filename.txt?</div>
+<br />
+<hr />
+<div class="faqAnswer">
+ <p>Xalan-Java often requires legal URLs as system identifiers, not local
+ pathnames (this is partly due to underlying parsers requiring this). A simple (but not always
+ correct!) way to change a local pathname into a URL in Java 1.1x is:</p>
+ <blockquote class="source">
+<pre>
+ public static String filenameToURL(String filename)
+ {
+ File f = new File(filename);
+ String tmp = f.getAbsolutePath();
+ if (File.separatorChar == '\\')
+ {
+ tmp = tmp.replace('\\', '/');
+ }
+ // Note: gives incorrect results when filename already begins with
+file:///
+ return "file:///" + tmp;
+ }
+ </pre>
+</blockquote>
+ <p>For a slightly more detailed example, see org.apache.xml.utils.SystemIDResolver.</p>
+ </div>
+<p align="right" size="2">
+<a href="#content">(top)</a>
+</p>
+<h3 id="faq-24" class="faqTitle">24. No more DTM IDs are available</h3>
+<div class="faqQuestion">What does: "XSLT Error (javax.xml.transform.TransformerException):
+ org.apache.xml.dtm.DTMException: No more DTM IDs are available" mean?</div>
+<br />
+<hr />
+<div class="faqAnswer">
+ <p>It means you are probably using a very old version of Xalan or Xalan-Java,
+ likely the version 2.2D11 which was packaged in JDK1.4. Architectural changes made in
+ early 2002 should have eliminated this issue for almost all cases.</p>
+ <p>You should verify the version of Xalan-Java you are using by running
+ the <a href="#environmentcheck">EnvironmentCheck</a> utility,
+ and read the FAQ about <a href="#jdk14">Issues running Xalan-Java
+ on JDK 1.4</a>.</p>
+ </div>
+<p align="right" size="2">
+<a href="#content">(top)</a>
+</p>
+<h3 id="faq-25" class="faqTitle">25. IllegalAccessError or could not load output_xml.properties on JDK 1.4</h3>
+<div class="faqQuestion">Why do I get a "java.lang.IllegalAccessError" or the message
+ "Could not load the property file 'output_xml.properties'" when I try
+ to transform using XSLTC or Xalan-Java Interpretive?</div>
+<br />
+<hr />
+<div class="faqAnswer">
+ <p>These errors may occur if you use JDK 1.4 or later releases.</p>
+ <p>JRE 1.4 and later releases contain copies of Xalan-Java. In some
+ cases, the JRE includes only Xalan-Java Interpretive, while in other cases it also
+ includes XSLTC. Typically, the copy of the processor packaged
+ with the JRE will be loaded in preference to any copy of Xalan-Java on
+ your class path.</p>
+ <p>Beginning with Xalan-Java 2.5, Xalan-Java Interpretive and XSLTC are both
+ packaged in xalan.jar, and share some of the same classes. If you
+ are using a version of the JRE that contains Xalan-Java Interpretive, but not
+ XSLTC, and you try to use XSLTC on your class path,
+ classes from that version of XSLTC may be loaded along with
+ classes from the version of Xalan-Java packaged with your JRE.</p>
+ <p>Because the classes may be from different versions of Xalan-Java, the
+ results may be unpredictable. In particular, a
+ <code>java.lang.IllegalAccessError</code> may be thrown, or an
+ <code>org.apache.xml.utils.WrappedRuntimeException</code> containing
+ the message: <code>"Could not load the property file
+ 'output_xml.properties' for output method 'xml' (check
+ CLASSPATH)"</code> may be thrown.</p>
+ <p>To work around those problems, please read the FAQ entitled
+ <a href="#jdk14">Issues running Xalan-Java on JDK 1.4</a>.</p>
+ </div>
+<p align="right" size="2">
+<a href="#content">(top)</a>
+</p>
+<h3 id="faq-26" class="faqTitle">26. Chaining transformations</h3>
+<div class="faqQuestion">How do you chain together a series of transformations?</div>
+<br />
+<hr />
+<div class="faqAnswer">
+ <p>Xalan-Java 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 ContentHandler 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
+ <a href="usagepatterns.html#outasin">Using transformation output as input for
+ another transformation</a>.</p>
+ </div>
+<p align="right" size="2">
+<a href="#content">(top)</a>
+</p>
+<h3 id="faq-27" class="faqTitle">27. Stylesheet validation</h3>
+<div class="faqQuestion">How do I validate an XSL stylesheet?</div>
+<br />
+<hr />
+<div class="faqAnswer">
+ <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
+ <a href="http://www.w3.org/TR/xslt#dtd">DTD Fragment
+ for XSL Stylesheets</a> 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>
+ </div>
+<p align="right" size="2">
+<a href="#content">(top)</a>
+</p>
+<h3 id="faq-28" class="faqTitle">28. Setting output encoding</h3>
+<div class="faqQuestion">Why is the output character encoding I set in the stylesheet not being used?</div>
+<br />
+<hr />
+<div class="faqAnswer">
+ <p>If you use a character output stream to instantiate the
+ <a href="apidocs/javax/xml/transform/stream/StreamResult.html">StreamResult</a> 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. If the transformation is run in a servlet, it is possible
+ that the Writer is coming from the ServletResponse object.
+ </p>
+ <p>
+ If the stylesheet is run using the JAXP APIs and the Transformer's setOutputProperty()
+ method is invoked, it is possible to set the <b>"encoding"</b> property and
+ over-ride the value in the stylesheet.
+ </p>
+ </div>
+<p align="right" size="2">
+<a href="#content">(top)</a>
+</p>
+<h3 id="faq-29" class="faqTitle">29. Getting line and column numbers for errors in XML input documents and XSL stylesheets</h3>
+<div class="faqQuestion">How do I get line numbers for errors in the XML or XSL input when I am performing a
+ transformation?</div>
+<br />
+<hr />
+<div class="faqAnswer">
+ <p>Use or mimic the command-line processor (<a href="apidocs/org/apache/xalan/xslt/Process.html">org.apache.xalan.xslt.Process</a>).
+ </p>
+ <p>A
+ <a href="apidocs/javax/xml/transform/TransformerException.html">TransformerException</a> generally wraps another exception, often a SAXParseException. The command-line processor uses the static
+ <a href="apidocs/org/apache/xml/utils/DefaultErrorHandler.html">org.apache.xml.utils.DefaultErrorHandler</a> printLocation() method to chase down the exception cause and get a
+ <a href="apidocs/javax/xml/transform/SourceLocator.html">SourceLocator</a> 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>
+ <blockquote class="source">
+<pre>public void error (SAXParseException spe)
+ throws SAXException
+{
+ System.out.println("SAXParseException error: " + spe.getMessage());
+}</pre>
+</blockquote>
+ <p>with</p>
+ <blockquote class="source">
+<pre>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());
+}</pre>
+</blockquote>
+ <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>
+ <blockquote class="source">
+<pre>
+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;
+}</pre>
+</blockquote>
+ <table class="note">
+<tr>
+<td class="noteImg">
+<img src="resources/note.gif" alt="note" />
+</td>
+<td class="noteTxt">
+ <b>Xalan-Java exception handling:</b> The exception architecture
+ in Xalan-Java 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-Java 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.3 TransformerException often wraps another exception. Two of the
+ TransformerException structures that are frequently used to construct contained exceptions
+ in JAXP 1.3 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-Java command-line processor uses to report errors. You can also
+ roll your own functions along the lines of the getRootSourceLocator() example above.
+ </td>
+</tr>
+</table>
+ </div>
+<p align="right" size="2">
+<a href="#content">(top)</a>
+</p>
+<h3 id="faq-30" class="faqTitle">30. Servlet unable to find classes for extension functions/elements</h3>
+<div class="faqQuestion">My servlet cannot find classes that implement extension functions or elements. What can I do?</div>
+<br />
+<hr />
+<div class="faqAnswer">
+ <p>If you install xalan.jar in the webserver's lib directory (e.g., tomcat/lib), as
+ opposed to the servlet application's lib directory, then the Xalan-Java classes
+ are loaded by a classloader that does not see the classes in the application's classloader
+ (i.e., the extension classes, if you placed them there). The Xalan-Java
+ classes try to load the extension classes using their own classloader, and that attempt
+ fails.</p>
+ <p>Workaround: place xalan.jar in the servlet application's lib directory and NOT in the webserver's
+ lib directory. Another workaround is to place the extension classes also in the webserver'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>
+ </div>
+<p align="right" size="2">
+<a href="#content">(top)</a>
+</p>
+<h3 id="faq-31" class="faqTitle">31. Translet name doesn't match stylesheet name</h3>
+<div class="faqQuestion">My stylesheet is named <code>foo-bar.xsl</code>, but XSLTC
+ created a translet named <code>foo_bar</code>. Is that a bug?</div>
+<br />
+<hr />
+<div class="faqAnswer">
+ <p>No. The name of a translet is usually the name of the stylesheet,
+ the name specified using the <code>translet-name</code> attribute on
+ the XSLTC <code>TransformerFactory</code> or the name
+ specified for the translet on the command-line invocation.
+ However, the name of the translet is also the name of a Java class.
+ Any character that is not permitted in a class name is replaced with
+ an underscore.</p>
+ </div>
+<p align="right" size="2">
+<a href="#content">(top)</a>
+</p>
+</div>
+<div id="footer">Copyright © 1999-2014 The Apache Software Foundation<br />Apache, Xalan, and the Feather logo are trademarks of The Apache Software Foundation<div class="small">Web Page created on - Thu 2014-05-15</div>
+</div>
+</body>
+</html>
Propchange: xalan/java/branches/WebSite/xalan-j/faq.html
------------------------------------------------------------------------------
svn:eol-style = native
Added: xalan/java/branches/WebSite/xalan-j/features.html
URL: http://svn.apache.org/viewvc/xalan/java/branches/WebSite/xalan-j/features.html?rev=1595253&view=auto
==============================================================================
--- xalan/java/branches/WebSite/xalan-j/features.html (added)
+++ xalan/java/branches/WebSite/xalan-j/features.html Fri May 16 16:11:33 2014
@@ -0,0 +1,509 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
+<html>
+<head>
+<title>ASF: Transform Features</title>
+<meta http-equiv="content-type" content="text/html; charset=UTF-8" />
+<meta http-equiv="Content-Style-Type" content="text/css" />
+<link rel="stylesheet" type="text/css" href="resources/apache-xalan.css" />
+</head>
+<!--
+ * Licensed to the Apache Software Foundation (ASF) under one
+ * or more contributor license agreements. See the NOTICE file
+ * distributed with this work for additional information
+ * regarding copyright ownership. The ASF licenses this file
+ * to you under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ -->
+<body>
+<div id="title">
+<table class="HdrTitle">
+<tbody>
+<tr>
+<th rowspan="2">
+<a href="../index.html">
+<img alt="Trademark Logo" src="resources/XalanJ-Logo-tm.png" width="190" height="90" />
+</a>
+</th>
+<th text-align="center" width="75%">
+<a href="index.html">Xalan XSL Transformer User's Guide</a>
+</th>
+</tr>
+<tr>
+<td valign="middle">Transform Features</td>
+</tr>
+</tbody>
+</table>
+<table class="HdrButtons" align="center" border="1">
+<tbody>
+<tr>
+<td>
+<a href="http://www.apache.org">Apache Foundation</a>
+</td>
+<td>
+<a href="http://xalan.apache.org">Xalan Project</a>
+</td>
+<td>
+<a href="http://xerces.apache.org">Xerces Project</a>
+</td>
+<td>
+<a href="http://www.w3.org/TR">Web Consortium</a>
+</td>
+<td>
+<a href="http://www.oasis-open.org/standards">Oasis Open</a>
+</td>
+</tr>
+</tbody>
+</table>
+</div>
+<div id="navLeft">
+<ul>
+<li>
+<a href="resources.html">Resources</a>
+<br />
+</li>
+<li>
+<a href="http://xalan.apache.org/index.html">Home</a>
+</li></ul><hr /><ul>
+<li>
+<a href="index.html">Xalan-J 2.7.2</a>
+</li>
+<li>
+<a href="charter.html">Charter</a>
+</li></ul><hr /><ul>
+<li>
+<a href="whatsnew.html">What's New</a>
+</li>
+<li>
+<a href="readme.html">Release Notes</a>
+</li></ul><hr /><ul>
+<li>
+<a href="overview.html">Overview</a>
+</li>
+<li>
+<a href="downloads.html">Download/Build</a>
+</li>
+<li>
+<a href="getstarted.html">Getting Started</a>
+</li>
+<li>
+<a href="xsltc_usage.html">Using XSLTC</a>
+</li></ul><hr /><ul>
+<li>
+<a href="faq.html">FAQs</a>
+</li></ul><hr /><ul>
+<li>
+<a href="samples.html">Sample Apps</a>
+</li>
+<li>
+<a href="commandline.html">Command Line</a>
+</li></ul><hr /><ul>
+<li>Features<br />
+</li>
+<li>
+<a href="trax.html">Transform API</a>
+</li>
+<li>
+<a href="xpath_apis.html">XPath API</a>
+</li>
+<li>
+<a href="usagepatterns.html">Usage Patterns</a>
+</li></ul><hr /><ul>
+<li>
+<a href="apidocs/index.html">Xalan-J API</a>
+</li>
+<li>
+<a href="public_apis.html">Public APIs</a>
+</li>
+<li>
+<a href="dtm.html">DTM</a>
+</li></ul><hr /><ul>
+<li>
+<a href="extensions.html">Extensions</a>
+</li>
+<li>
+<a href="extensionslib.html">Extensions Library</a>
+</li>
+<li>
+<a href="extensions_xsltc.html">XSLTC Exts</a>
+</li></ul><hr /><ul>
+<li>
+<a href="design/design2_0_0.html">Xalan 2 Design</a>
+</li>
+<li>
+<a href="xsltc/index.html">XSLTC Design</a>
+</li></ul><hr /><ul>
+<li>
+<a href="builds.html">Building a release</a>
+</li>
+<li>
+<a href="http://xml.apache.org/xalan-j/test/overview.html">Testing</a>
+</li>
+<li>
+<a href="bugreporting.html">Bug Reporting</a>
+</li></ul><hr /><ul>
+<li>
+<a href="contact_us.html">Contact us</a>
+</li>
+</ul>
+</div>
+<div id="content">
+<h2>Transform Features</h2>
+<p>Transform features are identified by URI Strings and fall into the following categories:</p>
+<ul>
+<li>
+<a href="#factoryfeature">Standard TransformationFactory features</a>
+</li>
+<li>
+<a href="#factoryattribute">Implementation-specific TransformerFactory attributes</a>
+</li>
+</ul>
+<a name="factoryfeature">â</a>
+<p align="right" size="2">
+<a href="#content">(top)</a>
+</p>
+<h3>Standard TransformerFactory features</h3>
+<p>
+<a href="https://jaxp.java.net/">Java API for XML Processing (JAXP) 1.3</a> defines objects and methods for processing input and producing
+output in a variety of formats, including character streams, SAX event streams, and DOM Documents.</p>
+<p>JAXP 1.3 defines the following features:</p>
+<ul>
+<li>
+<a href="#streamsource">StreamSource feature</a>
+</li>
+<li>
+<a href="#streamresult">StreamResult feature</a>
+</li>
+<li>
+<a href="#domsource">DOMSource feature</a>
+</li>
+<li>
+<a href="#domresult">DOMResult feature</a>
+</li>
+<li>
+<a href="#saxsource">SAXSource feature</a>
+</li>
+<li>
+<a href="#saxresult">SAXResult feature</a>
+</li>
+<li>
+<a href="#saxtransformerfactory">SAXTransformerFactory feature</a>
+</li>
+<li>
+<a href="#xmlfilter">XMLFilter feature</a>
+</li>
+<li>
+<a href="#secureprocessing">Secure processing feature</a>
+</li>
+</ul>
+<p>You can use the
+ <a href="apidocs/javax/xml/transform/TransformerFactory.html#getFeature(java.lang.String)">TransformerFactory.getFeature(String)</a>
+method to return a boolean indicating whether the implementation you are using supports the use of one of these objects or methods. For the String argument, provide the static String variable or literal URI String as detailed below.</p>
+<p>You can use the
+<a href="apidocs/javax/xml/transform/TransformerFactory.html#setFeature(java.lang.String, boolean)">TransformerFactory.setFeature(String, boolean)</a>
+method to set the value of a feature. Xalan-Java only supports setting of the
+<a href="apidocs/javax/xml/XMLConstants.html#FEATURE_SECURE_PROCESSING">XMLConstants.FEATURE_SECURE_PROCESSING</a>
+feature. For all other features, TransformerFactory exposes their values, but cannot change their states.</p>
+<p>Xalan-Java supports <b>all</b> TransformerFactory features.</p>
+<a name="streamsource">â</a>
+<p align="right" size="2">
+<a href="#content">(top)</a>
+</p>
+<h4>StreamSource feature</h4>
+<p>
+<b>URI:</b> "http://javax.xml.transform.stream.StreamSource/feature"</p>
+<p>The implementation supports the processing of <a href="apidocs/javax/xml/transform/stream/StreamSource.html">StreamSource</a> input objects.</p>
+<p>To determine whether your implementation supports this feature (Xalan-Java does), you can use the static StreamSource.FEATURE variable (equivalent to the URI String above) as follows:</p>
+<blockquote class="source">
+<pre>import javax.xml.transform.TransformerFactory;
+import javax.xml.stream.StreamSource;
+
+TransformerFactory tFact = TransformerFactory.newInstance();
+if (tFact.getFeature(StreamSource.FEATURE)){
+ // Can process a StreamSource.
+ ..
+}</pre>
+</blockquote>
+<p>For a example that uses this feature, see <a href="samples.html#simpletransform">SimpleTransform</a>.</p>
+<a name="streamresult">â</a>
+<p align="right" size="2">
+<a href="#content">(top)</a>
+</p>
+<h4>StreamResult feature</h4>
+<p>
+<b>URI:</b> "http://javax.xml.transform.stream.StreamResult/feature"</p>
+<p>The implementation supports the production of transformation output in the form of <a href="apidocs/javax/xml/transform/stream/StreamResult.html">StreamResult</a> objects.</p>
+<p>To determine whether your implementation supports this feature (Xalan-Java does), you can use the static StreamResult.FEATURE variable (equivalent to the URI String above) as follows:</p>
+<blockquote class="source">
+<pre>import javax.xml.transform.TransformerFactory;
+import javax.xml.stream.StreamResult;
+..
+TransformerFactory tFact = TransformerFactory.newInstance();
+if (tFact.getFeature(StreamResult.FEATURE)){
+ // Can generate a StreamResult.
+ ..
+}</pre>
+</blockquote>
+<p>For a example that uses this feature, see <a href="samples.html#simpletransform">SimpleTransform</a>.</p>
+<a name="domsource">â</a>
+<p align="right" size="2">
+<a href="#content">(top)</a>
+</p>
+<h4>DOMSource feature</h4>
+<p>
+<b>URI:</b> "http://javax.xml.transform.dom.DOMSource/feature"</p>
+<p>The implementation supports the processing of XML input in the form of <a href="apidocs/javax/xml/transform/dom/DOMSource.html">DOMSource</a> objects.</p>
+<p>To determine whether your implementation supports this feature (Xalan-Java does), you can use the static DOMSource.FEATURE string variable (equivalent to the URI String above) as follows:</p>
+<blockquote class="source">
+<pre>import javax.xml.transform.TransformerFactory;
+import javax.xml.dom.DOMSource;
+..
+TransformerFactory tFact = TransformerFactory.newInstance();
+if (tFact.getFeature(DOMSource.FEATURE)){
+ // Can process DOM input
+ ..
+}</pre>
+</blockquote>
+<p>For a example that uses this feature, see <a href="samples.html#dom2dom">DOM2DOM</a>.</p>
+<a name="domresult">â</a>
+<p align="right" size="2">
+<a href="#content">(top)</a>
+</p>
+<h4>DOMResult feature</h4>
+<p>
+<b>URI:</b> "http://javax.xml.transform.dom.DOMResult/feature"</p>
+<p>The implementation supports the production of transformation output in the form of <a href="apidocs/javax/xml/transform/dom/DOMResult.html">DOMResult</a> objects.</p>
+<p>To determine whether your implementation supports this feature (Xalan-Java does), you can use the static DOMResult.FEATURE variable (equivalent to the URI String above) as follows:</p>
+<blockquote class="source">
+<pre>import javax.xml.transform.TransformerFactory;
+import javax.xml.dom.DOMResult;
+..
+TransformerFactory tFact = TransformerFactory.newInstance();
+if (tFact.getFeature(DOMResult.FEATURE)){
+ // Can generate DOM output.
+ ..
+}</pre>
+</blockquote>
+<p>For a example that uses this feature, see <a href="samples.html#dom2dom">DOM2DOM</a>.</p>
+<a name="saxsource">â</a>
+<p align="right" size="2">
+<a href="#content">(top)</a>
+</p>
+<h4>SAXSource feature</h4>
+<p>
+<b>URI:</b> "http://javax.xml.transform.dom.SAXSource/feature"</p>
+<p>The implementation supports the processing of XML input in the form of <a href="apidocs/javax/xml/transform/sax/SAXSource.html">SAXSource</a> objects.</p>
+<p>To determine whether your implementation supports this feature (Xalan-Java does), you can use the static SAXSource.FEATURE string variable (equivalent to the URI String above) as follows:</p>
+<blockquote class="source">
+<pre>import javax.xml.transform.TransformerFactory;
+import javax.xml.sax.SAXSource;
+..
+TransformerFactory tFact = TransformerFactory.newInstance();
+if (tFact.getFeature(SAXSource.FEATURE)){
+ // Can process SAX events.
+ ..
+}</pre>
+</blockquote>
+<a name="saxresult">â</a>
+<p align="right" size="2">
+<a href="#content">(top)</a>
+</p>
+<h4>SAXResult feature</h4>
+<p>
+<b>URI:</b> "http://javax.xml.transform.dom.SAXResult/feature"</p>
+<p>The implementation supports the production of transformation output in the form of <a href="apidocs/javax/xml/transform/sax/SAXResult.html">SAXResult</a> objects.</p>
+<p>To determine whether your implementation supports this feature (Xalan-Java does), you can use the static SAXResult.FEATURE variable (equivalent to the URI String above) as follows:</p>
+<blockquote class="source">
+<pre>import javax.xml.transform.TransformerFactory;
+import javax.xml.sax.SAXResult;
+..
+TransformerFactory tFact = TransformerFactory.newInstance();
+if (tFact.getFeature(SAXResult.FEATURE)){
+ // Can output SAX events.
+ ..
+}</pre>
+</blockquote>
+<p>For a example that uses this feature, see <a href="samples.html#sax2sax">SAX2SAX</a>.</p>
+<a name="saxtransformerfactory">â</a>
+<p align="right" size="2">
+<a href="#content">(top)</a>
+</p>
+<h4>SAXTransformerFactory feature</h4>
+<p>
+<b>URI:</b> "http://javax.xml.transform.sax.SAXTransformerFactory/feature"</p>
+<p>The implementation provides a <a href="apidocs/javax/xml/transform/sax/SAXTransformerFactory.html">SAXTransformerFactory</a>.
+You may safely cast the TransformerFactory returned by TransformerFactory.newInstance() to a SAXTransformerFactory.</p>
+<p>To determine whether your implementation supports this feature (Xalan-Java does), you can use the static SAXTransformerFactory.FEATURE
+variable (equivalent to the URI String above) as follows:</p>
+<blockquote class="source">
+<pre>import javax.xml.transform.TransformerFactory;
+import javax.xml.sax.SAXTransformerFactory;
+..
+TransformerFactory tFact = TransformerFactory.newInstance();
+if (tFact.getFeature(SAXTransformerFactory.FEATURE)){
+ SAXTransformerFactory saxTFact = (SAXTransformerFactory)tFact;
+ ..
+}</pre>
+</blockquote>
+<p>For a example that uses this feature, see <a href="samples.html#sax2sax">SAX2SAX</a>.</p>
+<a name="xmlfilter">â</a>
+<p align="right" size="2">
+<a href="#content">(top)</a>
+</p>
+<h4>XMLFilter feature</h4>
+<p>
+<b>URI: </b>"http://javax.xml.transform.sax.SAXTransformerFactory/feature/xmlfilter"</p>
+<p>The implementation supports the use of <a href="apidocs/org/xml/sax/XMLFilter.html">XMLFilter</a> to use the output of one
+transformation as input for another transformation. The SAXTransformerFactory newXMLFilter(Source) and newXMLFilter(Templates) methods
+are supported.</p>
+<p>To determine whether your implementation supports this feature (Xalan-Java does), you can use the static
+SAXTransformerFactory.FEATURE_XMLFilter variable (equivalent to the URI String above) as follows:</p>
+<blockquote class="source">
+<pre>import javax.xml.transform.TransformerFactory;
+import javax.xml.sax.SAXTransformerFactory;
+..
+TransformerFactory tFact = TransformerFactory.newInstance();
+if (tFact.getFeature(SAXTransformerFactory.FEATURE_XMLFILTER))){
+ // Can use SAXTransformerFactory to get XMLFilters.
+ ..
+}</pre>
+</blockquote>
+<p>For an example that uses this feature to chain together a series of transformations, see
+<a href="samples.html#usexmlfilters">UseXMLFilters</a>.</p>
+
+<a name="secureprocessing">â</a>
+<p align="right" size="2">
+<a href="#content">(top)</a>
+</p>
+<h4>Secure processing feature</h4>
+<p>
+<b>URI: </b>"http://javax.xml.XMLConstants/feature/secure-processing"</p>
+<p>Xalan-Java supports the secure processing feature in both the interpretive and XSLTC
+processors. When this feature is set to true, the implementation will apply a set of limits on the
+XSLT/XML processing behavior to make the XSLT processor behave in a secure fashion. The limits are
+implementation dependent. Xalan-Java applies the following limits when the secure processing feature
+is set to true:<br />
+<br />
+<li>extension functions and extension elements are disabled.</li>
+<li>parsers created by the XSLT processors will also have the secure processing feature set to true.</li>
+</p>
+
+<a name="factoryattribute">â</a>
+<p align="right" size="2">
+<a href="#content">(top)</a>
+</p>
+<h3>Xalan-Java TransformerFactory attributes</h3>
+<p>A given implementation may provide TransformerFactory attributes for which you can set and get values. Xalan-Java uses the
+<a href="dtm.html"> DTM (Document Table Model)</a> to support three attributes which can be set to true or false:</p>
+<ul>
+<li>
+<a href="#optimize">optimize attribute</a>
+</li>
+<li>
+<a href="#incremental">incremental attribute</a>
+</li>
+<li>
+<a href="#source_location">source_location attribute</a>
+</li>
+</ul>
+<p>To get an attribute setting, use the TransformerFactory.getAttribute(String) method, which returns an Object. For these three Xalan-Java
+attributes, you can cast the return value to a boolean. To set an attribute, use the TransformerFactory.setAttribute(String, Object) method.
+For the String argument, provide the static String variable or literal URI String as detailed below. For the Object argument, use
+Boolean.TRUE or Boolean.FALSE (or the Strings "true" or "false").</p>
+<a name="optimize">â</a>
+<p align="right" size="2">
+<a href="#content">(top)</a>
+</p>
+<h4>optimize attribute</h4>
+<p>
+<b>URI:</b> "http://xml.apache.org/xalan/features/optimize"</p>
+<p>Optimize stylesheet processing. By default, this attribute is set to true. You may need to set it to false for tooling applications.
+For more information, see <a href="dtm.html#optimize">DTM optimize</a>.</p>
+<p>To turn optimization off, you can use the TransformerFactoryImpl.FEATURE_OPTIMIZE static variable (equivalent to the URI String above)
+as follows:</p>
+<blockquote class="source">
+<pre>import javax.xml.transform.TransformerFactory;
+import org.apache.xalan.processor.TransformerFactoryImpl;
+..
+TransformerFactory tFact = TransformerFactory.newInstance();
+if (tFact instanceof TransformerFactoryImpl) {
+ tFact.setAttribute(TransformerFactoryImpl.FEATURE_OPTIMIZE,
+ Boolean.FALSE);
+}</pre>
+</blockquote>
+<a name="incremental">â</a>
+<p align="right" size="2">
+<a href="#content">(top)</a>
+</p>
+<h4>incremental attribute</h4>
+<p>
+<b>URI:</b> "http://xml.apache.org/xalan/features/incremental"</p>
+<p>Produce output incrementally, rather than waiting to finish parsing the input before generating any output. By default this attribute is set
+to false. You can turn this attribute on to transform large documents where the stylesheet structure is optimized to execute individual templates
+without having to parse the entire document. For more information, see <a href="dtm.html#incremental">DTM incremental</a>.</p>
+<p>To turn incremental transformations on, you can use the TransformerFactoryImpl.FEATURE_INCREMENTAL static variable (equivalent to the URI String above) as follows:</p>
+<blockquote class="source">
+<pre>import javax.xml.transform.TransformerFactory;
+import org.apache.xalan.processor.TransformerFactoryImpl;
+..
+TransformerFactory tFact = TransformerFactory.newInstance();
+if (tFact instanceof TransformerFactoryImpl) {
+ tFact.setAttribute(TransformerFactoryImpl.FEATURE_INCREMENTAL,
+ Boolean.FALSE);
+}</pre>
+</blockquote>
+<table class="note">
+<tr>
+<td class="noteImg">
+<img src="resources/note.gif" alt="note" />
+</td>
+<td class="noteTxt">The incremental feature is not currently supported by XSLTC.</td>
+</tr>
+</table>
+
+<a name="source_location">â</a>
+<p align="right" size="2">
+<a href="#content">(top)</a>
+</p>
+<h4>source_location attribute</h4>
+<p>
+<b>URI:</b> "http://xml.apache.org/xalan/properties/source-location"</p>
+<p>Provide a <a href="apidocs/javax/xml/transform/SourceLocator.html">SourceLocator</a> that can be used during a transformation
+to obtain the location of individual nodes in a source document (system ID, line number, and column number).</p>
+<p>By default, this attribute is set to false. Setting this attribute to true involves a substantial increase in storage cost per source
+document node. If you want to use the <a href="extensionslib.html#nodeinfo">NodeInfo</a> extension functions (or some other mechanism)
+to provide this information during a transform, you must set the attribute to true before generating the Transformer and processing the
+stylesheet.</p>
+<p>The <a href="commandline.html">command-line utility</a> -L flag sets this attribute to true. To set the source_location attribute
+programmatically, you can use the TransformerFactoryImpl.FEATURE_SOURCE_LOCATION static variable (equivalent to the URI String above)
+as follows:</p>
+<blockquote class="source">
+<pre>import javax.xml.transform.TransformerFactory;
+import org.apache.xalan.transformer.TransformerImpl;
+import org.apache.xalan.transformer.XalanProperties;
+..
+TransformerFactory tFact = TransformerFactory.newInstance();
+if (tFact instanceof TransformerFactoryImpl) {
+ tFact.setAttribute(TransformerFactoryImpl.FEATURE_SOURCE_LOCATION,
+ Boolean.TRUE);
+}</pre>
+</blockquote>
+
+
+<p align="right" size="2">
+<a href="#content">(top)</a>
+</p>
+</div>
+<div id="footer">Copyright © 1999-2014 The Apache Software Foundation<br />Apache, Xalan, and the Feather logo are trademarks of The Apache Software Foundation<div class="small">Web Page created on - Thu 2014-05-15</div>
+</div>
+</body>
+</html>
Propchange: xalan/java/branches/WebSite/xalan-j/features.html
------------------------------------------------------------------------------
svn:eol-style = native
Added: xalan/java/branches/WebSite/xalan-j/getstarted.html
URL: http://svn.apache.org/viewvc/xalan/java/branches/WebSite/xalan-j/getstarted.html?rev=1595253&view=auto
==============================================================================
--- xalan/java/branches/WebSite/xalan-j/getstarted.html (added)
+++ xalan/java/branches/WebSite/xalan-j/getstarted.html Fri May 16 16:11:33 2014
@@ -0,0 +1,308 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
+<html>
+<head>
+<title>ASF: Getting Started</title>
+<meta http-equiv="content-type" content="text/html; charset=UTF-8" />
+<meta http-equiv="Content-Style-Type" content="text/css" />
+<link rel="stylesheet" type="text/css" href="resources/apache-xalan.css" />
+</head>
+<!--
+ * Licensed to the Apache Software Foundation (ASF) under one
+ * or more contributor license agreements. See the NOTICE file
+ * distributed with this work for additional information
+ * regarding copyright ownership. The ASF licenses this file
+ * to you under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ -->
+<body>
+<div id="title">
+<table class="HdrTitle">
+<tbody>
+<tr>
+<th rowspan="2">
+<a href="../index.html">
+<img alt="Trademark Logo" src="resources/XalanJ-Logo-tm.png" width="190" height="90" />
+</a>
+</th>
+<th text-align="center" width="75%">
+<a href="index.html">Xalan XSL Transformer User's Guide</a>
+</th>
+</tr>
+<tr>
+<td valign="middle">Getting Started</td>
+</tr>
+</tbody>
+</table>
+<table class="HdrButtons" align="center" border="1">
+<tbody>
+<tr>
+<td>
+<a href="http://www.apache.org">Apache Foundation</a>
+</td>
+<td>
+<a href="http://xalan.apache.org">Xalan Project</a>
+</td>
+<td>
+<a href="http://xerces.apache.org">Xerces Project</a>
+</td>
+<td>
+<a href="http://www.w3.org/TR">Web Consortium</a>
+</td>
+<td>
+<a href="http://www.oasis-open.org/standards">Oasis Open</a>
+</td>
+</tr>
+</tbody>
+</table>
+</div>
+<div id="navLeft">
+<ul>
+<li>
+<a href="resources.html">Resources</a>
+<br />
+</li>
+<li>
+<a href="http://xalan.apache.org/index.html">Home</a>
+</li></ul><hr /><ul>
+<li>
+<a href="index.html">Xalan-J 2.7.2</a>
+</li>
+<li>
+<a href="charter.html">Charter</a>
+</li></ul><hr /><ul>
+<li>
+<a href="whatsnew.html">What's New</a>
+</li>
+<li>
+<a href="readme.html">Release Notes</a>
+</li></ul><hr /><ul>
+<li>
+<a href="overview.html">Overview</a>
+</li>
+<li>
+<a href="downloads.html">Download/Build</a>
+</li>
+<li>Getting Started<br />
+</li>
+<li>
+<a href="xsltc_usage.html">Using XSLTC</a>
+</li></ul><hr /><ul>
+<li>
+<a href="faq.html">FAQs</a>
+</li></ul><hr /><ul>
+<li>
+<a href="samples.html">Sample Apps</a>
+</li>
+<li>
+<a href="commandline.html">Command Line</a>
+</li></ul><hr /><ul>
+<li>
+<a href="features.html">Features</a>
+</li>
+<li>
+<a href="trax.html">Transform API</a>
+</li>
+<li>
+<a href="xpath_apis.html">XPath API</a>
+</li>
+<li>
+<a href="usagepatterns.html">Usage Patterns</a>
+</li></ul><hr /><ul>
+<li>
+<a href="apidocs/index.html">Xalan-J API</a>
+</li>
+<li>
+<a href="public_apis.html">Public APIs</a>
+</li>
+<li>
+<a href="dtm.html">DTM</a>
+</li></ul><hr /><ul>
+<li>
+<a href="extensions.html">Extensions</a>
+</li>
+<li>
+<a href="extensionslib.html">Extensions Library</a>
+</li>
+<li>
+<a href="extensions_xsltc.html">XSLTC Exts</a>
+</li></ul><hr /><ul>
+<li>
+<a href="design/design2_0_0.html">Xalan 2 Design</a>
+</li>
+<li>
+<a href="xsltc/index.html">XSLTC Design</a>
+</li></ul><hr /><ul>
+<li>
+<a href="builds.html">Building a release</a>
+</li>
+<li>
+<a href="http://xml.apache.org/xalan-j/test/overview.html">Testing</a>
+</li>
+<li>
+<a href="bugreporting.html">Bug Reporting</a>
+</li></ul><hr /><ul>
+<li>
+<a href="contact_us.html">Contact us</a>
+</li>
+</ul>
+</div>
+<div id="content">
+<h2>Getting Started</h2>
+<ul>
+ <li>
+<a href="#classpath">Setting up the system classpath</a>
+</li>
+ <li>
+<a href="#samples">Trying out the samples</a>
+</li>
+ <li>
+<a href="#commandline">Performing your own transformations from the command line</a>
+</li>
+ <li>
+<a href="#java-apps">Setting up your own XSLT applications</a>
+</li>
+</ul>
+<table class="note">
+<tr>
+<td class="noteImg">
+<img src="resources/note.gif" alt="note" />
+</td>
+<td class="noteTxt">Unless otherwise specified, the usage discussed in this section refers to
+the Xalan-Java Interpretive processor. See <a href="xsltc_usage.html">Getting Started with XSLTC
+</a> for information on using the Xalan-Java Compiling processor.</td>
+</tr>
+</table>
+<br />
+<a name="classpath">â</a>
+<p align="right" size="2">
+<a href="#content">(top)</a>
+</p>
+<h3>Setting up the system classpath</h3>
+ <p>At the very minimum, you must include <code>xalan.jar</code>, <code>serializer.jar</code>, <code>xml-apis.jar</code>,
+ and <code>xercesImpl.jar</code> -- or another conformant XML parser -- see <a href="usagepatterns.html#plug">Plugging in a Transformer and XML parser</a>) on the system classpath.
+ To run the Xalan-Java Interpretive processor sample applications, include <code>xalansamples.jar</code>
+ (all samples other than the servlet) and <code>xalanservlet.jar</code>. All these JAR files are
+ distributed with Xalan-Java. To run Javascript extensions, include <code>bsf.jar</code>, which can
+ be obtained from the <a href="http://jakarta.apache.org/bsf/index.html">Apache Jakarta
+ BSF project</a>. For extensions implemented in other scripting language, see
+ <a href="extensions.html#supported-lang"> extensions language requirements</a>
+ to identify any additional JAR files you must place on the classpath and where you can
+ get them.</p>
+
+ <p>If you are using XSLTC, see <a href="xsltc_usage.html">Getting Starting with XSLTC</a>.</p>
+
+ <p>If you are using JDK or JRE 1.3.x or 1.4.x, include <code>tools.jar</code> on the classpath. If you
+ are using JDK or JRE 1.1.8 (supported for runtime only), then include <code>classes.zip</code> on the
+ classpath.</p>
+
+
+<a name="samples">â</a>
+<p align="right" size="2">
+<a href="#content">(top)</a>
+</p>
+<h3>Trying out the samples</h3>
+ <p>The Xalan-Java distribution includes a number of basic sample applications. These samples are easy
+ to run, and you can review the source files -- all of which are brief -- to see just how they
+ work.</p>
+ <p>To run the samples, do the following:</p>
+ <ol>
+ <li>Set up your classpath (see above), including <code>xalansamples.jar</code> and (for the servlet)
+ <code>xalanservlet.jar</code>.</li>
+ <li>Be sure the java executable is on your path.</li>
+ <li>Go to the samples subdirectory containing the sample (use the DOS shell if you are running
+ Windows).</li>
+ <li>Use the java executable to run the sample from the command line.</li>
+ <li>Examine the application source and result files.</li>
+ </ol>
+ <p>For example, go to the SimpleTransform subdirectory and issue the following command:</p>
+ <p>
+<code>java SimpleTransform</code>
+</p>
+ <p>The sample writes the transformation result to a file (birds.out). To see how the example works,
+ examine the source files: birds.xml, birds.xsl, and SimpleTransform.java.</p>
+ <p>The extensions examples require additional JAR files on the classpath, and the procedure for
+ running the sample applet and sample servlet is different. For more information about all the
+ samples, see <a href="samples.html">Xalan-Java Samples</a>.</p>
+
+
+<a name="commandline">â</a>
+<p align="right" size="2">
+<a href="#content">(top)</a>
+</p>
+<h3>Performing your own transformations from the command line</h3>
+ <p>org.apache.xalan.xslt.Process provides a basic utility for performing transformations from
+ the command line. You can use this utility, for example, to run several of the extensions samples.
+ The command line for most standard transformations is as follows:</p>
+ <p>
+<code>java org.apache.xalan.xslt.Process -in <b>
+<i>xmlSource</i>
+</b>
+</code>
+<br />
+ <code>Â Â Â Â -xsl <b>
+<i>stylesheet</i>
+</b> -out <b>
+<i>outputfile</i>
+</b>
+</code>
+</p>
+ <p>where <b>
+<i>xmlSource</i>
+</b> is the XML source file name, <b>
+<i>stylesheet</i>
+</b> is the XSL
+ stylesheet file name, and <b>
+<i>outputfile</i>
+</b> is the output file name.</p>
+ <p>If you want the output to be displayed on the screen, simply omit the -out flag and argument.</p>
+ <p>You can use this utility to try out XSL stylesheets you have written, to make sure they do what
+ you expect with the XML source files they are designed to transform. The utility provides useful
+ messages if the source file or stylesheet is not well formed. For more information, see
+ <a href="commandline.html">Command-Line Utility</a>.</p>
+
+
+<a name="java-apps">â</a>
+<p align="right" size="2">
+<a href="#content">(top)</a>
+</p>
+<h3>Setting up your own Java applications</h3>
+ <p>You can start by using your own XML source files and XSL stylesheets with the sample applications,
+ which illustrate a number of the <a href="usagepatterns.html">basic usage patterns</a>.</p>
+ <p>Here is the basic procedure to keep in mind when you set up a transformation:</p>
+ <ol>
+ <li>Use the <a href="apidocs/javax/xml/transform/TransformerFactory.html">TransformerFactory</a> static newInstance() method to instantiate a TransformerFactory.<br />
+<br />
+</li>
+ <li>Use the TransformerFactory newTransformer(Source stylesheet) method to process the
+ transformation instructions in an XSLT stylesheet Source (producing under the covers a
+ <a href="apidocs/javax/xml/transform/Templates.html">Templates</a> object) and generate
+ a <a href="apidocs/javax/xml/transform/Transformer.html">Transformer</a>.<br />
+<br />
+</li>
+ <li>Use the Transformer transform(Source xmlSource, Result transformResult) method to apply the
+ transformation instructions (the Templates object) to the XML Source and produce the
+ transformation Result.<br />
+<br />
+</li>
+ </ol>
+ <p>For more information about this procedure and its variations, see <a href="usagepatterns.html">Basic
+ Usage Patterns</a>.</p>
+
+<p align="right" size="2">
+<a href="#content">(top)</a>
+</p>
+</div>
+<div id="footer">Copyright © 1999-2014 The Apache Software Foundation<br />Apache, Xalan, and the Feather logo are trademarks of The Apache Software Foundation<div class="small">Web Page created on - Thu 2014-05-15</div>
+</div>
+</body>
+</html>
Propchange: xalan/java/branches/WebSite/xalan-j/getstarted.html
------------------------------------------------------------------------------
svn:eol-style = native
---------------------------------------------------------------------
To unsubscribe, e-mail: commits-unsubscribe@xalan.apache.org
For additional commands, e-mail: commits-help@xalan.apache.org