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 [EMAIL PROTECTED]
*
* 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 [EMAIL PROTECTED]
*
* 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 [EMAIL PROTECTED]
*
* 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="[email protected]"/>
</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 [EMAIL PROTECTED]
*
* 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>
