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]
