mkwan 2002/10/28 12:46:31
Modified: java/xdocs/sources/xalan extensions.xml extensionslib.xml
samples.xml
Log:
Update the extensions documentation.
Use the new namespaces in documents and examples. Update EXSLT development
status. Modify setup instructions for SQL samples.
Revision Changes Path
1.21 +57 -54 xml-xalan/java/xdocs/sources/xalan/extensions.xml
Index: extensions.xml
===================================================================
RCS file: /home/cvs/xml-xalan/java/xdocs/sources/xalan/extensions.xml,v
retrieving revision 1.20
retrieving revision 1.21
diff -u -r1.20 -r1.21
--- extensions.xml 8 Feb 2002 22:24:14 -0000 1.20
+++ extensions.xml 28 Oct 2002 20:46:31 -0000 1.21
@@ -73,9 +73,9 @@
<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. &xslt4j; also provides a growing <link
idref="extensionslib">extensions library</link> available for your use. An extension
(a collection of elements and functions) inhabits a namespace, either a namespace you
declare and designate as an extensions namespace, or one of the predefined namespaces
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 XSLT 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 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 XSLT 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. Extension functions written in Java can also
access certain items in the XSLT execution environment through an <jump
href="apidocs/org/apache/xalan/extensions/ExpressionContext.html">ExpressionContext</jump>
interface.</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. Extension functions written in Java can also
access certain items in the XSLT execution environment through an <jump
href="apidocs/org/apache/xalan/extensions/ExpressionContext.html">ExpressionContext</jump>
interface.</p>
<p>XSLT extensions are specified in the <jump
href="http://www.w3.org/TR/xslt#extension";>XSLT Recommendation</jump>. This document
focuses on the &xslt4j; implementation of those requirements, not on XSLT extensions
in general. For additional information on extensions, consult the Recommendation or
the other resources listed in <link idref="overview" anchor="uptospeed">Getting up to
speed with XSLT</link>.</p>
</s2><anchor name="supported-lang"/>
@@ -135,31 +135,31 @@
<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 extension elements.</note>
<p>As you review this stylesheet, please note the following:</p>
<ol>
- <li>The declaration of the &xslt; xslt namespace, which provides support for
the component and
+ <li>The declaration of the xalan 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>
+ <code>xmlns:xalan="http://xml.apache.org/xalan";</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. This
causes any element in the namespace associated with this prefix to be treated as an
extension element rather than a literal result element.<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
+ <li>The xalan: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>
+ <li>The xalan:script subelement with a JavaScript implementation of the
extension. For Java
+ extensions, the xalan: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:xalan="http://xml.apache.org/xalan";
xmlns:my-ext="ext1"
extension-element-prefixes="my-ext">
- <!--The component and its script are in the lxslt namespace and define the
+ <!--The component and its script are in the xalan namespace and define the
implementation of the extension.-->
- <lxslt:component prefix="my-ext" elements="timelapse" functions="getdate">
- <lxslt:script lang="javascript">
+ <xalan:component prefix="my-ext" elements="timelapse" functions="getdate">
+ <xalan: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
@@ -178,8 +178,8 @@
d.setDate(d.getDate() + totalDays);
return d.toLocaleString();
}
- </lxslt:script>
- </lxslt:component>
+ </xalan:script>
+ </xalan:component>
<xsl:template match="deadline">
<p><my-ext:timelapse multiplier="2"/>We have logged your enquiry
and will
@@ -194,13 +194,14 @@
</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 elements and functions implemented in
Java, you can also use an abbreviated syntax, described in <link
anchor="java-namespace">Alternative: using the abbreviated syntax for extensions
implemented in Java</link>. Unless you are using the abbreviated syntax, 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>
+<s3 title="1. Declare the xalan namespace">
+<p><br/><code>xmlns:xalan="http://xml.apache.org/xalan";</code></p>
+<p>The xalan namespace provides support for the xalan:component element and
xalan:script subelement.</p>
+<note>The old namespace http://xml.apache.org/xslt is still supported for backward
compatibility.</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 an
arbitrary (but unique) string that matches the value of the prefix attribute of an
lxslt:component element in the stylesheet.<br/>
+<p>The <ref>prefix</ref> identifies the namespace, and <ref>URI</ref> is an
arbitrary (but unique) string that matches the value of the prefix attribute of an
xalan:component element in the stylesheet.<br/>
Example: <code>xmlns:ext1="xyz"</code><br/><br/></p>
</s3>
<s3 title="3. If you are using extension elements, designate the extension element
prefixes">
@@ -218,42 +219,42 @@
<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="5. Set up an lxslt:component">
-<p><br/>In the scope of the lxslt namespace declaration:</p>
-<p><code><lxslt:component prefix="<ref>prefix</ref>" </code><br/>
+<s3 title="5. Set up an xalan:component">
+<p><br/>In the scope of the xalan namespace declaration:</p>
+<p><code><xalan: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 the component is implemented in Java, the values of the
<code>functions</code> and <code>elements</code> attributes are ignored. The
function-available and element-available functions use reflection to examine the
actual Java methods.</note>
+ <code> <!--See xalan:script below--></code><br/>
+ <code></xalan: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 xalan:component
is actually available.</p>
+<note>If the component is implemented in Java, the values of the functions and
elements attributes are ignored. The function-available and element-available
functions use reflection to examine the actual Java methods.</note>
</s3>
<anchor name="setup-script"/>
-<s3 title="6. Set up the lxslt:script element">
-<p><br/>In each lxslt:component, you must include exactly one lxslt:script element.
If the extension is implemented in JavaScript:</p>
-<p><code><lxslt:script lang="javascript" ></code><br/>
+<s3 title="6. Set up the xalan:script element">
+<p><br/>In each xalan:component, you must include exactly one xalan:script element.
If the extension is implemented in JavaScript:</p>
+<p><code><xalan:script lang="javascript" ></code><br/>
<code> <!--The implementation script--></code><br/>
-<code></lxslt:script></code></p>
+<code></xalan: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>
-<p>If the extension is implemented in Java, you have three choices for the format
of the src attribute in the lxslt:script element.</p>
-<p><code><lxslt:script lang="javaclass" src="xalan://<ref>FQCN</ref>"/></code>
+<p>If the extension is implemented in Java, you have three choices for the format
of the src attribute in the xalan:script element.</p>
+<p><code><xalan:script lang="javaclass" src="xalan://<ref>FQCN</ref>"/></code>
<br/>where <ref>FQCN</ref> is the fully qualified class name.
-<br/>Example: <code><lxslt:script lang="javaclass"
src="xalan://java.util.Hashtable"/></code></p>
-<p><code><lxslt:script lang="javaclass" src="xalan://<ref>PJPN</ref>"/></code>
+<br/>Example: <code><xalan:script lang="javaclass"
src="xalan://java.util.Hashtable"/></code></p>
+<p><code><xalan:script lang="javaclass" src="xalan://<ref>PJPN</ref>"/></code>
<br/>where <ref>PJPN</ref> is the beginning of or the complete name of a java
package.
-<br/>Example: <code><lxslt:script lang="javaclass"
src="java.util"/></code></p>
-<p><code><lxslt:script lang="javaclass"
src="http://xml.apache.org/xslt/java"/></code></p>
+<br/>Example: <code><xalan:script lang="javaclass"
src="java.util"/></code></p>
+<p><code><xalan:script lang="javaclass"
src="http://xml.apache.org/xalan/java"/></code></p>
<p>The different formats for the value of the src attribute when using Java
extensions are more fully explained in <link anchor="java-namespace-declare">Declare
the namespace</link>.</p>
</s3>
-<s3 title="Implicit DTD for lxslt:component">
-<source><!ELEMENT lxslt:component (lxslt:script)>
-<!ATTLIST lxslt:component
+<s3 title="Implicit DTD for xalan:component">
+<source><!ELEMENT xalan:component (xalan:script)>
+<!ATTLIST xalan:component
prefix CDATA #REQUIRED
elements NMTOKENS #IMPLIED
functions NMTOKENS #IMPLIED>
-<!ELEMENT lxslt:script (#PCDATA | EMPTY)?>
-<!ATTLIST lxslt:script
+<!ELEMENT xalan:script (#PCDATA | EMPTY)?>
+<!ATTLIST xalan:script
lang CDATA #REQUIRED
src CDATA #IMPLIED></source>
</s3>
@@ -499,7 +500,7 @@
</s3>
</s2><anchor name="java-namespace"/>
<s2 title="Alternative: using the abbreviated syntax for extensions implemented in
Java">
-<p>For extension functions and extension elements implemented in Java, &xslt4j;
permits an abbreviated syntax. When you use the abbreviated syntax, you do not use an
lxslt:component to designate the functions.</p>
+<p>For extension functions and extension elements implemented in Java, &xslt4j;
permits an abbreviated syntax. When you use the abbreviated syntax, you do not use an
xalan:component to designate the functions.</p>
<p>The abbreviated syntax supports the use of extension functions and extension
elements implemented in Java. You cannot use this syntax with extensions implemented
in JavaScript or another scripting language.</p>
<anchor name="java-namespace-declare"/>
<s3 title="Declare the namespace">
@@ -512,15 +513,17 @@
<p>where <ref>PJPN</ref> is a partial java package name. That is, it is the
beginning of or the complete name of a java package.
<br/>Examples: <code>xmlns:my-package="xalan://java.util"</code>
<br/> <code>xmlns:my-package="xalan://mypackage"</code></p>
-<p><em>Java format:</em>
<code>xmlns:java="http://xml.apache.org/xslt/java";</code></p>
+<p><em>Java format:</em>
<code>xmlns:java="http://xml.apache.org/xalan/java";</code></p>
+<note>The old namespace http://xml.apache.org/xslt/java is still supported for
backward compatibility.</note>
<note>Although the namespace declarations for the class and package formats are
shown with the xalan:// prefix, the current implementation for those formats will
simply use the string to the right of the rightmost forward slash as the Java class
name. This format, however, is the preferred format for extension namespace
declarations.</note>
<note>The class: prefix which was sometimes required in earlier versions of
&xslt4j; is no longer required.</note>
-<note>These formats are also available when coding the src attribute of the
lxslt:script element as explained in <link anchor="setup-script">Set up the
lxslt:script element</link>.</note>
+<note>These formats are also available when coding the src attribute of the
xalan:script element as explained in <link anchor="setup-script">Set up the
xalan:script element</link>.</note>
</s3>
<s3 title="Use the namespace when you make extension calls">
<p>Use the declared prefix with the syntax described in <link
anchor="ext-func-calls">Extension function Java calls</link>.</p>
-<p>That is all. You do not include an lxslt:component element. Using the
abbreviated syntax clearly involves less setup than using the
lxslt:component/lxslt:script approach.</p>
-<note>We recommend that, for extensions coded in Java, the abbreviated syntax
should always be used since the lxslt:component/lxslt:script constructs add no
functionality.</note>
+<p>That is all. You do not include an xalan:component element. Using the
abbreviated syntax clearly involves less setup than using the
xalan:component/xalan:script approach.</p>
+<note>We recommend that, for extensions coded in Java, the abbreviated syntax
should always be used since the xalan:component/xalan:script constructs add no
functionality.</note>
+<note>The abbreviated syntax is supported in XSLTC, but the
xalan:component/xalan:script constructs are not.</note>
</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>
@@ -562,7 +565,7 @@
<xsl:stylesheet
xmlns:xsl="http://www.w3.org/1999/XSL/Transform";
version="1.0"
- xmlns:java="http://xml.apache.org/xslt/java";
+ xmlns:java="http://xml.apache.org/xalan/java";
exclude-result-prefixes="java">
<!--Other templates for transforming the rest of
@@ -652,15 +655,15 @@
<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:xalan="http://xml.apache.org/xalan";
xmlns:counter="MyCounter"
extension-element-prefixes="counter"
version="1.0">
- <lxslt:component prefix="counter"
+ <xalan:component prefix="counter"
elements="init incr" functions="read">
- <lxslt:script lang="javaclass" src="xalan://MyCounter"/>
- </lxslt:component>
+ <xalan:script lang="javaclass" src="xalan://MyCounter"/>
+ </xalan:component>
<xsl:template match="/">
<HTML>
@@ -703,14 +706,14 @@
<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:xalan="http://xml.apache.org/xalan";
xmlns:counter="MyCounter"
extension-element-prefixes="counter"
version="1.0">
- <lxslt:component prefix="counter"
+ <xalan:component prefix="counter"
elements="init incr" functions="read">
- <lxslt:script lang="javascript">
+ <xalan:script lang="javascript">
var counters = new Array();
function init (xslproc, elem) {
@@ -731,8 +734,8 @@
counters[name]++;
return null;
}
- </lxslt:script>
- </lxslt:component>
+ </xalan:script>
+ </xalan:component>
<xsl:template match="/">
<HTML>
1.26 +46 -76 xml-xalan/java/xdocs/sources/xalan/extensionslib.xml
Index: extensionslib.xml
===================================================================
RCS file: /home/cvs/xml-xalan/java/xdocs/sources/xalan/extensionslib.xml,v
retrieving revision 1.25
retrieving revision 1.26
diff -u -r1.25 -r1.26
--- extensionslib.xml 13 Jun 2002 19:15:02 -0000 1.25
+++ extensionslib.xml 28 Oct 2002 20:46:31 -0000 1.26
@@ -63,21 +63,11 @@
<li><link anchor="xalanns">&xslt; namespace</link></li>
<li><link anchor="redirect">Redirect</link></li>
<li><link anchor="nodeset">nodeset</link></li>
-<li><link anchor="intersection">intersection</link></li>
-<li><link anchor="difference">difference</link></li>
-<li><link anchor="distinct">distinct</link></li>
-<li><link anchor="hassamenodes">hasSameNodes</link></li>
<li><link anchor="nodeinfo">NodeInfo extension functions</link></li>
<li><link anchor="sql">SQL library</link></li>
<li><link anchor="pipedocument">PipeDocument</link></li>
<li><link anchor="evaluate">evaluate</link></li>
<li><link anchor="tokenize">tokenize</link></li>
-<li><link anchor="groupitem">group and item</link> <ref>(to be done)</ref></li>
-<li><link anchor="type">type</link> <ref>(to be done)</ref></li>
-<li><link anchor="todate">toDate</link> <ref>(to be done)</ref></li>
-<li><link anchor="formatdate">formatDate</link> <ref>(to be done)</ref></li>
-<li><link anchor="grep">grep</link> <ref>(to be done)</ref></li>
-<li><link anchor="foreachtoken">forEachToken</link> <ref>(to be done)</ref></li>
<li>Examples: <link anchor="ex-redirect">Redirect</link>, <link
anchor="ex-nodeset">nodeset</link>, <link anchor="ex-sql">SQL library</link></li>
</ul><anchor name="intro"/>
<s2 title= "Introduction">
@@ -88,31 +78,36 @@
</s2><anchor name="exslt"/>
<s2 title="EXSLT extensions">
<p>&xslt4j; supports the <jump href="http://exslt.org/";>EXSLT</jump> initiative to
provide a set of
-standard extension functions and elements to XSLT users. &xslt4j; 2.3.2 includes
implementations for 12 EXSLT
-functions (some are calls to extension already in the Xalan namespace). For the
details, see:</p>
+standard extension functions and elements to XSLT users. &xslt4j; includes
implementations for the following EXSLT
+extension modules:</p>
<ul>
<li><jump href="apidocs/org/apache/xalan/lib/ExsltCommon.html">EXSLT common
functions</jump></li>
<li><jump href="apidocs/org/apache/xalan/lib/ExsltMath.html">EXSLT math
functions</jump></li>
-<li><jump href="apidocs/org/apache/xalan/lib/ExsltSets.html">EXSLT set
function</jump></li>
-<li><jump href="apidocs/org/apache/xalan/lib/ExsltDatetime.html">EXSLT
date-and-time function</jump></li>
+<li><jump href="apidocs/org/apache/xalan/lib/ExsltSets.html">EXSLT set
functions</jump></li>
+<li><jump href="apidocs/org/apache/xalan/lib/ExsltDatetime.html">EXSLT
date-and-time functions</jump></li>
+<li><jump href="apidocs/org/apache/xalan/lib/ExsltDynamic.html">EXSLT dynamic
functions</jump></li>
+<li><jump href="apidocs/org/apache/xalan/lib/ExsltStrings.html">EXSLT string
functions</jump></li>
<li>The EXSLT func:function and func:result elements (see <jump
href="http://www.exslt.org/func/elements/function/index.html";>EXSLT -
func:function)</jump></li>
</ul>
-<p>Work is currently underway on <jump
href="http://www.exslt.org/date/index.html";>EXSLT date and time functions</jump>
-and <jump href="http://www.exslt.org/func/index.html";>and user defined EXSLT
functions (with the function and result
-elements)</jump>. Anyone who would like to help by implementating other EXSLT
extensions is more than welcome. Please email us at the <human-resource-ref
idref="xalandev"/>.</p>
+<p>All EXSLT extensions use namespaces specified in the EXSLT specification. For
example, to use the EXSLT math functions, specify a namespace URI as follows:</p>
+<p> <code>xmlns:math="http://exslt.org/math";</code></p>
+<p>Anyone who would like to help by implementating other EXSLT extensions is more
than welcome. Please email us at the <human-resource-ref idref="xalandev"/>.</p>
</s2>
<anchor name="xalanns"/>
<s2 title="&xslt; namespace">
-<p>Where it makes sense, we are placing the new &xslt; extensions in the
org.apache.xalan.lib.Extensions class and we have defined a namespace for this
class:</p>
+<p>The &xslt; extensions are implemented in one of the classes under
org.apache.xalan.lib. The main extension class is <jump
href="apidocs/org/apache/xalan/lib/Extensions.html">org.apache.xalan.lib.Extensions</jump>.
Some extension
+functions (e.g. intersection, difference, etc.) used to be in this class are now
moved to the corresponding <link anchor="exslt">EXSLT</link> modules. All &xslt;
extensions use namespace URIs starting with:</p>
<p> <code>http://xml.apache.org/xalan</code></p>
-<p>If you are calling &xslt4j;-supplied extensions, we recommend that you define
this namespace in your stylesheet element, and call the extension using the namespace
prefix that you have associated with that namespace. That way, if we later reorganize
how the &xslt4j;-supplied extensions are stored, you won't have to modify your
stylesheet.</p>
+<p>If you are calling &xslt4j;-supplied extensions, we recommend that you define
the corresponding namespace in your stylesheet, and call the extension using the
namespace prefix that you have associated with that namespace. That way, if we later
reorganize how the &xslt4j;-supplied extensions are stored, you won't have to modify
your stylesheet.</p>
<p>For an example that uses this namespace, see <link anchor="ex-nodeset">Example
with the nodeset extension function</link>.</p>
</s2><anchor name="redirect"/>
<s2 title= "Redirect">
<p>A standard XSL transformation involves an XSL stylesheet, an XML source tree,
and the transformation result tree. The transformation sends the entire result to a
single <jump href="apidocs/org/apache/trax/Result.html">org.apache.trax.Result</jump>
object.</p>
-<p>The Redirect extension
-(<jump
href="apidocs/org/apache/xalan/xslt/extensions/Redirect.html">org.apache.xalan.xslt.extensions.Redirect</jump>)
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>
+<p>The namespace for the <jump
href="apidocs/org/apache/xalan/lib/Redirect.html">Redirect</jump> extension is:</p>
+<p> <code>http://xml.apache.org/xalan/redirect</code></p>
+<p>It 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>The <open> and <write> elements include 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>
+<p>The <open> and <write> elements also support an append attribute. If
the append attribute is set to true or yes, then the result is appended to the output
file.</p>
<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>
@@ -130,8 +125,7 @@
<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"
+ xmlns:redirect="http://xml.apache.org/xalan/redirect";
extension-element-prefixes="redirect">
<xsl:template match="/">
@@ -181,6 +175,7 @@
<s2 title= "nodeset">
<p>Implemented in <jump
href="apidocs/org/apache/xalan/lib/Extensions.html">org.apache.xalan.lib.Extensions</jump>,<br/>
<code>nodeset (result-tree-fragment)</code> casts a result tree fragment into a
node-set.</p>
+<p>To use the nodeset extension, you can either use the <code>nodeset</code>
function in the namespace <code>xmlns:xalan="http://xml.apache.org";</code> or the
<link anchor="exslt">EXSLT</link> extension function <code>node-set</code> in the
namespace <code>xmlns:common="http://exslt.org/common";</code>.</p>
<note>When you bind a variable to a template, rather than to the value generated by
a select expression, the data type of the variable is result tree fragment. For more
information, see <jump
href="http://www.w3.org/TR/xslt#section-Result-Tree-Fragments";>Result Tree
Fragments</jump>.</note>
<anchor name="ex-nodeset"/>
<s3 title="Example with the nodeset extension function">
@@ -214,24 +209,8 @@
<note>For illustration purposes, the preceding stylesheet pays no attention to the
structure and content of the XML input document. Instead, it processes the template
(in the stylesheet) bound to the variable named rtf.</note>
</s3>
-</s2><anchor name="intersection"/>
-<s2 title="intersection">
-<p>Implemented in <jump
href="apidocs/org/apache/xalan/lib/Extensions.html">org.apache.xalan.lib.Extensions</jump>,<br/>
-<code>intersection (node-set1, node-set2)</code> function returns a node-set with
all nodes that are in ns1 and in ns2 .</p>
-</s2><anchor name="difference"/>
-<s2 title= "difference">
-<p>Implemented in <jump
href="apidocs/org/apache/xalan/lib/Extensions.html">org.apache.xalan.lib.Extensions</jump>,<br/>
-<code>difference(node-set1, node-set2)</code> returns a node-set with the nodes in
node-set1 and not in node-set2.</p>
-</s2><anchor name="distinct"/>
-<s2 title= "distinct">
- <p>Implemented in <jump
href="apidocs/org/apache/xalan/lib/Extensions.html">org.apache.xalan.lib.Extensions</jump>,<br/>
- distinct (node-set) returns a node-set containing nodes with distinct string
values. If more than one node in the node-set
- contains the same text node value, distinct only returns the first of these nodes
that it finds.</p>
-</s2><anchor name="hassamenodes"/>
-<s2 title= "hasSameNodes">
-<p>Implemented in <jump
href="apidocs/org/apache/xalan/lib/Extensions.html">org.apache.xalan.lib.Extensions</jump>,<br/>
-<code>hasSameNodes(node-set1, node-set2)</code> returns true if both node-set1 and
node-set2 contain exactly the same set of nodes.</p>
-</s2><anchor name="nodeinfo"/>
+</s2>
+<anchor name="nodeinfo"/>
<s2 title="NodeInfo">
<p><jump
href="apidocs/org/apache/xalan/lib/NodeInfo.html">org.apache.xalan.lib.NodeInfo</jump>
provides extension elements that you can
use to get information about the location of nodes in the source document:</p>
@@ -247,24 +226,24 @@
method to set this attribute.</note>
<anchor name="systemid"/>
<s3 title="systemId">
-<p>Implemented in <jump
href="apidocs/org/apache/xalan/lib/NodeInfo.html">org.apache.xalan.lib.NodeInfo</jump>,<br/>
-<code>systemId()</code> returns the system ID for the current node, and <br/>
+<p>Implemented in <jump
href="apidocs/org/apache/xalan/lib/NodeInfo.html">org.apache.xalan.lib.NodeInfo</jump>,
+<code>systemId()</code> returns the system ID for the current node, and
<code>systemId(node-set)</code> returns the system ID of the first node in the
node-set.</p>
</s3><anchor name="publicid"/>
<s3 title="publicId">
-<p><em>To be done.</em> Implemented in <jump
href="apidocs/org/apache/xalan/lib/NodeInfo.html">org.apache.xalan.lib.NodeInfo</jump>,<br/>
-<code>publicId()</code> will return the public ID for the current node, and<br/>
+<p><em>To be done.</em> Implemented in <jump
href="apidocs/org/apache/xalan/lib/NodeInfo.html">org.apache.xalan.lib.NodeInfo</jump>,
+<code>publicId()</code> will return the public ID for the current node, and
<code>publicId(node-set)</code> will return the public ID of the first node in the
node-set.</p>
</s3><anchor name="linenumber"/>
<s3 title="lineNumber">
-<p>Implemented in <jump
href="apidocs/org/apache/xalan/lib/NodeInfo.html">org.apache.xalan.lib.NodeInfo</jump>,<br/>
-<code>lineNumber()</code> returns the line number in the source document for the
current node, and<br/>
+<p>Implemented in <jump
href="apidocs/org/apache/xalan/lib/NodeInfo.html">org.apache.xalan.lib.NodeInfo</jump>,
+<code>lineNumber()</code> returns the line number in the source document for the
current node, and
<code>lineNumber(node-set)</code> returns the line number in the source document
for the first node in the node-set.</p>
<note>This function returns -1 if the line number is not known (for example, the
source is a DOM Document).</note>
</s3><anchor name="columnnumber"/>
<s3 title="columnNumber">
-<p>Implemented in <jump
href="apidocs/org/apache/xalan/lib/NodeInfo.html">org.apache.xalan.lib.NodeInfo</jump>,<br/>
-<code>columnNumber()</code> returns the column number in the source document for
the current node, and<br/>
+<p>Implemented in <jump
href="apidocs/org/apache/xalan/lib/NodeInfo.html">org.apache.xalan.lib.NodeInfo</jump>,
+<code>columnNumber()</code> returns the column number in the source document for
the current node, and
<code>columnNumber(node-set)</code> returns the column number in the source
document for the first node in the node-set.</p>
<note>This function returns -1 if the column number is not known (for example, the
source is a DOM Document).</note>
</s3></s2><anchor name="sql"/>
@@ -276,7 +255,9 @@
<li><link anchor="ex-sql">SQL library example</link></li>
<li><link idref="samples" anchor="sql">SQL library sample applications</link></li>
</ul>
-<p>Provides extension functions for connecting to a JDBC data source, executing a
query,
+<p>The namespace for the SQL extension is:</p>
+<p> <code>http://xml.apache.org/xalan/sql</code></p>
+<p>The SQL extension provides extension functions for connecting to a JDBC data
source, executing a query,
and working incrementally through a "streamable" result set. Streaming (reuse of a
single row node to traverse the result set) is the default mode of operation. If you
want unlimited access to the entire result set, you can cache the query result set (1
row node for each row in the result set).</p>
<p><em>If you use streaming mode (the default), you can only access row elements
one at a time moving forward through the result set. The use of XPath expressions in
your stylesheet, for example, that attempt to return nodes from the result set in any
other manner may produce unpredictable results.</em></p>
<note>Many features of the SQL library, including support for connection pools,
parameterized queries, caching, and added support for extracting connection
information and query parameters from XML source documents exist thanks to John
Gentilin ([EMAIL PROTECTED]), who has also added a number of <link
idref="samples" anchor="sql">SQL library samples</link>.</note>
@@ -319,7 +300,7 @@
<p>In the stylesheet, you can extract this information as follows:</p>
<source><xsl:stylesheet version 1.0
xmlns:xsl="http://www.w3.org/1999/XSL/Transform";
- xmlns:sql="org.apache.xalan.lib.sql.XConnection"
+ xmlns:sql="http://xml.apache.org/xalan/sql";
extension-element-prefixes="sql">
<xsl:param name="cinfo" select="//DBINFO"/>
<xsl:variable name="db" select="sql:new($cinfo)"/>
@@ -343,7 +324,7 @@
<p>A stylesheet can use this connection pool as follows:</p>
<source><xsl:stylesheet version 1.0
xmlns:xsl="http://www.w3.org/1999/XSL/Transform";
- xmlns:sql="org.apache.xalan.lib.sql.XConnection"
+ xmlns:sql="http://xml.apache.org/xalan/sql";
extension-element-prefixes="sql">
...
<xsl:variable name="db" select="sql:new($driver, 'extpool')"/></source>
@@ -370,7 +351,7 @@
<source><?xml version="1.0"?>
<xsl:stylesheet xmlns:xsl="http://www.w3.org/1999/XSL/Transform";
version="1.0"
- xmlns:sql="org.apache.xalan.lib.sql.XConnection"
+ xmlns:sql="http://xml.apache.org/xalan/sql";
extension-element-prefixes="sql">
<xsl:output method="html" indent="yes"/>
<xsl:param name="query" select="'SELECT * FROM import1'"/>
@@ -424,7 +405,9 @@
<p>Implemented in <jump
href="apidocs/org/apache/xalan/lib/PipeDocument.html">org.apache.xalan.lib.PipeDocument</jump>,<br/>
the pipeDocument extension element pipes an XML document through a series of one
or more transformations. The output of
each transformation is piped to the next transformation. The final transofrmation
creates a target file.</p>
-
+ <p>The namespace for the pipeDocument extension is:</p>
+
<p> <code>http://xml.apache.org/xalan/PipeDocument</code></p>
+
<p>Suppose, for example,you have a stylesheet that is processing a "book"
document with elements designating the
documents to be transformed. This primary stylesheet generates a table of
contents for the book. For each source
document it uses a pipeDocument extension element to pipe the document through a
series of one or more transformations.</p>
@@ -437,7 +420,7 @@
and contains a parameter designating where the output files are to be
placed:</p>
<source><xsl:stylesheet version="1.0"
xmlns:xsl="http://www.w3.org/1999/XSL/Transform";
- xmlns:pipe="xalan://PipeDocument"
+ xmlns:pipe="http://xml.apache.org/xalan/PipeDocument";
extension-element-prefixes="pipe">
<xsl:param name="destdir" value="html/output">
@@ -482,7 +465,7 @@
<xsl:stylesheet version="1.0"
xmlns:xsl="http://www.w3.org/1999/XSL/Transform";
- xmlns:pipe="xalan://org.apache.xalan.lib.PipeDocument"
+ xmlns:pipe="http://xml.apache.org/xalan/PipeDocument";
extension-element-prefixes="pipe">
<xsl:param name="source"/>
@@ -508,6 +491,9 @@
<code>evaluate (xpath-expression)</code> function returns the result of evaluating
the xpath-expression in the current
XPath expression context (automatically passed in by the extension mechanism).</p>
<p>Use the evaluation extension function when the value of the expression is not
known until run time.</p>
+<note>Although you can still use the evaluate extension function in the main
Extensions class, the preferred solution
+is to use the same function in the EXSLT dynamic package. This will make your
stylesheet more portable across XSLT
+processors that support EXSLT extensions.</note>
</s2><anchor name="tokenize"/>
<s2 title="tokenize">
<p>Implemented in <jump
href="apidocs/org/apache/xalan/lib/Extensions.html">org.apache.xalan.lib.Extensions</jump>,<br/>
@@ -517,24 +503,8 @@
<p>The delimiters determine which characters are used to divide the tokenize-string
into individual tokens. If you do not include
the delimiters argument, the function uses tab (&#x09), linefeed (&#x0A),
return (&#x0D), and space (&#x20) as delimiters.
If tokenize-string is an empty string or contains only delimiters, the result is an
empty node-set.</p>
-</s2><anchor name="groupitem"/>
-<s2 title= "group and item">
-<p><em>To be done.</em> Provides efficient grouping of items with a common
value.</p>
-</s2><anchor name="type"/>
-<s2 title= "type">
-<p><em>To be done.</em> Returns a string that represents the Schema or DTD type.</p>
-</s2><anchor name="todate"/>
-<s2 title="to-date">
-<p><em>To be done.</em> Takes a string as input, and returns a long value
representing the date.</p>
-</s2><anchor name="formatdate"/>
-<s2 title="format-date">
-<p><em>To be done.</em> Takes a date string, and formats it according to a
specification.</p>
-</s2><anchor name="grep"/>
-<s2 title="grep">
-<p><em>To be done.</em> Performs a grep function and returns the substring.</p>
-</s2><anchor name="foreachtoken"/>
-<s2 title="for-each-token">
-<p><em>To be done.</em> Tokenizes a string, treats each token as a DOM Text node,
and executes the
-sub-template.</p>
+<note>Although you can still use the tokenize extension function in the main
Extensions class, the preferred solution
+is to use the same function in the EXSLT strings package. This will make your
stylesheet more portable across XSLT
+processors that support EXSLT extensions.</note>
</s2>
</s1>
1.47 +24 -24 xml-xalan/java/xdocs/sources/xalan/samples.xml
Index: samples.xml
===================================================================
RCS file: /home/cvs/xml-xalan/java/xdocs/sources/xalan/samples.xml,v
retrieving revision 1.46
retrieving revision 1.47
diff -u -r1.46 -r1.47
--- samples.xml 14 Feb 2002 16:12:28 -0000 1.46
+++ samples.xml 28 Oct 2002 20:46:31 -0000 1.47
@@ -350,27 +350,27 @@
<s2 title="SQL library extensions">
<p>The <link idref="extensionslib" anchor="sql">SQL library </link> extension
enables you to execute SQL queries from within a stylesheet,
and to incorporate query result sets in the XML output. To use the SQL
library, you need
- a JDBC driver, the underying DBMS, and a database. Our samples use
Lutris® InstantDB, available "free of charge for research and
- development use."</p><anchor name="instantdbsetup"/>
- <s3 title="Setting up the InstantDB samples">
+ a JDBC driver, the underlying DBMS, and a database. Our samples use
Lutris® InstantDB.
+ You can also customize the stylesheets for your own database
implementations.</p>
+ <anchor name="dbsetup"/>
+ <s3 title="Setting up the SQL extension samples">
<p>To run the SQL library extension samples, do the following:</p>
<ol>
- <li>Obtain a copy of InstantDB. You can download a free "Development license"
copy for research and development from
- <jump href="http://www.lutris.com/downloads/index.html";>Lutris
Downloads</jump>.<br/><br/></li>
- <li>Follow the instructions Lutris provides for installing InstantDB and
generating the sample database.<br/><br/></li>
- <li>Add idb.jar and the Java Transaction API JAR (jta-spec1_0_1.jar in the
InstantDB 4.0 release) to the system class path.<br/><br/></li>
- <li>Create an instantdb directory in the samples/extensions subdirectory, and
copy the sample database to instantdb. The sample database
- is in the Examples subdirectory where you installed InstantDB. For our
purposes, it includes samples.prp and three subdirectories:
- indexes, system, and tables.<br/><br/>
- Alternative: You can adjust the references to samples.prp in the XSL
stylesheets and XML document dburl nodes to point to sample.prp in
- its original location, in which case you do not need to copy the samples
database. For example, if you have installed InstantDB in /idb,
- you can change 'jdbc:idb:./instantdb/sample.prp' in the XConnection new()
call in extensions/6-sqllib-instantdb to
- 'jdbc:idb:/idb/Examples/sample.prp'.<br/><br/></li>
+ <li>InstantDB is no longer freely available. If you still have a copy of it,
+ you can follow the instructions Lutris provides for installing InstantDB and
generating the sample database.</li>
+ <li>For other database implementations, you have to customize the stylesheets
by modifying the SQL query, the JDBC driver name and the database url:
+ <ul>
+ <li>Modify the SQL query to your own needs. The SQL query is defined in a
parameter like
+ <code><xsl:param name="query" select="'SELECT * FROM
import1'"/></code>.</li>
+ <li>Modify the JDBC driver name and the database url. They are specified
in the stylesheets as parameters for some
+ examples. For other examples the parameters are defined in the dbinfo.xml
file.</li>
+ </ul>
+ </li>
+ <li>Add the JDBC driver jar to the system class path.</li>
+ <li>Create the database you want to work with if it does not already
exist.</li>
</ol>
- <p>For more information about InstantDB, see the <jump
href="http://www.lutris.com/products/instantDB/software/documentation/";>InstantDB
- Documentation</jump>.</p>
</s3>
- <s3 title="SQL Library samples with InstantDB">
+ <s3 title="SQL Library samples">
<ul>
<li><link anchor="ext6">6-sqllib-instantdb</link></li>
<li><link anchor="basic-conn">Basic Connections</link></li>
@@ -380,13 +380,13 @@
<li><link anchor="showerror">Show-error</link></li>
</ul>
<note>Except for 6-sqllib-instantdb, all these samples have been created by
John Gentilin
- ([EMAIL PROTECTED]) to take illustrate the rich feature set he has
contributed to the SQL Library.
+ ([EMAIL PROTECTED]) to illustrate the rich feature set he has
contributed to the SQL Library.
To run each of these samples, be sure you are in the appropriate
extensions/sql subdirectory.</note>
</s3><anchor name="ext6"/>
<s3 title="6-sqllib-instantdb">
<p>What it does: Uses the SQL library XConnection extension to connect to the
InstantDB sample database,
performs a query, and returns the query result in an HTML table.</p>
- <p><link anchor="instantdbsetup">Set up InstantDB</link>, and run this sample
from the extensions subdirectory:</p>
+ <p><link anchor="dbsetup">Set up the database</link>, and run this sample
from the extensions subdirectory:</p>
<p><code>java org.apache.xalan.xslt.Process</code>
<br/> <code>-xsl 6-sqllib-instantdb.xsl -out
import1.html</code></p>
</s3><anchor name="basic-conn"/>
@@ -398,7 +398,7 @@
in the form of stylesheet parameters.</p>
<p>The second strategy is to get connection information from a nodeset in an
XML source document (dbInfo.xml).</p>
- <p><link anchor="instantdbsetup">Set up InstantDB</link>, and run this sample
from the extensions/sql/basic-connection
+ <p><link anchor="dbsetup">Set up the database</link>, and run this sample
from the extensions/sql/basic-connection
directory.</p>
<p>1. To get connection information from the stylesheet:</p>
<p><code>java org.apache.xalan.xslt.Process</code>
@@ -418,7 +418,7 @@
XConnection object and connect to a datasouce.</p>
<p>The stylesheet uses this named connection pool to instantiate an XConnection
object and connect to the datasource.
The ExternalConnection class is in xalansamples.jar.</p>
- <p><link anchor="instantdbsetup">Set up InstantDB</link>, be sure
xalanxamples.jar is on the class path, and run this
+ <p><link anchor="dbsetup">Set up the database</link>, be sure xalanxamples.jar
is on the class path, and run this
sample from the extensions/sql/ext-connection directory:</p>
<p><code>java ExternalConnection</code></p>
<p>ExternalConnection creates the ConnectionPool, and performs a transformation
with dbtest.xsl, which draws
@@ -431,7 +431,7 @@
provides the parameter value as well as the connection information. The
parameter value is in a node in the XML source.</p>
<p>The stylesheet gets the required connection and parameter information from
the XML source, sets up and executes the
parameterized query, and retuns the query result set.</p>
- <p><link anchor="instantdbsetup">Set up InstantDB</link>, and run this sample
from the sql/pquery subdirectory:</p>
+ <p><link anchor="dbsetup">Set up the database</link>, and run this sample from
the sql/pquery subdirectory:</p>
<p><code>java org.apache.xalan.xslt.Process -in dbInfo.xml</code>
<br/><code>-xsl dbTest.xsl -out dbTest.html</code></p>
</s3><anchor name="streamable"/>
@@ -439,7 +439,7 @@
<p><em>Contributed by John Gentilin ([EMAIL PROTECTED]).</em></p>
<p>What it does: Illustrates enabling and disabling of caching the streamable
result set returned by a query.</p>
<p>The stylesheets use the XConnection enableCacheNodes() and
disableCacheNodes() methods.</p>
- <p><link anchor="instantdbsetup">Set up InstantDB</link>, and run these samples
from the sql/streamable subdirectory.</p>
+ <p><link anchor="dbsetup">Set up the database</link>, and run these samples
from the sql/streamable subdirectory.</p>
<p>1. To turn caching on:</p>
<p><code>java org.apache.xalan.xslt.Process</code>
<br/><code>-xsl cachedNodes.xsl</code></p>
@@ -455,7 +455,7 @@
<source><xsl:variable name="table" select='sql:query($db, $query)'/>
<xsl:apply-templates select="$table/row-set" />
<xsl:apply-templates select="$table/ext-error"/></source>
- <p><link anchor="instantdbsetup">Set up InstantDB</link>, and run this sample
from the extensions/sql/show-error subdirectory:</p>
+ <p><link anchor="dbsetup">Set up the database</link>, and run this sample from
the extensions/sql/show-error subdirectory:</p>
<p><code>java org.apache.xalan.xslt.Process</code>
<br/><code> -xsl <ref>invalidSomething.xsl</ref> -out dbtestout.html</code></p>
<p>where <ref>invalidSomething.xsl</ref> is <code>invalidConn.xsl</code>
(specifies a database that does not exist),
---------------------------------------------------------------------
To unsubscribe, e-mail: [EMAIL PROTECTED]
For additional commands, e-mail: [EMAIL PROTECTED]
