You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@xalan.apache.org by mk...@apache.org on 2002/10/28 21:46:31 UTC
cvs commit: xml-xalan/java/xdocs/sources/xalan extensions.xml extensionslib.xml samples.xml
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 (johnglinux@eyecatching.com), 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
- (johnglinux@eyecatching.com) to take illustrate the rich feature set he has contributed to the SQL Library.
+ (johnglinux@eyecatching.com) 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 (johnglinux@eyecatching.com).</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: xalan-cvs-unsubscribe@xml.apache.org
For additional commands, e-mail: xalan-cvs-help@xml.apache.org