You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@xalan.apache.org by dl...@locus.apache.org on 2000/09/15 21:03:23 UTC
cvs commit: xml-xalan/java/xdocs/sources/xalan BUGS DONE extensions.xml getstarted.xml index.xml overview.xml readme.xml resources.xml STATUS usagepatterns.xml
dleslie 00/09/15 12:03:22
Added: java/xdocs/sources/xalan BUGS DONE extensions.xml
getstarted.xml index.xml overview.xml readme.xml
resources.xml STATUS usagepatterns.xml
Log:
rellatively complete 1st draft for xalan-j 2.
Revision Changes Path
1.1 xml-xalan/java/xdocs/sources/xalan/BUGS
Index: BUGS
===================================================================
<s3 title="Open bugs and bug reporting">
<p>Open bugs:</p>
<p>Outstanding bugs are recorded in the Apache XML <jump href="http://xml.apache.org/bugs/">Bug Tracking System</jump>.
If you find a bug, please use this system to report it.</p>
<note>If the Apache XML Bug Tracking System is not working, please report the bug to the
<human-resource-ref idref="xalandev"/>.</note>
</s3>
1.1 xml-xalan/java/xdocs/sources/xalan/DONE
Index: DONE
===================================================================
<s3 title="Changes since &xslt4j; version 2.0.D01">
<p></p>
</s3>
1.1 xml-xalan/java/xdocs/sources/xalan/extensions.xml
Index: extensions.xml
===================================================================
<?xml version="1.0" standalone="no"?>
<!--
* Copyright (c) 1999 Lotus Development Corporation, Inc. All Rights Reserved.
* This software is provided without a warranty of any kind.
*
-->
<!DOCTYPE s1 SYSTEM "sbk:/style/dtd/document.dtd">
<s1 title="&xslt4j; Extensions">
<ul>
<li><link anchor="intro">Introduction</link></li>
<li><link anchor="supported-lang">Supported languages</link></li>
<li><link anchor="basic-pattern">The basic pattern</link></li>
<li><link anchor="setup-runtime">Setting up the runtime environment</link></li>
<li><link anchor="basic-syntax">Syntax</link></li>
<li><link anchor="ext-elements">Using an extension element</link></li>
<li><link anchor="ext-functions">Using extension functions</link></li>
<li><link anchor="java-namespace">Alternative: using the predefined java extension namespace</link></li>
<li>Examples: <link anchor="ex-basic">basic JavaScript example</link>, <link anchor="ex-redirect">the Redirect extension</link>, <link anchor="ex-java-namespace">using the java namespace</link>, <link anchor="ex-java">using a Java Hashtable</link>, <link anchor="ex-javascript">using a JavaScript array</link></li>
</ul><anchor name="intro"/>
<s2 title="Introduction">
<p>For those situations where you would like to augment the functionality of XSLT with calls to a procedural language, &xslt4j; supports the creation and use of extension elements and extension functions. An extension (a collection of elements and functions) inhabits a namespace, either a namespace you declare and designate as an extensions namespace, or the predefined java namespace that &xslt4j; provides. For information about XML namespaces, see <jump href="http://www.w3.org/TR/REC-xml-names/">Namespaces in XML</jump>.</p>
<p><em>Extension elements</em> Unlike a literal result element, which the stylesheet simply transfers to the result tree, an extension element performs an action. For example, you can use the Redirect extension elements shipped with &xslt4j; to redirect portions of your transformation output to one or more files. Extension elements may contain attributes, text nodes, other elements, basically any valid XML. Extension elements may perform quite sophisticated actions, given that the extension routine (the implementation) has direct access to the XSL processor context object and to the element. In many cases the implementation returns void or null; if it does return a value, that value is placed in the transformation result tree.</p>
<p><em>Extension functions</em>You can think of extension functions as extending the core library of functions that XPath provides. An extension function passes arguments to the extension implementation and returns a value. You can use extension functions to return values that XSLT can interact with directly (node-set, result tree fragment, string, boolean, and number) as well as values (of any type) that you pass in turn to other extension functions.</p>
</s2><anchor name="supported-lang"/>
<s2 title="Supported languages">
<p>&xslt4j; uses the <jump href="http://www.alphaworks.ibm.com/tech/bsf">Bean Scripting Framework (BSF)</jump>, an architecture for incorporating scripting into Java applications and applets. BSF allows an application to take advantage of scripting while being independent of any specific scripting language. To date, we have tested extensions implemented in Java and JavaScript. Other languages with BSF support appear in the table below.</p>
<p>BSF requires two JAR files on the class path: bsf.jar and bsfengines.jar. These two JAR files are shipped with &xslt4j;, and that is all that is required for Java extensions. The additional JAR files or DLLs required to support extensions in other languages are listed in the table below. These files are available from the sources indicated and are not shipped with &xslt4j;.</p>
<table>
<tr>
<td><em>Language</em></td>
<td><em>Version</em></td>
<td><em>Requirements</em></td>
</tr>
<tr>
<td>Mozilla Rhino<br/><br/></td>
<td>1.5<br/><br/></td>
<td>js.jar available from
http://www.mozilla.org/rhino<br/><br/></td>
</tr>
<tr>
<td>NetRexx<br/><br/></td>
<td>1.148 up <br/><br/></td>
<td>NetRexxC.zip available from http://www2.hursley.ibm.com/netrexx<br/><br/></td>
</tr>
<tr>
<td>BML<br/><br/></td>
<td>2.4<br/><br/></td>
<td>bmlall.jar available from http://www.alphaWorks.ibm.com/formula/bml<br/><br/></td>
</tr>
<tr>
<td>JPython<br/><br/></td>
<td>1.1-beta3<br/><br/></td>
<td>python.jar available from http://www.jpython.org/<br/><br/></td>
</tr>
<tr>
<td>Jacl<br/><br/></td>
<td>1.1.1<br/><br/></td>
<td> jacl.jar and tcljava.jar from http://www.scriptics.com/java<br/><br/></td>
</tr>
<tr>
<td>Win32 ActiveScript langs
JScript, VBScript<br/><br/></td>
<td><br/><br/></td>
<td>MSVCP60.DLL from Microsoft, appropriate language DLLs from Microsoft
http://msdn.microsoft.com/scripting<br/><br/></td>
</tr>
<tr>
<td>PerlScript<br/><br/></td>
<td><br/><br/></td>
<td>ActivePerl from http://www.activestate.com/<br/><br/></td>
</tr>
</table>
</s2><anchor name="basic-pattern"/>
<s2 title="The basic pattern">
<p>Let's examine a simple example. The stylesheet below uses an extension element and an extension function to transform an element in the XML source into a statement in the output indicating the date by which a customer can expect a response to a given enquiry.</p>
<p>The source element contains a numdays attribute. The extension element contains a multiplier attribute, which is used to set a variable in the extension. The extension function computes the deadline, that is the current date plus numdays * multiplier. So for <deadline numdays="3"/> (in the XML source) and <timelapse multiplier="2"/> (in the stylesheet), the extension computes a deadline 6 days from now, and the stylesheet template transform the deadline element into a string along the lines of <code><p>We have received your enquiry and will respond by April 29, 2000 12:07:16 PM EST.</p></code></p>
<note>The extension function could include both numdays and multiplier as arguments, thus bypassing the need for the extension element, but the purpose here is to illustrate the usage pattern for both extension elements and extension functions.</note>
<p>As you review this stylesheet, please note the following:</p>
<ol>
<li>The declaration of the Xalan lxslt namespace, which provides support for the component and
component/script elements:<br/><br/>
<code>xmlns:lxslt="http://xml.apache.org/xslt"</code><br/><br/></li>
<li>The declaration of a namespace for this extension:<br/><br/>
<code>xmlns:my-ext="ext1"</code><br/><br/></li>
<li>The designation of this namespace prefix as an extension prefix:<br/><br/>
<code>extension-element-prefixes="my-ext"</code><br/><br/></li>
<li>The lxslt:component with attributes designating the namespace prefix and the elements and
functions this extension provides.<br/><br/></li>
<li>The lxslt:script subelement with a JavaScript implementation of the extension. For Java
extensions, the lxslt:script element has a src attribute that you set to identify the Java class.</li>
</ol><anchor name="ex-basic"/>
<source><?xml version="1.0"?>
<!--Namespaces are global if you set them in the stylesheet element-->
<xsl:stylesheet
xmlns:xsl="http://www.w3.org/1999/XSL/Transform"
version="1.0"
xmlns:lxslt="http://xml.apache.org/xslt"
xmlns:my-ext="ext1"
extension-element-prefixes="my-ext">
<!--The component and its script are in the lxslt namespace and define the
implementation of the extension.-->
<lxslt:component prefix="my-ext" elements="timelapse" functions="getdate">
<lxslt:script lang="javascript">
var multiplier=1;
// The methods or functions that implement extension elements always take 2
// arguments. The first argument is the XSL Processor context; the second
// argument is the element node.
function timelapse(xslProcessorContext, elem)
{
multiplier=parseInt(elem.getAttribute("multiplier"));
// The element return value is placed in the result tree.
// If you do not want a return value, return null.
return null;
}
function getdate(numdays)
{
var d = new Date();
var totalDays = parseInt(numdays) * multiplier;
d.setDate(d.getDate() + totalDays);
return d.toLocaleString();
}
</lxslt:script>
</lxslt:component>
<xsl:template match="deadline">
<p><my-ext:timelapse multiplier="2"/>We have logged your enquiry and will
respond by <xsl:value-of select="my-ext:getdate(string(@numdays))"/>.</p>
</xsl:template>
</xsl:stylesheet>
</source>
</s2><anchor name="setup-runtime"/>
<s2 title="Setting up the runtime environment">
<p>To run the preceding example, bsf.jar, bsfengines.jar, and js.jar must be on the class path. Remember that bsf.jar and bsfengines.jar must be on the class path to run any extension. For extensions implemented in a scripting language, see the additional requirements in <link anchor="supported-lang">Supported languages</link>.</p>
</s2><anchor name="basic-syntax"/>
<s2 title="Syntax">
<p>You can always use the pattern illustrated above to set up and use extension elements and extension functions. For extension functions implemented in Java, you can also use the java namespace, described in <link anchor="java-namespace">Alternative: using the predefined java extension namespace</link>. Unless you are using the predefined java extension namespace, do the following:</p>
<s3 title="1. Declare the lxslt namespace">
<p><br/><code>xmlns:lxslt="http://xml.apache.org/xslt"</code></p>
<p>The lxslt namespace provides support for the lxslt:component element and lxslt:script subelement.</p>
<note>You may also use the LotusXSL alias for this namespace: "http://xsl.lotus.com/".</note>
</s3>
<s3 title="2. Declare a unique namespace for each extension prefix">
<p><br/><code>xmlns:<ref>prefix</ref>=<ref>URI</ref></code></p>
<p>The <ref>prefix</ref> identifies the namespace, and <ref>URI</ref> is one of the following:</p>
<ul>
<li>An arbitrary (but unique) string that matches the prefix attribute of an lxslt:component element in the stylesheet.<br/>
Example: <code>xmlns:ext1="xyz"</code><br/><br/></li>
<li><code>[class:]<ref>FQCN</ref></code><br/>
where <ref>FQCN</ref> is a Java fully qualified class name. If the extension only involves static class method
calls (no instance constructors or instance method calls) precede the class name with <code>class:</code>.<br/>
Example: <code>xmlns:ext2="java.util.Hashtable"</code><br/><br/></li>
<li>The file name or URL for another document that contains the lxslt:component element.<br/>
Example: <code>xmlns:ext3="my-component.txt"</code></li>
</ul>
<note>&xslt4j; identifies the URI by working through the list above. In other words, if the URI does not match an lxslt:component element prefix in the stylesheet, &xslt4j; attempts to map the URI to a fully qualified class name on the class path, and so on.</note>
<p>If the stylesheet contains an lxslt:component element with a prefix attribute set to the extension prefix, the only function of the URI is to provide a unique namespace. If the stylesheet does not contain an lxslt:component, the URI must identify a Java class or a document containing the lxslt:component.</p>
</s3>
<s3 title="3. Designate the extension prefixes">
<p>In the stylesheet element:</p>
<p><code>extension-element-prefixes="<ref>prefix-1 prefix-2 ...</ref>"</code></p>
<p>In a literal result element or extension element include the xsl prefix:</p>
<p><code>xsl:extension-element-prefixes="<ref>prefix1 prefix2 ...</ref>"</code></p>
<p>Keep in mind that where you declare namespaces and designate extension prefixes determines the scope of those namespaces.To make your extensions available throughout the stylesheet, include these settings and attribute in the stylesheet element.</p>
<p>By default, namespace declarations are included in the transformation output. To exclude namespaces from the output, use</p>
<p><code>exclude-result-prefixes="<ref>prefix-1 prefix-2 ...</ref>"</code></p>
<p>in the stylesheet element or</p>
<p><code>xsl:exclude-result-prefixes="<ref>prefix-1 prefix-2 ...</ref>"</code></p>
<p>in a literal result element or extension element.</p>
</s3>
<s3 title="4. Set up an lxslt:component">
<p>In the scope of the xslt namespace declaration:</p>
<p><code><lxslt:component prefix="<ref>prefix</ref>" </code><br/>
<code> functions="<ref>func-1 func-2 ...func-n</ref>"</code><br/>
<code> elements="<ref>elem-1 elem-2 ...elem-n</ref>"></code><br/>
<code> <!--See lxslt:script below--></code><br/>
<code></lxslt:component></code></p>
<p>where <ref>func-1 func-2 ... func-n</ref> and <ref>elem-1 elem-2 ... elem-n</ref> designate the functions and elements the extension provides and the stylesheet uses. You can use the function-available and element-available functions to determine at run time whether a function or element designated in the lxslt:component is actually available.</p>
<note>If your extension namespace is a fully qualified class name, you do not need to include the lxslt:component. If you do not include it, you cannot use the function-available and element-available functions to determine whether a given element or function is actually available at runtime.</note>
</s3>
<s3 title="5. Set up the lxslt:script element">
<p>In each lxslt:component, you must include an lxslt:script element. If the extension is implemented in Java:</p>
<p><code><lxslt:script lang="javaclass" src="<ref>[class:]FQCN</ref>"/></code></p>
<p>where <ref>FQCN</ref> is the fully qualified class name. If the extension only involves static class method calls (no instance constructors or instance method calls) precede the class name with <code>class:</code>.<br/>
Example: <code><lxslt:script lang="javaclass"</code><br/>
<code> src="java.util.Hashtable"/></code></p>
<p>If the extension is implemented in JavaScript:</p>
<p><code><lxslt:script lang="javascript" ></code><br/>
<code> <!--The implementation script--></code><br/>
<code></lxslt:script></code></p>
<p>For other scripting languages supported by BSF, use the same approach as for JavaScript. &xslt4j; plans to add support for using the src attribute to identify another document that contains the implementation script; this feature is not yet supported.</p>
</s3>
<s3 title="Implicit DTD for lxslt:component">
<source><!ELEMENT lxslt:component (lxslt:script)>
<!ATTLIST lxslt:component
prefix CDATA #IMPLIED
namespace-uri CDATA #IMPLIED
elements NMTOKENS #REQUIRED
functions NMTOKENS #REQUIRED>
<!ELEMENT lxslt:script EMPTY)>
<!ATTLIST lxslt:script
lang CDATA #REQUIRED
src CDATA #IMPLIED></source>
</s3>
</s2><anchor name="ext-elements"/>
<s2 title="Using an extension element">
<p>Extension elements pass the extension two objects:</p>
<ul>
<li><jump href="apidocs/org/apache/xalan/extensions/XSLProcessorContext.html">org.apache.xalan.extensions.XSLProcessorContext</jump>, which provides access to the XSL processor, the XML source tree, the stylesheet tree, the current context node, and the current mode (if any).<br/><br/></li>
<li>org.w3c.dom.Element, which provides the API for interacting with the extension element.</li>
</ul>
<p>You can use the Element getAttribute(String name) method, for example, to read element attributes.</p>
<s3 title="Implementing an extension element">
<p>For each extension element in a namespace, the implementation must be a Java method with the following signature, or the scripting language equivalent:</p>
<p><code><ref>Type element</ref>(org.apache.xalan.extensions.XSLProcessorContext, </code><br/>
<code> org.w3c.dom.Element extensionElement)</code></p>
<p>where <ref>Type</ref> designates the return type and <ref>element</ref> is the local part of the extension element name (the element name without the namespace prefix).</p>
<p>If the extension element is implemented in a loosely typed scripting language, such as JavaScript, the arguments and return value are untyped.</p>
<p><em>Caution:</em> The value returned by an extension element is placed in the transformation result. If you are not interested in a return value, use a public void Java method or return null from a scripting language function.</p>
<p>Java example: <code>public void myElement</code><br/>
<code> (org.apache.xalan.xslt.XSLProcessorContext, </code><br/>
<code> org.w3c.dom.Element extensionElement)</code></p>
<p>JavaScript example: <code>function myElement(xslProcContext, element)</code></p>
</s3>
<s3 title="The Redirect extension">
<p>The Redirect extension (<jump href = "apidocs/org/apache/xalan/xslt/extensions/Redirect.html">org.apache.xalan.xslt.extensions.Redirect</jump>) is shipped with &xslt4j; (more extensions are on the way!).</p>
<p>A standard XSL transformation involves three parameters: the XML source tree, an XSL stylesheet, and the transformation result tree. Whether the result tree is output to a file, a character stream, a byte stream, a DOM, or a SAX document handler, the initial transformation sends the entire result to a single target, represented by the <resource-ref idref="XSLTResultTargetDoc"/>.</p>
<p>The Redirect extension supplies three extension elements that you can use to redirect portions of your transformation output to multiple files: <open>, <write>, and <close>. If you use the <write> element alone, the extension opens a file, writes to it, and closes the file immediately. If you want explicit control over the opening and closing of files, use <write> in conjunction with the <open> and <close> elements.</p>
<p>Each of these elements includes a file attribute and/or a select attribute to designate the output file. The file attribute takes a string, so you can use it to directly specify the output file name; The select attribute takes an XPath expression, so you can use it to dynamically generate the output file name. If you include both attributes, the Redirect extension first evaluates the select attribute, and falls back to the file attribute if the select attribute expression does not return a valid file name.</p>
</s3><anchor name="ex-redirect"/>
<s3 title="Example with the Redirect extension">
<p>Suppose you are outputting the bulk of your result tree to one file, but you want to output the transformation of all <foo> elements and their children to another file. The following example illustrates the basic structure of the XML source:</p>
<source><?xml version="1.0"?>
<doc>
<foo file="foo.out">
Testing Redirect extension:
<bar>A foo subelement text node</bar>
</foo>
<main>
Everything else
</main>
</doc></source>
<p>This stylesheet redirects part of the output to a secondary file:</p>
<source>
<xsl:stylesheet xmlns:xsl="http://www.w3.org/1999/XSL/Transform"
version="1.0"
xmlns:lxslt="http://xml.apache.org/xslt"
xmlns:redirect="org.apache.xalan.xslt.extensions.Redirect"
extension-element-prefixes="redirect">
<xsl:template match="/">
<standard-out>
Standard output:
<xsl:apply-templates/>
</standard-out>
</xsl:template>
<xsl:template match="main">
<main>
<xsl:apply-templates/>
</main>
</xsl:template>
<xsl:template match="/doc/foo">
<redirect:write select="@file">
<foo-out>
<xsl:apply-templates/>
</foo-out>
</redirect:write>
</xsl:template>
<xsl:template match="bar">
<foobar-out>
<xsl:apply-templates/>
</foobar-out>
</xsl:template>
</xsl:stylesheet></source>
<p>The standard output is:</p>
<source><?xml version="1.0" encoding="UTF-8"?>
<standard-out>
Standard output:
<main>
Everything else.
</main>
<standard-out></source>
<p>The output redirected to foo.out is:</p>
<source><?xml version="1.0" encoding="UTF-8"?>
<foo-out>
Testing Redirect extension:
<foobar-out>foo subelement text node</foobar-out>
</foo-out></source>
<p>For more information on using the Redirect extension to send output to multiple files, see <resource-ref idref="RedirectDoc"/>.</p>
</s3>
</s2><anchor name="ext-functions"/>
<s2 title="Using extension functions">
<p>Extension functions may include arguments of any type and return a value of any type.</p>
<p>XSLT recognizes five data types: node-set, result-tree-fragment, string, boolean, and number. You can use XPath expressions to set variables with values of these types. You can also pass literals for string, boolean, and number arguments. If you want to pass an argument of a type that XSLT does not recognize, use another extension function to return an object of that type. The stylesheet that appears in <link anchor="format-date-stylesheet">Formatting a date</link>, for example uses extension functions to return a Date object and a SimpleDateFormat object, and then uses these objects to call another extension function.</p>
<s3 title="Data type mapping">
<p>The XSLT data types map to Java data types as follows:</p>
<table>
<tr>
<th>XSLT Type</th>
<th>Java Type</th>
</tr>
<tr>
<td>Node-Set</td>
<td>org.w3c.dom.NodeList</td>
</tr>
<tr>
<td>String</td>
<td>java.lang.String</td>
</tr>
<tr>
<td>Boolean</td>
<td>boolean or Boolean</td>
</tr>
<tr>
<td>Number</td>
<td>double or Double</td>
</tr>
<tr>
<td>Result Tree Fragment</td>
<td>org.w3c.dom.DocumentFragment</td>
</tr>
</table>
<p>For the XSLT boolean and number types, &xslt4j; first looks for a method with the corresponding Java primitive type. If it does not find such a method, it looks for a method with the object type. In the case of the foo:bar(10) static method call, for example, &xslt4j; first looks for bar(double). If it does not find such a method, it looks for for bar(java.lang.Double).</p>
<p>When an extension function is invoked, the arguments are converted as indicated above, and sent to the extension. No conversion takes place for arguments of non-XSLT types.</p>
<anchor name="ext-func-calls"/>
</s3>
<s3 title="Extension function Java calls">
<p>Use the following syntax to instantiate Java objects and to call methods:</p>
<p><code><ref>prefix</ref>:<ref>FQCN</ref>.new (<ref>args</ref>)</code></p>
<p>where <ref>prefix</ref> is the extension namespace prefix and <ref>FQCN</ref> is the fully qualified class name of which a new instance is to be created with the <ref>args</ref> constructor arguments (if any).<br/>
Example: <code>variable myHash</code><br/>
<code> select"my-ext:java.util.Hashtable.new()"</code></p>
<p><code><ref>prefix</ref>:<ref>FQCN.methodName</ref> (<ref>args</ref>)</code></p>
<p>where <ref>FQCN</ref> is the fully qualified class name whose static method <ref>methodName</ref> is to be invoked using the <ref>args</ref> arguments.<br/>
Example: <code>variable new-pop</code><br/>
<code> select="my-ext:java.lang.Integer.valueOf(string(@population))"</code></p>
<p><code><ref>prefix</ref>:<ref>methodName</ref> (<ref>object</ref>, <ref>args</ref>)</code></p>
<p>where <ref>methodName</ref> is the name of the method to invoke on <ref>object</ref> with the <ref>args</ref> arguments.<br/>
Example: <code>variable old-pop </code><br/>
<code> select="my-ext:put($myHash, string(@region), $new-pop)"</code></p>
</s3>
<s3 title="Passing Nodes to java">
<p>Please keep in mind that <em>all</em> LocationPath expressions return a node-set, even if the expression only returns a single attribute or a text node (node-sets with one member). You can use the XSLT string() function (as in the syntax examples above) to convert a node-set value to string, and the number() function to convert a node-set value to number (a double).</p>
<p>If you want to pass a node-set to an extension function, set up a Java method to accept an
org.w3c.dom.NodeList (or an org.apache.xalan.xpath.MutableNodeList, which extends NodeList, if you want to modify the nodes).</p>
<p>Suppose, for example, you have a myExtensions.ProcessNodes class with the following doSomething method:</p>
<p><code>public static boolean doSomething(org.w3c.dom.NodeList nList)</code></p>
<p>Assuming you set up this extension in the node-ext namespace, any of the following extension calls from a stylesheet are syntactically possible:</p>
<p><code><!--Process the current node--></code><br/>
<code><xsl:variable name="success" select="node-ext:MyExtensions.ProcessNodes.doSomething(.)"/></code></p>
<p><code><!--Process all nodes in current context--></code><br/>
<code><xsl:variable name="success" select="node-ext:MyExtensions.ProcessNodes.doSomething(*)"/></code></p>
<p><code><!-- Process all nodes --></code><br/>
<code><xsl:variable name="success" select="node-ext:MyExtensions.ProcessNodes.doSomething(/*)"/></code></p>
<p><code><!--Process the foo/baz nodes in current context --></code><br/>
<code><xsl:variable name="success" select="node-ext:MyExtensions.ProcessNodes.doSomething(foo/baz)"/></code></p>
<p><code><!--Process the/foo/baz and /bar/saz nodes --></code><br/>
<code><xsl:variable name="success" select="node-ext:MyExtensions.ProcessNodes.doSomething(/foo/baz | /bar/saz)"/></code></p>
<p>The NodeList is in fact a list of references into the XML document, so keep in mind that getNextSibling(), for example, gets you the next sibling in the document, which may not be the next Node in the NodeList.</p>
</s3>
<s3 title="Implementing extension functions">
<p>For each extension function in a namespace, the implementation must include a Java method with the following signature, or the scripting language equivalent:</p>
<p><code>public <ref> object function</ref>(<ref>args</ref>)</code></p>
<p>where <ref>object</ref> is the return type, <ref>function</ref> is the local part of the extension function name (the function name without the namespace prefix), and <ref>args</ref> correspond to the arguments in the function call.</p>
</s3>
</s2><anchor name="java-namespace"/>
<s2 title="Alternative: using the predefined java extension namespace">
<p>For extension functions implemented in Java, Xalan provides a java namespace. When you declare and use the java namespace, you do not use an lxslt:component to designate the functions.</p>
<p>The java namespace supports the use of extension functions implemented in Java. You cannot use this syntax with extension elements or with extensions implemented in JavaScript or another scripting language.</p>
<s3 title="Declare the Xalan java namespace">
<p><code>xmlns:lxslt="http://xml.apache.org/xslt/java"</code></p>
<note>You may also use the LotusXSL alias for this namespace: "http://xsl.lotus.com/java".</note>
</s3>
<s3 title="Use the java namespace when you make extension function calls">
<p>Use "java" as the prefix with the syntax described in <link anchor="ext-func-calls">Extension function Java calls</link>.</p>
<p>That is all. You do not need to set an extension-element-prefixes attribute, and you do not include an lxslt:component element. Given the absence of the lxslt:component element, you cannot use the function-available method to determine at runtime whether a Java method call is actually available. </p>
<p>Using the java namespace clearly involves less setup than using your own namespace, as long as these restrictions are not a problem. Remember that you always have the option of setting up your own namespace and extra overhead is really minimal.</p>
</s3><anchor name="ex-java-namespace"/>
<s3 title="Example: Formatting a date">
<p>This example uses extension functions to call the SimpleDateFormat class and the IntDate class. IntDate uses String arguments to set up a Date object:</p>
<source>import java.util.Date;
import java.util.Calendar;
public class IntDate
{
public static Date getDate(String year, String month, String day)
{
// Date(int, int, int) has been deprecated, so use Calendar to
// set the year, month, and day.
Calendar c = Calendar.getInstance();
// Convert each argument to int.
c.set(Integer.parseInt(year),Integer.parseInt(month),Integer.parseInt(day));
return c.getTime();
}
}</source>
<p>The template transforms date elements with four attributes. For example, it transforms <code><date format="EEEE, MMM dd, yyyy" year="2000" month="4" day="27"/></code> into <p>Date: Thursday, April 27, 2000.</p>.</p>
<p>As you review this stylesheet, please keep the following in mind:</p>
<ul>
<li>The exclude-result-prefixes stylesheet attribute prevents the java namespace declaration from
appearing in the output.</li>
<li>The XSLT type returned by any LocationPath expression is node-set, so the XSLT string
function is used to convert the format, year, month, and day attribute values from node-sets to
strings.</li>
<li>The format attribute provides a String argument for constructing a java.text.SimpleDateFormat
object.</li>
<li>The IntDate class uses String values provided by the year, month, and day attributes, to set the
date. XSLT can pass number values, but these are converted into doubles.</li>
<li>The formatter variable holds a SimpleDateFormat object, and the date variable holds a Date object.
XSLT does not understand either of these types, but they are used to call the SimpleDateFormat format
method. In that call, $formatter is the object, and $date is the argument. The syntax for calling
Java constructors and methods is described above in <link anchor="ext-func-calls">Extension function Java calls</link>.</li>
</ul><anchor name="format-date-stylesheet"/>
<source><?xml version="1.0"?>
<xsl:stylesheet
xmlns:xsl="http://www.w3.org/1999/XSL/Transform"
version="1.0"
xmlns:java="http://xml.apache.org/xslt/java"
exclude-result-prefixes="java">
<!--Other templates for transforming the rest of the XML source documents-->
<xsl:template match="date">
<xsl:variable name="year" select="string(./@year)"/>
<xsl:variable name="month" select="string(./@month)"/>
<xsl:variable name="day" select="string(./@day)"/>
<xsl:variable name="format" select="string(./@format)"/>
<xsl:variable name="formatter"
select="java:java.text.SimpleDateFormat.new($format)"/>
<xsl:variable name="date"
select="java:IntDate.getDate($year, $month, $day)"/>
<p>Date: <xsl:value-of select="java:format($formatter, $date)"/></p>
</xsl:template>
</xsl:stylesheet>
</source>
</s3>
</s2>
<s2 title="Examples: using Java and JavaScript to implement the same extension">
<p>This section contains two examples. The first example uses a Java extension to transform a set of name elements into an alphabetical and numbered list. The second example uses a JavaScript script to do the same. Both examples include equivalent extension elements and an extension function.</p>
<anchor name="ex-java"/>
<s3 title="Java implementation">
<p>MyCounter.java</p>
<source>Import java.util.*;
public class MyCounter {
Hashtable counters = new Hashtable ();
public MyCounter ()
{}
public void init(org.apache.xalan.extensions.XSLProcessorContext context,
org.apache.xalan.xslt.ElemExtensionCall extElem)
{
String name = extElem.getAttribute("name");
String value = extElem.getAttribute("value");
int val;
try
{
val = Integer.parseInt (value);
}
catch (NumberFormatException e)
{
e.printStackTrace ();
val = 0;
}
counters.put (name, new Integer (val));
}
public int read(String name)
{
Integer cval = (Integer) counters.get (name);
return (cval == null) ? 0 : cval.intValue ();
}
public void incr(org.apache.xalan.extensions.XSLProcessorContext context,
org.apache.xalan.xslt.ElemExtensionCall extElem) {
String name = extElem.getAttribute("name");
Integer cval = (Integer) counters.get(name);
int nval = (cval == null) ? 0 : (cval.intValue () + 1);
counters.put (name, new Integer (nval));
}
}
</source>
<p>An XML source document:</p>
<source><?xml version="1.0"?>
<doc>
<name first="David" last="Marston"/>
<name first="David" last="Bertoni"/>
<name first="Donald" last="Leslie"/>
<name first="Emily" last="Farmer"/>
<name first="Jack" last="Donohue"/>
<name first="Myriam" last="Midy"/>
<name first="Paul" last="Dick"/>
<name first="Robert" last="Weir"/>
<name first="Scott" last="Boag"/>
<name first="Shane" last="Curcuru"/>
</doc></source>
<p>The stylesheet:</p>
<source><?xml version="1.0"?>
<xsl:stylesheet xmlns:xsl="http://www.w3.org/1999/XSL/Transform"
xmlns:lxslt="http://xml.apache.org/xslt"
xmlns:counter="MyCounter"
extension-element-prefixes="counter"
version="1.0">
<lxslt:component prefix="counter"
elements="init incr" functions="read">
<lxslt:script lang="javaclass" src="MyCounter"/>
</lxslt:component>
<xsl:template match="/">
<HTML>
<H1>Names in alphabetical order</H1>
<counter:init name="index" value="1"/>
<xsl:for-each select="doc/name">
<xsl:sort select="@last"/>
<xsl:sort select="@first"/>
<p>
<xsl:text>[</xsl:text>
<xsl:value-of select="counter:read('index')"/>
<xsl:text>]. </xsl:text>
<xsl:value-of select="@last"/>
<xsl:text>, </xsl:text>
<xsl:value-of select="@first"/>
</p>
<counter:incr name="index"/>
</xsl:for-each>
</HTML>
</xsl:template>
</xsl:stylesheet>
</source>
<p>Transformation output:</p>
<source><HTML>
<H1>Names in alphabetical order</H1>
<p>[1]. Bertoni, David</p>
<p>[2]. Boag, Scott</p>
<p>[3]. Curcuru, Shane</p>
<p>[4]. Dick, Paul</p>
<p>[5]. Donohue, Jack</p>
<p>[6]. Farmer, Emily</p>
<p>[7]. Leslie, Donald</p>
<p>[8]. Marston, David</p>
<p>[9]. Midy, Myriam</p>
<p>[10]. Weir, Robert</p>
</HTML></source>
</s3><anchor name="ex-javascript"/>
<s3 title="JavaScript implementation">
<p></p>
<source><?xml version="1.0"?>
<xsl:stylesheet xmlns:xsl="http://www.w3.org/1999/XSL/Transform"
xmlns:lxslt="http://xml.apache.org/xslt"
xmlns:counter="MyCounter"
extension-element-prefixes="counter"
version="1.0">
<lxslt:component prefix="counter"
elements="init incr" functions="read">
<lxslt:script lang="javascript">
var counters = new Array();
function init (xslproc, elem) {
name = elem.getAttribute ("name");
value = parseInt(elem.getAttribute ("value"));
counters[name] = value;
return null;
}
function read (name) {
// Return a string.
return "" + (counters[name]);
}
function incr (xslproc, elem)
{
name = elem.getAttribute ("name");
counters[name]++;
return null;
}
</lxslt:script>
</lxslt:component>
<xsl:template match="/">
<HTML>
<H1>Names in alphatebical order</H1>
<counter:init name="index" value="1"/>
<xsl:for-each select="doc/name">
<xsl:sort select="@last"/>
<xsl:sort select="@first"/>
<p>
<xsl:text>[</xsl:text>
<xsl:value-of select="counter:read('index')"/>
<xsl:text>]. </xsl:text>
<xsl:value-of select="@last"/>
<xsl:text>, </xsl:text>
<xsl:value-of select="@first"/>
</p>
<counter:incr name="index"/>
</xsl:for-each>
</HTML>
</xsl:template>
</xsl:stylesheet>
</source>
<p>This stylesheet produces the same output as the preceding example with the Java extension.</p>
</s3>
</s2>
</s1>
1.1 xml-xalan/java/xdocs/sources/xalan/getstarted.xml
Index: getstarted.xml
===================================================================
<?xml version="1.0" standalone="no"?>
<!DOCTYPE s1 SYSTEM "sbk:/style/dtd/document.dtd">
<s1 title="Getting Started">
<ul>
<li><link anchor="download">Downloading what you need</link></li>
<li><link anchor="classpath">Setting up the system class path</link></li>
<li><link anchor="samples">Trying out the samples</link></li>
<li><link anchor="commandline">Performing your own transformations from the command line</link></li>
<li><link anchor="java-apps">Setting up your own XSLT applications</link></li>
</ul>
<anchor name="download"/>
<s2 title="Downloading what you need">
<p>To use Xalan, you need the following:</p>
<ul>
<li>The JDK or JRE 1.1.8 or 1.2.2</li>
<li>xalan.jar</li>
<li>xerces.jar</li>
</ul>
<p>You can get the JDK or JRE from <jump href="http://www.ibm.com/java/jdk">ibm.com/java/jdk/</jump> or <jump href="http://www.java.sun.com">java.sun.com</jump>.</p>
<p>Download <resource-ref idref="xslt4j-dist-zip"/> or <resource-ref idref="xslt4j-dist-targz"/>. Both of these files contain <resource-ref idref="xslt4j-current"/> (with xalan.jar) and xerces.jar from <resource-ref idref="xml4j-used"/>. You can use a zip or tar utility to expand these files into a full build.</p>
<p>If you plan to run <link idref="extensions">XSLT extensions</link>, you need bsf.jar and bsfengines.jar, both of which are included in the &xslt4j; distribution. If you plan to run XSLT extensions implemented in JavaScript or another scripting language, you will need one or more additional files as indicated in <link idref="extensions" anchor="supported-lang">extensions language requirements</link>.</p>
</s2><anchor name="classpath"/>
<s2 title="Setting up the system class path">
<p>At the very minimum, you must include xalan.jar and xerces.jar on the system class path. To run the sample applications, include xalansamples.jar (all samples other than the servlet) and xalanservlet.jar. To run extensions, include bsf.jar and bsfengines.jar. All these JAR files are distributed with &xslt4j;. For extensions implemented in JavaScript or another scripting language, see <link idref="extensions" anchor="supported-lang">extensions language requirements</link> to identify any additional JAR files you must place on the class path and where you can get them.</p>
<p>If you are using JDK or JRE 1.1.8, also include classes.zip on the class path.</p>
</s2><anchor name="samples"/>
<s2 title="Trying out the samples">
<p>The &xslt4j; 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 class path (see above), including xalansamples.jar and (for the servlet) xalanservlet.jar.</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 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 (foo.out). To see how the example works, examine the source files: foo.xml, foo.xsl, and SimpleTransform.java.</p>
<p>The extensions examples require additional JAR files on the class path, and the procedure for running the sample applet and sample servlet is different. For more information about all the samples, see <link idref="samples">&xslt4j; Samples</link>.</p>
</s2><anchor name="commandline"/>
<s2 title="Performing your own transformations from the command line">
<p>java.org.apache.xalan.xslt.Process provides a basic utility for performing transformations from the command line. You use this utility, for example, to run the extensions samples. The command line for most standard transformations is as follows:</p>
<p><code>java org.apache.xalan.xslt.Process -in <ref>xmlSource</ref></code><br/>
<code> -xsl <ref>stylesheet</ref> -out <ref>outputfile</ref></code></p>
<p>where <ref>xmlSource</ref> is the XML source file name, <ref>stylesheet</ref> is the XSL stylesheet file name, and <ref>outputfile</ref> 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. If you include a DOCTYPE statement in your XML source files and include the -validate flag on the command line, the utility will also let you know whether the XML document is valid (conforms to that DOCTYPE). For more information, see <link idref="commandline">Command-Line Utility</link>.</p>
</s2><anchor name="java-apps"/>
<s2 title="Setting up your own Java applications">
<p>You can start by using your own XML source files and XSL stylesheets with the sample applications, which illustrate a number of the <link idref="usagepatterns">basic usage patterns</link>.</p>
<p>Here is the basic TRaX procedure to keep in mind when you set up a transformation:</p>
<ol>
<li>Use trax.Processor.newInstance("xslt") to instantiate a stylesheet processor -- a TRaX <jump href="apidocs/trax/Processor.html">Processor</jump> object implemented by the Xalan <jump href="apidocs/org/apache/xalan/processor/StylesheetProcessor.html">StylesheetProcessor</jump>.<br/><br/></li>
<li>Use the Processor process() or processFromNode() method to process the stylesheet (a SAX InputSource or DOM Node) and generate a Templates object -- a TRaX <jump href="apidocs/trax/Templates.html">Templates</jump> object implemented by the Xalan <jump href="apidocs/org/apache/xalan/processor/StylesheetRoot.html">StylesheetRoot</jump><br/><br/></li>
<li>Use the Templates newTransformer() method to instantiate a Transformer -- a TRaX
<jump href="apidocs/trax/Transformer.html">Transformer</jump> object implemented by the Xalan <jump href="apidocs/org/apache/xalan/transformer/TransformerImpl.html">TransformerImpl</jump>.<br/><br/></li>
<li>Use one of the Transformer transform() or transformNode() methods to apply the Templates object to an XML document (a SAX InputSource or DOM Node) and perform the transformation, placing the output in a TRaX <jump href="apidocs/trax/Result.html">Result</jump> object.</li>
</ol>
<p>For more information about this procedure and its variations, see <link idref="usagepatterns">Basic Usage Patterns</link>.</p>
</s2>
</s1>
1.1 xml-xalan/java/xdocs/sources/xalan/index.xml
Index: index.xml
===================================================================
<?xml version="1.0" standalone="no"?>
<!DOCTYPE s1 SYSTEM "sbk:/style/dtd/document.dtd">
<!--
* The Apache Software License, Version 1.1
*
*
* Copyright (c) 1999 The Apache Software Foundation. All rights
* reserved.
*
* Redistribution and use in source and binary forms, with or without
* modification, are permitted provided that the following conditions
* are met:
*
* 1. Redistributions of source code must retain the above copyright
* notice, this list of conditions and the following disclaimer.
*
* 2. Redistributions in binary form must reproduce the above copyright
* notice, this list of conditions and the following disclaimer in
* the documentation and/or other materials provided with the
* distribution.
*
* 3. The end-user documentation included with the redistribution,
* if any, must include the following acknowledgment:
* "This product includes software developed by the
* Apache Software Foundation (http://www.apache.org/)."
* Alternately, this acknowledgment may appear in the software itself,
* if and wherever such third-party acknowledgments normally appear.
*
* 4. The names "Xalan" and "Apache Software Foundation" must
* not be used to endorse or promote products derived from this
* software without prior written permission. For written
* permission, please contact apache@apache.org.
*
* 5. Products derived from this software may not be called "Apache",
* nor may "Apache" appear in their name, without prior written
* permission of the Apache Software Foundation.
*
* THIS SOFTWARE IS PROVIDED ``AS IS'' AND ANY EXPRESSED OR IMPLIED
* WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
* OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
* DISCLAIMED. IN NO EVENT SHALL THE APACHE SOFTWARE FOUNDATION OR
* ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
* SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
* LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF
* USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND
* ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
* OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT
* OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
* SUCH DAMAGE.
* ====================================================================
*
* This software consists of voluntary contributions made by many
* individuals on behalf of the Apache Software Foundation and was
* originally based on software copyright (c) 1999, Lotus
* Development Corporation., http://www.lotus.com. For more
* information on the Apache Software Foundation, please see
* <http://www.apache.org/>.
-->
<s1 title="&xslt4j-current;">
<s2 title="What is it?">
<p>Xalan is an XSLT processor for transforming XML documents into HTML, text, or other XML document types. It implements the
W3C Recommendations for XSL Transformations (XSLT) and the XML Path Language (XPath). It can be used from the command line,
in an applet or a servlet, or as a module in other program.</p>
</s2>
<s2 title="I've heard of &xslt4j;, but what is version 2?">
<p>&xslt4j; version 2 recasts Xalan as an implementation of the <resource-ref idref="trax"/> interfaces. TRaX provides a
modular framework and a standard API for performing an open-ended range of XML transformations.</p>
<p>In conjunction with TRaX, &xslt4j2; relies on system properties to configure its operational settings, such as
which stylesheet processor, which SAX parser, and which serializers to use. The default settings point to the Xalan
StylesheetProcessor, the Xerces SAXParser, and the serializers shipped with Xerces.</p>
<p>&xslt4j; version 2 also builds on <resource-ref idref="sax2"/>, <resource-ref idref="dom2"/>, and the
<resource-ref idref="jaxp"/>.</p>
<p>For more information, see <link idref="whatsnew">What's new in &xslt4j2;</link>.</p>
</s2>
<s2 title="How about this release?">
<p>&xslt4j-current; is the first release of &xslt4j2;. It is an alpha Develper's release. For information about known
limitations and problems, see the <link idref="readme">Release notes</link>. Please send your comments, bug reports, and
feeback to the <human-resource-ref idref="xalandev"/></p>
</s2>
<s2 title="How do I get it?">
<p>Download and unzip either of the following:</p>
<ul>
<li><resource-ref idref="xslt4j-dist-zip"/></li>
<li><resource-ref idref="xslt4j-dist-targz"/></li>
</ul>
</s2>
<s2 title="Where do I get Xerces?">
<p>The Xalan download includes xerces.jar from &xml4j-used;. This is all you need to run Xalan.
You can, however, download the complete Xerces distribution from the <resource-ref idref="xml4j-distdir"/>.</p>
</s2>
<s2 title="What else do I need?">
<p>You need the Java Development Kit or Java Runtime 1.1.8 or 1.2.2, which you can obtain from <jump
href="http://www.ibm.com/java/jdk">ibm.com/java/jdk/</jump> or <jump href="http://www.java.sun.com">java.sun.com</jump>.</p>
</s2>
<s2 title="For more information...">
<p>For more information, go to <link idref="overview">Xalan Overview</link> and <link idref="getstarted">Getting
Started</link>. All of the Xalan documentation on this website is included in the Xalan download, as are a number of samples
to help you start using &xslt4j2; to transform XML documents.</p>
</s2>
</s1>
1.1 xml-xalan/java/xdocs/sources/xalan/overview.xml
Index: overview.xml
===================================================================
<?xml version="1.0" standalone="no"?>
<!DOCTYPE s1 SYSTEM "sbk:/style/dtd/document.dtd">
<!--
* The Apache Software License, Version 1.1
*
*
* Copyright (c) 1999 The Apache Software Foundation. All rights
* reserved.
*
* Redistribution and use in source and binary forms, with or without
* modification, are permitted provided that the following conditions
* are met:
*
* 1. Redistributions of source code must retain the above copyright
* notice, this list of conditions and the following disclaimer.
*
* 2. Redistributions in binary form must reproduce the above copyright
* notice, this list of conditions and the following disclaimer in
* the documentation and/or other materials provided with the
* distribution.
*
* 3. The end-user documentation included with the redistribution,
* if any, must include the following acknowledgment:
* "This product includes software developed by the
* Apache Software Foundation (http://www.apache.org/)."
* Alternately, this acknowledgment may appear in the software itself,
* if and wherever such third-party acknowledgments normally appear.
*
* 4. The names "Xalan" and "Apache Software Foundation" must
* not be used to endorse or promote products derived from this
* software without prior written permission. For written
* permission, please contact apache@apache.org.
*
* 5. Products derived from this software may not be called "Apache",
* nor may "Apache" appear in their name, without prior written
* permission of the Apache Software Foundation.
*
* THIS SOFTWARE IS PROVIDED ``AS IS'' AND ANY EXPRESSED OR IMPLIED
* WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
* OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
* DISCLAIMED. IN NO EVENT SHALL THE APACHE SOFTWARE FOUNDATION OR
* ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
* SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
* LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF
* USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND
* ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
* OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT
* OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
* SUCH DAMAGE.
* ====================================================================
*
* This software consists of voluntary contributions made by many
* individuals on behalf of the Apache Software Foundation and was
* originally based on software copyright (c) 1999, Lotus
* Development Corporation., http://www.lotus.com. For more
* information on the Apache Software Foundation, please see
* <http://www.apache.org/>.
-->
<s1 title="&xslt4j; Overview">
<ul>
<li><link anchor="intro">Introduction</link></li>
<li><link anchor="features">&xslt4j; Features</link></li>
<li><link anchor="towork">Getting to work with &xslt4j;</link></li>
<li><link anchor="uptospeed">Getting up to speed with XSLT</link></li>
<li><link anchor="glossary">Glossary</link></li>
</ul><anchor name="intro"/>
<s2 title="Introduction">
<p>&xslt4j; (named after a rare musical instrument) fully implements the <resource-ref idref="xslt"/> and the
<resource-ref idref="xpath"/>. XSLT is the first part of the XSL stylesheet language for XML. It includes the XSL
Transformation vocabulary and XPath, a language for addressing parts of XML documents. For links to background materials,
discussion groups, frequently asked questions, and tutorials on XSLT, see <link anchor="uptospeed">Getting up
to speed with XSLT</link>.</p>
<note>XSL also includes a vocabulary for formatting documents, which is still under design and is not part of &xslt4j;.
For more information, see <jump href="http://www.w3.org/TR/xsl/">W3C XSL Working Draft</jump> and the <jump
href="http://xml.apache.org/fop">Apache XML FOP (Formatting Objects Project)</jump>.</note>
<p>You use the XSLT language to compose XSL stylesheets. An XSL stylesheet contains instructions for
transforming XML documents from one document type into another document type (XML, HTML, or other). In structural
terms, an XSL stylesheet specifies the transformation of one tree of nodes (the XML input) into another tree of nodes
(the output or transformation result).</p>
<note>The XSL stylesheet may generate and refer to cascading style sheets (CSS) as part of its output.</note>
<p>In the following example, the foo.xsl stylesheet is used to transform foo.xml into foo.out:</p>
<p>foo.xml:</p>
<source><?xml version="1.0"?>
<doc>Hello</doc></source>
<p>foo.xsl:</p>
<source><?xml version="1.0"?>
<xsl:stylesheet xmlns:xsl="http://www.w3.org/1999/XSL/Transform" version="1.0">
<xsl:template match="doc">
<out><xsl:value-of select="."/></out>
</xsl:template>
</xsl:stylesheet></source>
<p>foo.out:</p>
<source><out>Hello</out></source>
<p>By default, &xslt4j; uses the &xml4j; SAXParser, and it may be configured (with system properties) to work with other parsers. The input may be submitted in the form of a SAX InputStream (from a URI, a character or byte stream, or another transformation) or a DOM Node.</p>
<p>&xslt4j; performs the transformations specified in the XSL stylesheet and packages a sequence of SAX events that may be serialized to an output stream or writer, used to build a DOM tree, or forwarded as input to another transformation.</p>
</s2><anchor name="features"/>
<s2 title="&xslt4j; Features">
<ul>
<li>Implements the <resource-ref idref="xslt"/> and the <resource-ref idref="xpath"/><br/><br/></li>
<li>Builds on <resource-ref idref="trax"/>, <resource-ref idref="sax2"/>, <resource-ref idref="dom2"/>,
and the <resource-ref idref="jaxp"/><br/><br/></li>
<li>Works by default with the <jump href="http://xml.apache.org/xerces-j/index.html">&xml4j; SAXParser</jump>, and may
be configured to work with any conformant SAX or DOM parser<br/><br/></li>
<li>Can process SAX or DOM input, and output to SAX or DOM<br/><br/></li>
<li>Transformations may be chained (the output of one transformation may be the input for another)<br/><br/></li>
<li>May be run from the <link idref="commandline">command line</link> for convenient file-to-file
transformations<br/><br/></li>
<li>Includes an <link idref="getstarted" anchor="applet">applet wrapper</link><br/><br/></li>
<li>May be used in a <link idref="samples" anchor="servlet">servlet</link> to transform XML documents into HTML
and serve the results to clients<br/><br/></li>
<li>Supports the creation of <link idref="extensions">Java and scripting language extensions</link> and provides
a growing library of extension elements and functions</li>
</ul>
</s2><anchor name="towork"/>
<s2 title="Getting to work with &xslt4j;">
<p>For instructions and some suggestions about how to get started using &xslt4j;, see
<link idref="getstarted">Getting Started</link>.</p>
</s2><anchor name="uptospeed"/>
<s2 title="Getting up to speed with XSLT">
<p>If you are still working through the details of the XSLT spec (the W3C 1.0 Recommendation), you may want
to consult one or more of the following:</p>
<ul>
<li>Michael Kay's <jump href="http://www.wrox.com/Consumer/Store/Details.asp?ISBN=1861003129">XSLT Programmer's
Reference</jump>, Wrox Press, 2000<br/><br/></li>
<li>Neil Bradley's <jump href="http://cseng.aw.com/bookpage.taf?ISBN=0-201-67487-4">XSL Companion</jump>,
Addison-Wesley, 2000<br/><br/></li>
<li>Elliotte Rusty Harold's <jump href="http://metalab.unc.edu/xml/books/bible/updates/14.html">Chapter 14 of
the XML Bible: XSL Transformations</jump><br/><br/></li>
<li>Crane Softwright's <jump href="http://www.CraneSoftwrights.com/training/">Free preview of Practical
Transformation Using XSLT and XPath</jump><br/><br/></li>
<li>The Mulberry <jump href="http://www.mulberrytech.com/xsl/xsl-list/">XSL-List -- Open Forum on XSL</jump>
(of interest to XSL users at all levels)<br/><br/></li>
<li>Dave Pawson's <jump href="http://freespace.virgin.net/b.pawson/xsl/xslfaq.html">XSL Frequently Asked
Questions</jump><br/><br/></li>
<li>Objects by Design's <jump href="http://www.objectsbydesign.com/projects/xmi_to_html.html">Transforming XMI to
HTML</jump> (oriented towards XMI, "an XML-based, stream representation of a UML model," but also covers "generic"
XML transformations)<br/><br/></li>
<li>Nic Miloslav's <jump href="http://zvon.vscht.cz/HTMLonly/XSLTutorial/Books/Book1/index.html">XSL Tutorial</jump>
<br/><br/></li>
<li>OASIS (the Organization for the Advancement of Structured Information Standards):
<jump href="http://www.oasis-open.org/cover/xsl.html">Extensible Stylesheet Language (XSL)</jump> by Robin
Cover<br/><br/></li>
<li>Donald Ball's <jump href="http://www.webslingerZ.com/balld/xsl/designer_manual.xml">A Guide to XML and XSL for
Designers</jump><br/><br/></li>
<li>XSLT - XSL Transformations in
<jump href="http://www.brics.dk/~amoeller/XML/">The XML Revolution: Technologies for the future Web</jump> by
Anders Møller and Michael I. Schwartzbach</li>
</ul>
<p>When you come across other useful introductory or background materials, please email <human-resource-ref
idref="dleslie"/>, so he can add them to this list.</p>
</s2><anchor name="glossary"/>
<s2 title="Glossary">
<gloss>
<label>XSLT Namespace</label>
<item>The <jump href="http://www.w3.org/TR/REC-xml-names/">XML namespace</jump> for XSLT. An XML namespace is a
collection of element and attribute names, identified by a Unique Resource Identifier (URI), which often takes the form of
a URL, but is really just a unique string, not a pointer to a web page. The XSLT namespace URI is
http://www.w3.org/1999/XSL/Transform. In each XSLT stylesheet, you must declare this namespace in the stylesheet element
tag and bind it to a local prefix. Like the XSLT specification, we always use xsl as the XSLT namespace prefix in our
descriptions and examples, although you are free to bind any prefix to this namespace.<br/><br/></item>
<label>XSL Instruction</label>
<item>Any tag associated with the XSLT namespace.<br/><br/></item>
<label>Template</label>
<item>An element, usually with child elements, that specifies a "rule" or set of
instructions to perform when a particular kind of node is encountered in the source tree.<br/><br/></item>
<label>XSL Template Instruction</label>
<item>Any tag that occurs inside an xsl:template element and is associated with the XSLT namespace.<br/><br/></item>
<label>Source Tree</label>
<item>The XML tree input to the XSL process.<br/><br/></item>
<label>Result Tree</label>
<item>The tree that is output by the XSL process.<br/><br/></item>
<label>Stylesheet Tree</label>
<item>The stylesheet tree produced from the XSL file.<br/><br/></item>
<label>Match Pattern</label>
<item>The part of a template that defines the kind(s) of nodes to which the template applies.<br/><br/></item>
</gloss>
<p>For more definitions of XSLT terminology, see Dave Pawson's
<jump href="http://freespace.virgin.net/b.pawson/xsl/jargon.html">XSLT Terminology
Clarification</jump> and the Glossary in Michael Kay's
<jump href="http://www.wrox.com/Consumer/Store/Details.asp?ISBN=1861003129">XSLT Programmer's Reference</jump>.</p>
</s2>
</s1>
1.1 xml-xalan/java/xdocs/sources/xalan/readme.xml
Index: readme.xml
===================================================================
<?xml version="1.0" standalone="no"?>
<!DOCTYPE s1 SYSTEM "sbk:/style/dtd/document.dtd"[
<!ENTITY done-j SYSTEM "DONE">
<!ENTITY status-j SYSTEM "STATUS">
<!ENTITY bugs-j SYSTEM "BUGS">]>
<!--
* The Apache Software License, Version 1.1
*
*
* Copyright (c) 1999 The Apache Software Foundation. All rights
* reserved.
*
* Redistribution and use in source and binary forms, with or without
* modification, are permitted provided that the following conditions
* are met:
*
* 1. Redistributions of source code must retain the above copyright
* notice, this list of conditions and the following disclaimer.
*
* 2. Redistributions in binary form must reproduce the above copyright
* notice, this list of conditions and the following disclaimer in
* the documentation and/or other materials provided with the
* distribution.
*
* 3. The end-user documentation included with the redistribution,
* if any, must include the following acknowledgment:
* "This product includes software developed by the
* Apache Software Foundation (http://www.apache.org/)."
* Alternately, this acknowledgment may appear in the software itself,
* if and wherever such third-party acknowledgments normally appear.
*
* 4. The names "Xalan" and "Apache Software Foundation" must
* not be used to endorse or promote products derived from this
* software without prior written permission. For written
* permission, please contact apache@apache.org.
*
* 5. Products derived from this software may not be called "Apache",
* nor may "Apache" appear in their name, without prior written
* permission of the Apache Software Foundation.
*
* THIS SOFTWARE IS PROVIDED ``AS IS'' AND ANY EXPRESSED OR IMPLIED
* WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
* OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
* DISCLAIMED. IN NO EVENT SHALL THE APACHE SOFTWARE FOUNDATION OR
* ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
* SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
* LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF
* USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND
* ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
* OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT
* OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
* SUCH DAMAGE.
* ====================================================================
*
* This software consists of voluntary contributions made by many
* individuals on behalf of the Apache Software Foundation and was
* originally based on software copyright (c) 1999, Lotus
* Development Corporation., http://www.lotus.com. For more
* information on the Apache Software Foundation, please see
* <http://www.apache.org/>.
-->
<s1 title="Release Notes">
<p>&xslt4j-current;</p>
<ul>
<li><link anchor="status">Status</link></li>
<li><link anchor="build">Build Notes</link></li>
<li><link anchor="contact">Getting in touch</link></li>
<li><link anchor="history">History of software changes</link></li>
</ul>
<s2 title="Status">
<ul>
<li><link anchor="bugs">Open bugs and bug reporting</link></li>
<li><link anchor="status">Version of Xerces to use</link></li>
<li><link anchor="to-do">To-do tasks for future &xslt4j; releases</link></li>
</ul>
<anchor name="bugs"/>
&bugs-j;
<anchor name="status"/>
&status-j;
</s2>
<anchor name="build"/>
<s2 title="Build Notes">
<ul>
<li><link anchor="ant">Using Ant</link></li>
<li><link anchor="jar">Rebuilding xalan.jar</link></li>
<li><link anchor="samples">Rebuilding sample applications</link></li>
<li><link anchor="doc">Rebuilding the &xslt4j; documentation</link></li>
</ul>
<anchor name="ant"/>
<s3 title="Using Ant">
<p>Apache <resource-ref idref="ant"/> is a flexible, powerful, and easy-to-use Java build tool that we include with the
&xslt4j; distribution. The Ant JAR file is in the bin directory along with a cross-platform XML build file (build.xml), a
Windows32 batch file (build.bat) and a UNIX shell file (build.sh). The build file defines the "targets" that you can use Ant
to build. The batch and shell files set up the classpath and launch Ant with the target (and any other arguments) you
provide.</p>
<p><em>Instructions for using Ant</em></p>
<ol>
<li>Set the JAVA_HOME environment variable to the JDK root directory.<br/><br/>
If you are using JDK 1.1.8, you must also put classes.zip in the JDK bin directory on the classpath. You can use Ant
with JDK 1.1.8 to compile and jar the &xslt4j; source files, but you must have JDK 1.2.2 or higher to build the
documentation.<br/><br/></li>
<li>Depending on your environment, run the batch file (build.bat) or shell file (bmild.sh) from the &xslt4j; root
directory, optionally with arguments (see the table of targets below).<br/><br/>
The batch/shell file adds several JAR files to the classpath and launches Ant with any arguments you provide. If you
provide no target, Ant compiles the source files and rebuilds xalan.jar (the "jar" target).</li>
</ol>
<p>You can also set up your classpath manually (see build.bat or build.sh for the details), and then run Ant as
follows:<br/><br/>
<code>java org.apache.tools.ant.Main <ref>target</ref></code><br/><br/>
where <ref>target</ref> is nothing (for the default target) or one of the following.</p>
<table>
<tr><td><em>Target</em></td><td><em>What Ant does</em></td></tr>
<tr><td>compile</td><td>compiles Xalan-J in build/classes.</td></tr>
<tr><td>jar</td><td>creates xalan.jar in the build directory (the default)</td></tr>
<tr><td>samples</td><td>compiles and jars the sample apps (except the sample servlet)</td></tr>
<tr><td>servlet</td><td>compiles and jars the sample servlet</td></tr>
<tr><td>docs</td><td>creates the HTML User's Guide in build/docs</td></tr>
<tr><td>javadocs</td><td>generates the API documentation in ./build/docs/apidocs</td></tr>
<tr><td>dist</td><td>creates a complete distribution in xalan-j_<ref>x</ref>_<ref>y</ref>_<ref>z</ref></td></tr>
<tr><td>site</td><td> creates the website documentation tree in xml-site/target/xalan</td></tr>
<tr><td>clean</td><td>purges the build, distribution, and site trees, and removes any document files placed
in the source tree for doc and Javadoc builds</td></tr>
</table>
<p>If you build a target that depends on other targets, Ant creates those other targets in the correct order.</p>
</s3><anchor name="jar"/>
<s3 title="Rebuilding &xslt4j;">
<p>The &xslt4j; build is in xalan.jar. The &xslt4j; source code tree is in the src directory.</p>
<p>If you are using Ant, the target is jar (the default). For more information, see <link anchor="ant">Using
Ant</link>.</p>
<p>If you want to do the build without Ant, keep the following in mind:</p>
<ul>
<li>Set the class path to include the src directory, xerces.jar, bsf.jar, and bsfengines.jar.</li>
<li>Use a Java compiler (such as the IBM Just-In-Time compiler or the Sun javac) to compile all the .java files in the src
tree. </li>
<li>Use the Sun jar utility to store the resulting .class files in xalan.jar</li>
</ul>
</s3><anchor name="samples"/>
<s3 title="Rebuilding a sample application">
<p>If you modify a sample and want to recompile it, you can run the Java compiler in the directory containing the
example. Be sure xalan.jar and xerces.jar are on the class path. To recompile (and run!) the class files in the
Servlet subdirectory, the javax.servlet and javax.servlet.http packages must also be on the class path. Sun
distributes these packages in the JSWDK 1.0.1 servlet.jar file.</p>
<p>After recompiling a sample, you can use the Sun jar utility to place your new .class files in
xalansamples.jar.</p>
<p>You can use Ant with the samples target to recompile the samples and place the unpackaged class files in xalansamples.jar.
For more information, see <link anchor="ant">Using Ant</link>.</p>
<note>To rebuild (and to run) the sample servlet, the javax.servlet and javax.servlet.http packages must be on your
classpath.</note>
</s3><anchor name="doc"/>
<s3 title="Rebuilding the &xslt4j; documentation">
<p>&xslt4j; includes a number of XML source files, XSL stylesheets, document type definition (DTD)
files, entity relationship (ENT) files, graphics, and a JavaScript file that provide the input for the Xalan
HTML User's Guide, and the overview and package-level documents used during the generation of Javadoc.</p>
<p>To rebuild the documentation, you must use the StyleBook tool and the JDK 1.2.2 java and javadoc
tools. StyleBook (which uses Xalan and Xerces) is in stylebook-1.0-b3_xalan-2.jar. Some of the document definition files,
stylesheets, and resources are stored in xml-site-style.tar.gz, and are unzipped when you run the Ant build.</p>
<p>You can use Ant with the docs target to regenerate the User's Guide and with the javadocs target to regenerate the
Javadoc API documentation. For more information, see <link anchor="ant">Using Ant</link>.</p>
<p>If you want to rebuild the documentation without using Ant, keep the following in mind:</p>
<ul>
<li>Unzip xml-site-style.tar.gz into the xdocs directory (the operation places files in a number of subdirectories).
<br/><br/></li>
<li>Be sure stylebook-1.0-b3_xalan-2.jar, xalanjdoc.jar, xalan.jar, bsf.jar, bsfengines.jar, and xerces.jar are on the class
path.<br/><br/></li>
<li>To build doc in a build/docs subdirectory, run StyleBook from the xdocs directory as follows:<br/><br/>
<code>java org.apache.stylebook.StyleBook "targetDirectory=../build/docs/" sources/xalanLocal.xml style</code>
<br/><br/></li>
<li>To build the HTML source files that javadoc needs for top-level and package-level documentation, run
StyleBook from the xdocs directory as follows:<br/><br/>
<code>java org.apache.stylebook.StyleBook "loaderConfig=sbk:/style/loaderjdoc.xml" targetDirectory=../src sources/javadocPackages.xml style</code><br/><br/></li>
<li>Before you run javadoc, make sure the following directory structure exists under the Xalan root
directory: build/docs/apidocs.<br/><br/></li>
<li>To build the API documentation, run the JDK 1.2.2 javadoc tool from the xdocs directory:<br/><br/>
<code>-doclet xalanjdoc.Standard -public -overview ../src/javadocOverview.html -sourcepath ../src -group XSLT_Packages "org.apache.xalan.xslt*" -group XPath_Packages "org.apache.xalan.xpath*" org.apache.xalan.xpath org.apache.xalan.xpath.xdom org.apache.xalan.xpath.dtm org.apache.xalan.xpath.xml org.apache.xalan.xslt org.apache.xalan.xslt.trace org.apache.xalan.xslt.client org.apache.xalan.xslt.extensions -windowtitle Xalan -d ../build/docs/apidocs
</code></li>
</ul>
</s3>
</s2><anchor name="contact"/>
<s2 title="Getting in Touch">
<p>Your feedback is more than welcome. Offers of help are even more so! Perhaps you would like to take on an active role in the ongoing development, testing, and documentation of &xslt4j;?</p>
<p>Please email your comments, questions, suggestions, and offers to join the Xalan team to <human-resource-ref idref="xalandev"/>.</p>
</s2>
</s1>
1.1 xml-xalan/java/xdocs/sources/xalan/resources.xml
Index: resources.xml
===================================================================
<?xml version="1.0" encoding="US-ASCII"?>
<!DOCTYPE resources [
<!ENTITY % externalEntity SYSTEM "sbk:/sources/entities.ent">
%externalEntity;
<!ELEMENT resources (resource|human-resource)+>
<!ELEMENT resource EMPTY>
<!ATTLIST resource
id CDATA #IMPLIED
title CDATA #IMPLIED
location CDATA #IMPLIED>
<!ELEMENT human-resource EMPTY>
<!ATTLIST human-resource
id CDATA #IMPLIED
name CDATA #IMPLIED
mailto CDATA #IMPLIED>
]>
<resources>
<resource id="xslt4j-current"
title="&xslt4j-current;"
location="http://xml.apache.org/xalan"/>
<resource id="xslt4j-dist-zip"
title="&xslt4j-dist;.zip"
location="http://xml.apache.org/dist/xalan-j/&xslt4j-dist;.zip"/>
<resource id="xslt4j-dist-targz"
title="&xslt4j-dist;.tar.gz"
location="http://xml.apache.org/dist/xalan-j/&xslt4j-dist;.tar.gz"/>
<resource id="xslt4j-distdir"
title="xalan-j distribution directory"
location="http://xml.apache.org/dist/xalan-j/"/>
<resource id="xml4j-used"
title="&xml4j-used;"
location="http://xml.apache.org/xerces-j/index.html"/>
<resource id="xml4j-distdir"
title="xerces-j distribution directory"
location="http://xml.apache.org/dist/xerces-j/"/>
<resource id="ant" title="Ant"
location="http://jakarta.apache.org/ant/index.html"/>
<resource id="ApacheLicense"
title="The Apache Software License, Version 1.1"
location="http://xml.apache.org/dist/LICENSE.txt"/>
<resource id="Readme"
title="Xalan Repository Release Notes"
location="http://www.apache.org/websrc/cvsweb.cgi/xml-xalan/README"/>
<resource id="xslt"
title="W3C Recommendation 16 November 1999 XSL Transformations (XSLT) Version 1.0"
location="http://www.w3.org/TR/xslt"/>
<resource id="xpath"
title="XML Path Language (XPath) Version 1.0"
location="http://www.w3.org/TR/xpath"/>
<resource id="trax"
title="TRaX (Transformations for XML)"
location="http://trax.openxml.org/"/>
<resource id="dom"
title="DOM"
location="http://www.w3.org/DOM"/>
<resource id="dom2"
title="DOM level 2"
location="http://www.w3.org/TR/DOM-Level-2/"/>
<resource id="sax"
title="SAX"
location="http://www.megginson.com/SAX/sax.html"/>
<resource id="sax2"
title="SAX 2"
location="http://www.megginson.com/SAX/Java/index.html"/>
<resource id="jaxp"
title="Java API for XML Parsing"
location="http://java.sun.com/xml/docs/api/index.html"/>
<human-resource id="xalandev"
name="Xalan Development Mailing List"
mailto="xalan-dev@xml.apache.org"/>
</resources>
1.1 xml-xalan/java/xdocs/sources/xalan/STATUS
Index: STATUS
===================================================================
<s3 title="Version of Xerces to use">
<p>The &xslt4j-current; has been tested with &xml4j-used;. &download; For information about including xerces.jar on the system class path, see <link idref="getstarted" anchor="classpath">Setting up the system class path</link>.</p>
<p><em>Important</em> You may experience unpredictable anomalies if your Xalan and Xerces builds are not in synch. If you download an update to Xalan, check the release notes to determine which version of Xerces you should use.</p>
<note>You can use Xalan with other conformnant SAX and DOM parsers. </note>
</s3><anchor name="to-do"/>
<s3 title="To-do tasks">
<p>As part of the xml.apache team, members of the &xslt4j; team are also exploring options to upgrade the integration of all
the xml.apache projects, including Xalan, Xerces, Cocoon, and FOP.</p>
<p>The more individuals who join in the design, development, testing, documentation, and use of
&xslt4j; the better for us all in the xml.apache.org open source community! Watch the <human-resource-ref idref="xalandev"/> for more information and for ideas about how you can get involved.</p>
</s3>
1.1 xml-xalan/java/xdocs/sources/xalan/usagepatterns.xml
Index: usagepatterns.xml
===================================================================
<?xml version="1.0" standalone="no"?>
<!DOCTYPE s1 SYSTEM "sbk:/style/dtd/document.dtd">
<!--
* The Apache Software License, Version 1.1
*
*
* Copyright (c) 1999 The Apache Software Foundation. All rights
* reserved.
*
* Redistribution and use in source and binary forms, with or without
* modification, are permitted provided that the following conditions
* are met:
*
* 1. Redistributions of source code must retain the above copyright
* notice, this list of conditions and the following disclaimer.
*
* 2. Redistributions in binary form must reproduce the above copyright
* notice, this list of conditions and the following disclaimer in
* the documentation and/or other materials provided with the
* distribution.
*
* 3. The end-user documentation included with the redistribution,
* if any, must include the following acknowledgment:
* "This product includes software developed by the
* Apache Software Foundation (http://www.apache.org/)."
* Alternately, this acknowledgment may appear in the software itself,
* if and wherever such third-party acknowledgments normally appear.
*
* 4. The names "Xalan" and "Apache Software Foundation" must
* not be used to endorse or promote products derived from this
* software without prior written permission. For written
* permission, please contact apache@apache.org.
*
* 5. Products derived from this software may not be called "Apache",
* nor may "Apache" appear in their name, without prior written
* permission of the Apache Software Foundation.
*
* THIS SOFTWARE IS PROVIDED ``AS IS'' AND ANY EXPRESSED OR IMPLIED
* WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
* OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
* DISCLAIMED. IN NO EVENT SHALL THE APACHE SOFTWARE FOUNDATION OR
* ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
* SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
* LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF
* USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND
* ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
* OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT
* OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
* SUCH DAMAGE.
* ====================================================================
*
* This software consists of voluntary contributions made by many
* individuals on behalf of the Apache Software Foundation and was
* originally based on software copyright (c) 1999, Lotus
* Development Corporation., http://www.lotus.com. For more
* information on the Apache Software Foundation, please see
* <http://www.apache.org/>.
-->
<s1 title="Basic usage patterns">
<ul>
<li><link anchor="basic">Basic steps</link></li>
<li><link anchor="params">Setting stylesheet parameters</link></li>
<li><link anchor="sax">Explicitly working with SAX</link></li>
<li><link anchor="dom">Processing and producing DOM trees</link></li>
<li><link anchor="xpath">Working with XPath expressions</link></li>
<li><link anchor="applet">Using the &xslt4j; applet wrapper</link></li>
<li><link anchor="servlet">Using &xslt4j; in a servlet</link></li>
<li><link anchor="extensions">Creating and using extensions</link></li>
<li><link anchor="debugging">Debugger interface</link></li>
</ul>
<anchor name="basic"/>
<s2 title="Basic steps">
<ol>
<li><link anchor="processor">Instantiate stylesheet Processor</link></li>
<li><link anchor="process">Process stylesheet</link></li>
<li><link anchor="transformer">Instantiate Transformer</link></li>
<li><link anchor="transformation">Perform transformation</link></li>
</ol>
<p>The following example highlights the four basic steps involved in performing a transformation.</p>
<source>// 1. Instantiate a stylesheet Processor.
trax.Processor processor = trax.Processor.newInstance("xslt");
// 2. Process the stylesheet, producing a Templates object.
trax.Templates templates = processor.process
(new org.xml.sax.InputSource("foo.xsl"));
// 3. Use the Templates object to instantiate a Transformer.
trax.Transformer transformer = templates.newTransformer();
// 4. Use the Transformer to apply the Templates object to an XML
// source and send the output to a Result object.
transformer.transform
(new org.xml.sax.InputSource("foo.xml"),
new trax.Result(new java.io.FileWriter("foo.out")));</source>
<note>For a working example of this model at its simplest, see SimpleTransform.java in the java/samples/SimpleTransform subdirectory.</note>
</s2><anchor name="processor"/>
<s2 title="1. Instantiate a stylesheet Processor">
<p>The trax.Processor static newInstance() method with "xslt" as its argument instantiates the processor designated by the trax.processor.xslt system property.</p>
<p>If this system property has not already been set, trax.Processor sets it from a file.</p>
<p>For &xslt4j;, this system property should be set to org.apache.xalan.processor.StylesheetProcessor.</p>
</s2><anchor name="process"/>
<s2 title="2. Process the stylesheet, producing a Templates object">
<p>The Templates object is an immutable runtime representation of the structure and content of a stylesheet (which may include
and import multiple stylesheet sources).</p>
<p>A given Templates object may be used repeatedly and by multiple concurrent threads for the transformation of XML input. Each Templates object also incorporates XSLTSchema, which encapsulates the underlying XSLT stylesheet schema.</p>
<p>You may provide the stylesheet as a SAX input source (from a file or stream) or as a DOM tree.</p>
<p>Use the Processor process() method with a SAX input source (as in the example above), or the processFromNode() method with a DOM tree to generate a Templates object.</p>
<p>To perform this operation with a SAX input source, the processor uses a trax.TemplatesBuilder (extending the SAX ContentHandler interface) and a SAX XMLReader.</p>
<p>The XMLReader parses the input, sending parse events to the TemplatesBuilder, which responds by building the Templates object.</p>
<note>Templates and TemplatesBuilder are TRaX interfaces, and XMLReader is a SAX interface. &xslt4j; uses org.apache.xalan.templates.StylesheetRoot to implement Templates, and org.apache.xalan.processor.StylesheetHandler to implement TemplatesBuilder. XMLReader is a SAX interface. The &xslt4j; StylesheetProcessor uses org.xml.sax.XMLReaderFactory to instantiate an XMLReader as designated by the org.xml.sax.driver system property. If you are using &xml4j;, this system property should be set to org.apache.xerces.parsers.SAXParser</note>
<p>If you use the processFromNode() method with a DOM representation of the stylesheet, the processor uses org.apache.xalan.utils.TreeWalker to traverse the DOM, sending SAX events to the TemplatesBuilder.</p>
</s2><anchor name="transformer"/>
<s2 title="3. Instantiate a Transformer">
<p>To transform an XML document, you need an implementation of the trax.Transformer interface.</p>
<p>&xslt4j; implements the Transformer interface with org.apache.xalan.transformer.TransformerImpl.</p>
<p>You can use a Templates object for multiple transformations (even performed concurrently), but you should use the Templates object to instantiate a separate Transformer for each transformation you perform. The Templates object contains the stylesheet structure and data and XSLT schema, which are immutable, whereas the Transformer tracks state information as it performs the transformation.</p>
</s2><anchor name="transformation"/>
<s2 title="4. Perform a transformation">
<p>Supply the XML input, a target or "holder" for the transformation output, and instruct the Transformer to perform the transformation.</p>
<p>Just as with the stylesheet, you can supply the XML input in the form of a SAX input source (from a URL or stream) or a DOM tree.</p>
<p>TRaX provides the holder for the output: trax.Result. You can set up a Result object to send the transformation result to a file or stream or to build a DOM tree.</p>
<p>The Transformer uses the SAX XMLParser to parse the XML input and sends parse events to an input SAX ContentHandler, org.apache.xalan.stree.SourceTreeHandler, which in turn uses org.apache.xalan.utils.DOMBuilder to assemble the input into a DOM tree. Of course this operation is unnecessary if the XML input is submitted as a DOM.</p>
<p>For each node in the XML source, the Transformer uses the Templates object and underlying XSLT schema to determine which template to apply: one of the templates in the Templates object, a default template rule as specified in the XSLT spec, or none.</p>
<p>The Transformer works with org.apache.xalan.transformer.ResultTreeHandler to forward the SAX events produced by this process to the appropriate output ContentHandler, a serializer if the Result object has been set up to write to a stream or file, a DOMBuilder utility if the output is to be a DOM tree.</p>
<p>To the degree possible, the parsing of the XML source and application of the Templates object to that source are performed concurrently in separate threads. When necessary, the Transformer waits for the parse events that must be in place before a given template may be applied.</p>
</s2><anchor name="params"/>
<s2 title="Setting stylesheet parameters">
<p>An XSLT stylesheet may include parameters that are set at run time each time a transformation takes place. To set a stylesheet parameter, use the trax.Transformer <jump href="apidocs/trax/Transformer.html#setParameter(java.lang.String,java.lang.String,java.lang.Object)">setParameter(String name, String namespace, Object value)</jump> method. If the parameter QName only includes a local name (as is often the case), the namespace argument is null. For a working example, see UseStylesheetParam.java in the java/samples/UseStylesheetParam subdirectory.</p>
<p>You can also set a parameter with the command-line utility by including the -param flag. For example:</p>
<p><code>java org.apache.xalan.xslt.Process -in foo.xml -xsl foo.xsl -param param1 boo</code></p>
<p>or</p>
<p><code>java org.apache.xalan.xslt.Process -in foo.xml -xsl foo.xsl -param param1 org/myorg/xyz boo</code></p>
<p>where <code>org/myorg/xyz</code> is the parameter namespace. [not yet working]</p>
</s2><anchor name="sax"/>
<s2 title="Explicitly working with SAX">
<p>&xslt4j; uses the SAX event model to process stylesheets, to parse XML input documents, and to produce output. For each of these operations, an XMLReader reads input, firing parse events, and a ContentHandler listens to the XMLReader and performs parse event methods.</p>
<p>When you use the basic procedure described above for performing transformations, &xslt4j; takes care of many of the SAX details under the covers. You are free to make these details explicit, which simply means that you can intervene in the procedure to accommodate the specific conditions in which your application operates.</p>
<p>Suppose, for example, you are using a custom XMLReader (perhaps doing more than just parsing static XML documents) to generate &xslt4j; SAX parse events. You can instruct the Transformer to provide the ContentHandler for this XMLReader. You might even have a custom reader for producing/processing stylesheets, in which case you simply set the trax.TemplatesBuilder (implemented by the org.apache.xalan.processor.StylesheetHandler) as the ContentHandler for this reader.</p>
<p>The following example replicates the <link anchor="basic">Basic 4 steps</link> described above</p>
<source>// 1. Instantiate stylesheet processor.
trax.Processor processor = trax.Processor.newInstance("xslt");
// 2. Process the stylesheet. producing a Templates object.
// Get the XMLReader.
org.xml.sax.XMLReader reader =
org.xml.sax.helpers.XMLReaderFactory.createXMLReader();
// Set the ContentHandler.
trax.TemplatesBuilder templatesBuilder = processor.getTemplatesBuilder();
reader.setContentHandler(templatesBuilder);
// Set the ContentHandler to also function as a LexicalHandler, which
// includes "lexical" (e.g., comments and CDATA) events. The Xalan
// TemplatesBuilder -- org.apache.xalan.processor.StylesheetHandler -- is
// also a LexicalHandler).
if(templatesBuilder instanceof org.xml.sax.ext.LexicalHandler)
reader.setProperty("http://xml.org/sax/properties/lexical-handler",
templatesBuilder);
// Parse the stylesheet.
reader.parse("foo.xsl");
//Get the Templates object from the ContentHandler.
trax.Templates templates = templatesBuilder.getTemplates();
// 3. Use the Templates object to instantiate a Transformer.
trax.Transformer transformer = templates.newTransformer();
// 4. Perform the transformation.
// Set up the ContentHandler (a serializer) for the output.
trax.Result result = new trax.Result(new java.io.FileWriter("foo.out"));
org.apache.xml.serialize.SerializerFactory sfactory =
org.apache.xml.serialize.SerializerFactory.getSerializerFactory("xml");
org.apache.xml.serialize.Serializer serializer = sfactory.makeSerializer
(result.getCharacterStream(),
new org.apache.xml.serialize.OutputFormat());
transformer.setContentHandler(serializer.asContentHandler());
// Set up the ContentHandler for the input.
org.xml.sax.ContentHandler chandler = transformer.getInputContentHandler();
reader.setContentHandler(chandler);
if(chandler instanceof org.xml.sax.ext.LexicalHandler)
reader.setProperty("http://xml.org/sax/properties/lexical-handler",chandler);
else
reader.setProperty("http://xml.org/sax/properties/lexical-handler", null);
// Parse the XML input document. The input and output ContentHandlers work in
// separate threads to optimize performance.
reader.parse("foo.xml");</source>
</s2><anchor name="dom"/>
<s2 title="Processing and producing DOM trees">
<p>In some cases, the input and/or desired output for a transformation may be a DOM tree object, rather than a file or stream.</p>
<p>To process DOM input, use one of the trax.Transformer <jump href="apidocs/trax/Transformer.html#transformNode(org.w3c.dom.Node, trax.Result)">transformNode()</jump> methods.</p>
<p>To produce a transformation result in the form of a DOM tree, use the <jump href="http://java.sun.com/xml/docs/api/index.html">Java API for XML Parsing</jump> as indicated below to instantiate an empty DOM Document to hold the result tree.</p>
<ol>
<li>The javax.xml.parsers.DocumentBuilderFactory abstract class contains a static newInstance() method for instantiating a factory designated by the javax.xml.parsers.DocumentBuilderFactory system property.<br/><br/></li>
<li>In turn, the factory provides a newDocumentBuilder() method with which you instantiate a DocumentBuilder.<br/><br/></li>
<li>Use the DocumentBuilder to instantiate an empty DOM Document.<br/><br/></li>
<li>Use this DOM Document node to construct the trax.Result object for the transformation result tree.</li>
</ol>
<source>javax.xml.parsers.DocumentBuilderFactory dfactory =
javax.xml.parsers.DocumentBuilderFactory.newInstance();
javax.xml.parsers.DocumentBuilder docBuilder = dfactory.newDocumentBuilder();
org.w3c.dom.Document resultDoc = docBuilder.newDocument();
trax.Result result = new trax.Result(resultDoc);
</source>
<note>If you are using the Xerces implementation of the <ref>Java API for XML Parsing</ref> (in xerces.jar), the default value for the javax.xml.parsers.DocumentBuilderFactory system property is org.apache.xerces.jaxp.DocumentBuilderFactoryImpl. The Xerces implementations of DocumentBuilder and DOM Document are org.apache.xerces.jaxp.DocumentBuilderImpl and org.apache.xerces.dom.DocumentImpl.</note>
</s2><anchor name="xpath"/>
<s2 title="Working with XPath expressions">
<p><ref>To be written.</ref></p>
</s2><anchor name="applet"/>
<s2 title="Using the &xslt4j; applet wrapper">
<ol>
<li>Include <jump href="apidocs/org/apache/xalan/client/XSLTProcessorApplet.html">XSLTProcessorApplet</jump> in an HTML client.<br/><br/></li>
<li>Specify the XML source document and XSL stylesheet.<br/><br/>
You can use the DocumentURL and StyleURL PARAM tags or the <jump href="apidocs/org/apache/xalan/client/XSLTProcessorApplet.html#setDocumentURL(java.lang.String)">setdocumentURL()</jump> and <jump href="apidocs/org/apache/xalan/client/XSLTProcessorApplet.html#setStyleURL(java.lang.String)">setStyleURL()</jump> methods. If the XML document contains a stylesheet Processing Instruction (PI), you do not need to specify an XSL stylesheet.<br/><br/></li>
<li>Call the <jump href="apidocs/org/apache/xalan/client/XSLTProcessorApplet.html#transformToHtml(java.lang.String,java.lang.String)">transformToHtml()</jump> method, which performs the transformation and returns the new document as a String.</li></ol>
<p>For an example, see the <jump href="../samples/appletXMLtoHTML/readme.html">sample applet readme</jump>.</p>
</s2><anchor name="servlet"/>
<s2 title="Using &xslt4j; in a servlet">
<p>You can set up a servlet to use &xslt4j; to respond to requests for XML documents by transforming those documents into HTML and serving them to clients. For a sample of how this might be done, see <link idref="samples" anchor="servlet">sample servlet</link>.</p>
</s2><anchor name="extensions"/>
<s2 title="Creating and using extensions">
<p>For those cases where you want to be able to call procedural code from within a stylesheet, the &xslt4j; Extensions facility supports the creation of extension elements and extension functions. See <link idref="extensions">Extensions</link> and <link idref="samples" anchor="extensions">Extensions samples</link>.</p>
</s2>
<anchor name="debugging"/>
<s2 title="Debugger Interface">
<p>&xslt4j; contains a debugger interface in the org.apache.xalan.xslt.trace package:</p>
<ul>
<li><jump href="apidocs/org/apache/xalan/trace/TraceListener.html">TraceListener"</jump> is an interface that debuggers
can implement. Or, like the <link idref="commandline">command-line utility</link>, you can use the <jump
href="apidocs/org/apache/xalan/trace/PrintTraceListener.html">PrintTraceListener</jump> implementation of that interface.
<br/><br/></li>
<li>You can associate a <jump href="apidocs/org/apache/xalan/trace/TraceManager.html">TraceManager</jump> with the
Transformer for a given transformation, and register a TraceListener with the TraceManager.<br/><br/></li>
<li><jump href="apidocs/org/apache/xalan/trace/TracerEvent.html">TracerEvent</jump> is an event that is
passed to the TraceListener.trace function. It is called before a node is 'executed' in the stylesheet.<br/><br/></li>
<li><jump href="apidocs/org/apache/xalan/trace/GenerateEvent.html">GenerateEvent</jump> is an event that is
passed to the TraceListener.generated() function. It is called after an event occurs to create something in the result
tree.<br/><br/></li>
<li><jump href="apidocs/org/apache/xalan/trace/SdelectionEvent.html">SelectionEvent</jump> is an event triggered by the
selection of a stylesheet node.</li>
</ul>
<p>The <link idref="commandline">command-line utility</link> uses the debugger interface when you include one or more of the
following switches: -TT, -TG, -TS, -TTC.</p>
<p>Example:</p>
<source>import org.apache.xalan.transformer.TransformerImpl;
import org.apache.xalan.trace.TraceManager;
import org.apache.xalan.trace.PrintTraceListener;
...
// Set up a PrintTraceListener object to print to a file.
java.io.FileWriter fw = new java.io.FileWriter("events.log");
java.io.PrintWriter pw = new java.io.PrintWriter(fw);
PrintTraceListener ptl = new PrintTraceListener(pw);
// Print information as each node is 'executed' in the stylesheet.
ptl.m_traceElements = true;
// Print information after each result-tree generation event.
ptl.m_traceGeneration = true;
// Print information after each selection event.
ptl.m_traceSelection = true;
// Print information whenever a template is invoked.
ptl.m_traceTemplates = true;
// Set up the transformation
traxProcessor processor = trax.Processor.newInstance("xslt");
trax.Templates templates = processor.process
(new org.xml.sax.InputSource("foo.xsl"));
trax.Transformer transformer = templates.newTransformer();
// Cast the Transformer object as TransformerImpl.
if (transformer instanceof TransformerImpl) {
TransformerImpl transformerImpl = (TransformerImpl)transformer;
// Register the TraceListener with a TraceManager associated
// with the TransformerImpl.
TraceManager trMgr = new TraceManager(transformerImpl);
trMgr.addTraceListener(ptl);
// Perform the transformation --printing information to
// the events log during the process.
transformer.transform
(new org.xml.sax.InputSource("foo.xml"),
new trax.Result(new java.io.FileWriter("foo.out")));
}
// Close the PrintWriter and FileWriter.
pw.close();
fw.close();</source>
</s2>
</s1>