<?xml version="1.0" encoding="ISO-8859-1" standalone="no"?> | |
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd"> | |
<html> | |
<head> | |
<title>ASF: Extensions library</title> | |
<meta http-equiv="content-type" content="text/html; charset=ISO-8859-1" /> | |
<meta http-equiv="Content-Style-Type" content="text/css" /> | |
<link rel="stylesheet" type="text/css" href="resources/apache-xalan.css" /> | |
</head> | |
<!-- | |
* Licensed to the Apache Software Foundation (ASF) under one | |
* or more contributor license agreements. See the NOTICE file | |
* distributed with this work for additional information | |
* regarding copyright ownership. The ASF licenses this file | |
* to you under the Apache License, Version 2.0 (the "License"); | |
* you may not use this file except in compliance with the License. | |
* You may obtain a copy of the License at | |
* | |
* http://www.apache.org/licenses/LICENSE-2.0 | |
* | |
* Unless required by applicable law or agreed to in writing, software | |
* distributed under the License is distributed on an "AS IS" BASIS, | |
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. | |
* See the License for the specific language governing permissions and | |
* limitations under the License. | |
--> | |
<body> | |
<div id="title"> | |
<table class="HdrTitle"> | |
<tbody> | |
<tr> | |
<th rowspan="2"> | |
<a href="../index.html"> | |
<img alt="Trademark Logo" src="resources/XalanJ-Logo-tm.png" width="190" height="90" /> | |
</a> | |
</th> | |
<th text-align="center" width="75%"> | |
<a href="index.html">Xalan XSL Transformer User's Guide</a> | |
</th> | |
</tr> | |
<tr> | |
<td valign="middle">Extensions library</td> | |
</tr> | |
</tbody> | |
</table> | |
<table class="HdrButtons" align="center" border="1"> | |
<tbody> | |
<tr> | |
<td> | |
<a href="http://www.apache.org">Apache Foundation</a> | |
</td> | |
<td> | |
<a href="http://xalan.apache.org">Xalan Project</a> | |
</td> | |
<td> | |
<a href="http://xerces.apache.org">Xerces Project</a> | |
</td> | |
<td> | |
<a href="http://www.w3.org/TR">Web Consortium</a> | |
</td> | |
<td> | |
<a href="http://www.oasis-open.org/standards">Oasis Open</a> | |
</td> | |
</tr> | |
</tbody> | |
</table> | |
</div> | |
<div id="navLeft"> | |
<ul> | |
<li> | |
<a href="resources.html">Resources</a> | |
<br /> | |
</li> | |
<li> | |
<a href="../index.html">Home</a> | |
</li></ul><hr /><ul> | |
<li> | |
<a href="index.html">Xalan-J 2.7.1</a> | |
</li> | |
<li> | |
<a href="charter.html">Charter</a> | |
</li></ul><hr /><ul> | |
<li> | |
<a href="whatsnew.html">What's New</a> | |
</li> | |
<li> | |
<a href="readme.html">Release Notes</a> | |
</li></ul><hr /><ul> | |
<li> | |
<a href="overview.html">Overview</a> | |
</li> | |
<li> | |
<a href="downloads.html">Download/Build</a> | |
</li> | |
<li> | |
<a href="getstarted.html">Getting Started</a> | |
</li> | |
<li> | |
<a href="xsltc_usage.html">Using XSLTC</a> | |
</li></ul><hr /><ul> | |
<li> | |
<a href="faq.html">FAQs</a> | |
</li></ul><hr /><ul> | |
<li> | |
<a href="samples.html">Sample Apps</a> | |
</li> | |
<li> | |
<a href="commandline.html">Command Line</a> | |
</li></ul><hr /><ul> | |
<li> | |
<a href="features.html">Features</a> | |
</li> | |
<li> | |
<a href="trax.html">Transform API</a> | |
</li> | |
<li> | |
<a href="xpath_apis.html">XPath API</a> | |
</li> | |
<li> | |
<a href="usagepatterns.html">Usage Patterns</a> | |
</li></ul><hr /><ul> | |
<li> | |
<a href="apidocs/index.html">Xalan-J API</a> | |
</li> | |
<li> | |
<a href="public_apis.html">Public APIs</a> | |
</li> | |
<li> | |
<a href="dtm.html">DTM</a> | |
</li></ul><hr /><ul> | |
<li> | |
<a href="extensions.html">Extensions</a> | |
</li> | |
<li>Extensions Library<br /> | |
</li> | |
<li> | |
<a href="extensions_xsltc.html">XSLTC Exts</a> | |
</li></ul><hr /><ul> | |
<li> | |
<a href="design/design2_0_0.html">Xalan 2 Design</a> | |
</li> | |
<li> | |
<a href="xsltc/index.html">XSLTC Design</a> | |
</li></ul><hr /><ul> | |
<li> | |
<a href="builds.html">Building a release</a> | |
</li> | |
<li> | |
<a href="http://xml.apache.org/xalan-j/test/overview.html">Testing</a> | |
</li> | |
<li> | |
<a href="bugreporting.html">Bug Reporting</a> | |
</li></ul><hr /><ul> | |
<li> | |
<a href="contact_us.html">Contact us</a> | |
</li> | |
</ul> | |
</div> | |
<div id="content"> | |
<h2>Extensions library</h2> | |
<ul> | |
<li> | |
<a href="#intro">Introduction</a> | |
</li> | |
<li> | |
<a href="#exslt">EXSLT extensions</a> | |
</li> | |
<li> | |
<a href="#xalanns">Xalan namespace</a> | |
</li> | |
<li> | |
<a href="#redirect">Redirect</a> | |
</li> | |
<li> | |
<a href="#nodeset">nodeset</a> | |
</li> | |
<li> | |
<a href="#nodeinfo">NodeInfo extension functions</a> | |
</li> | |
<li> | |
<a href="#sql">SQL library</a> | |
</li> | |
<li> | |
<a href="#pipedocument">PipeDocument</a> | |
</li> | |
<li> | |
<a href="#evaluate">evaluate</a> | |
</li> | |
<li> | |
<a href="#tokenize">tokenize</a> | |
</li> | |
<li> | |
<a href="extensions_xsltc.html">Extensions for XSLTC</a> | |
</li> | |
<li>Examples: <a href="#ex-redirect">Redirect</a>, <a href="#ex-nodeset">nodeset</a>, | |
<a href="#ex-sql">SQL library</a> | |
</li> | |
</ul> | |
<table class="note"> | |
<tr> | |
<td class="noteImg"> | |
<img src="resources/note.gif" alt="note" /> | |
</td> | |
<td class="noteTxt">Unless otherwise specified, the Xalan-Java extensions library discussed in this section refers to | |
the Xalan-Java Interpretive processor. See <a href="extensions_xsltc.html">Extensions for XSLTC</a> for | |
more information.</td> | |
</tr> | |
</table> | |
<br /> | |
<a name="intro">‌</a> | |
<p align="right" size="2"> | |
<a href="#content">(top)</a> | |
</p> | |
<h3>Introduction</h3> | |
<p>Extension elements and functions provide a powerful mechanism | |
for extending and simplifying what you can do with an XLST processor like | |
Xalan. With input and contributions from the XML open-source developer community, we are working on | |
placing the most useful extensions in an extensions library distributed with Xalan-Java. If you have | |
ideas and/or contributions you would like to make, please email us at | |
the <a href="mailto:xalan-dev@xml.apache.org">Xalan Development Mailing List</a>.</p> | |
<a name="exslt">‌</a> | |
<p align="right" size="2"> | |
<a href="#content">(top)</a> | |
</p> | |
<h3>EXSLT extensions</h3> | |
<p>Xalan-Java supports the <a href="http://exslt.org/">EXSLT</a> initiative to provide a set of | |
standard extension functions and elements to XSLT users. Xalan-Java includes implementations for the | |
following EXSLT extension modules:</p> | |
<ul> | |
<li> | |
<a href="apidocs/org/apache/xalan/lib/ExsltCommon.html">EXSLT common functions</a> | |
</li> | |
<li> | |
<a href="apidocs/org/apache/xalan/lib/ExsltMath.html">EXSLT math functions</a> | |
</li> | |
<li> | |
<a href="apidocs/org/apache/xalan/lib/ExsltSets.html">EXSLT set functions</a> | |
</li> | |
<li> | |
<a href="apidocs/org/apache/xalan/lib/ExsltDatetime.html">EXSLT date-and-time functions</a> | |
</li> | |
<li> | |
<a href="apidocs/org/apache/xalan/lib/ExsltDynamic.html">EXSLT dynamic functions</a> | |
</li> | |
<li> | |
<a href="apidocs/org/apache/xalan/lib/ExsltStrings.html">EXSLT string functions</a> | |
</li> | |
<li>The EXSLT func:function and func:result elements (see | |
<a href="http://www.exslt.org/func/elements/function/index.html">EXSLT - func:function)</a> | |
</li> | |
</ul> | |
<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 <a href="mailto:xalan-dev@xml.apache.org">Xalan Development Mailing List</a>.</p> | |
<a name="xalanns">‌</a> | |
<p align="right" size="2"> | |
<a href="#content">(top)</a> | |
</p> | |
<h3>Xalan namespace</h3> | |
<p>The Xalan extensions are implemented in one of the classes under org.apache.xalan.lib. The main | |
extension class is <a href="apidocs/org/apache/xalan/lib/Extensions.html"> | |
org.apache.xalan.lib.Extensions</a>. Some extension | |
functions (e.g. intersection, difference, etc.) used to be in this class are now moved to the | |
corresponding <a href="#exslt">EXSLT</a> modules. All Xalan extensions use namespace URIs | |
starting with:</p> | |
<p> <code>http://xml.apache.org/xalan</code> | |
</p> | |
<p>If you are calling Xalan-Java-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 Xalan-Java-supplied extensions are stored, | |
you won't have to modify your stylesheet.</p> | |
<p>For an example that uses this namespace, see <a href="#ex-nodeset">Example with the nodeset | |
extension function</a>.</p> | |
<a name="redirect">‌</a> | |
<p align="right" size="2"> | |
<a href="#content">(top)</a> | |
</p> | |
<h3>Redirect</h3> | |
<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 | |
<a href="apidocs/javax/xml/transform/Result.html">javax.xml.transform.Result</a> object.</p> | |
<p>The namespace for the <a href="apidocs/org/apache/xalan/lib/Redirect.html">Redirect</a> | |
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> | |
<a name="ex-redirect">‌</a> | |
<p align="right" size="2"> | |
<a href="#content">(top)</a> | |
</p> | |
<h4>Example with the Redirect extension</h4> | |
<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> | |
<blockquote class="source"> | |
<pre><?xml version="1.0"?> | |
<doc> | |
<foo file="foo.out"> | |
Testing Redirect extension: | |
<bar>A foo subelement text node</bar> | |
</foo> | |
<main> | |
Everything else | |
</main> | |
</doc></pre> | |
</blockquote> | |
<p>This stylesheet redirects part of the output to a secondary file:</p> | |
<blockquote class="source"> | |
<pre> | |
<xsl:stylesheet xmlns:xsl="http://www.w3.org/1999/XSL/Transform" | |
version="1.0" | |
xmlns:redirect="http://xml.apache.org/xalan/redirect" | |
extension-element-prefixes="redirect"> | |
<xsl:template match="/"> | |
<standard-out> | |
Standard output: | |
<xsl:apply-templates/> | |
</standard-out> | |
</xsl:template> | |
<xsl:template match="main"> | |
<main> | |
<xsl:apply-templates/> | |
</main> | |
</xsl:template> | |
<xsl:template match="/doc/foo"> | |
<redirect:write select="@file"> | |
<foo-out> | |
<xsl:apply-templates/> | |
</foo-out> | |
</redirect:write> | |
</xsl:template> | |
<xsl:template match="bar"> | |
<foobar-out> | |
<xsl:apply-templates/> | |
</foobar-out> | |
</xsl:template> | |
</xsl:stylesheet></pre> | |
</blockquote> | |
<p>The standard output is:</p> | |
<blockquote class="source"> | |
<pre><?xml version="1.0" encoding="UTF-8"?> | |
<standard-out> | |
Standard output: | |
<main> | |
Everything else. | |
</main> | |
<standard-out></pre> | |
</blockquote> | |
<p>The output redirected to foo.out is:</p> | |
<blockquote class="source"> | |
<pre><?xml version="1.0" encoding="UTF-8"?> | |
<foo-out> | |
Testing Redirect extension: | |
<foobar-out>foo subelement text node</foobar-out> | |
</foo-out></pre> | |
</blockquote> | |
<p>For more information on using the Redirect extension to send output to multiple files, examine | |
the <a href="samples.html#ext1">SimpleRedirect</a> sample and see the | |
<a href="apidocs/org/apache/xalan/lib/Redirect.html">Redirect</a> class Javadoc.</p> | |
<a name="nodeset">‌</a> | |
<p align="right" size="2"> | |
<a href="#content">(top)</a> | |
</p> | |
<h3>nodeset</h3> | |
<p>Implemented in <a href="apidocs/org/apache/xalan/lib/Extensions.html"> | |
org.apache.xalan.lib.Extensions</a>,<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 <a href="#exslt">EXSLT</a> | |
extension function <code>node-set</code> in the namespace | |
<code>xmlns:common="http://exslt.org/common"</code>.</p> | |
<table class="note"> | |
<tr> | |
<td class="noteImg"> | |
<img src="resources/note.gif" alt="note" /> | |
</td> | |
<td class="noteTxt">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 <a href="http://www.w3.org/TR/xslt#section-Result-Tree-Fragments">Result Tree | |
Fragments</a>.</td> | |
</tr> | |
</table> | |
<a name="ex-nodeset">‌</a> | |
<p align="right" size="2"> | |
<a href="#content">(top)</a> | |
</p> | |
<h4>Example with the nodeset extension function</h4> | |
<p>The following stylesheet uses the nodeset extension function to cast a result tree fragment | |
into a node-set that can then be navigated in standard XPath manner. It uses the | |
http://xml.apache.org/xalan namespace to provide access to the nodeset() method in | |
xml.apache.xalan.lib.Extensions.</p> | |
<blockquote class="source"> | |
<pre><?xml version="1.0"?> | |
<xsl:stylesheet xmlns:xsl="http://www.w3.org/1999/XSL/Transform" | |
version="1.0" | |
xmlns:xalan="http://xml.apache.org/xalan" | |
exclude-result-prefixes="xalan"> | |
<xsl:template match="/"> | |
<out> | |
<xsl:variable name="rtf"> | |
<docelem> | |
<elem1> | |
<elem1a>ELEMENT1A</elem1a> | |
<elem1b>,ELEMENT1B</elem1b> | |
</elem1> | |
<elem2> | |
<elem2a>ELEMENT2A</elem2a> | |
</elem2> | |
</docelem> | |
</xsl:variable> | |
<xsl:for-each select="xalan:nodeset($rtf)/docelem//*"> | |
<xsl:value-of select="name(.)"/><xsl:text>,</xsl:text> | |
</xsl:for-each> | |
</out> | |
</xsl:template> | |
</xsl:stylesheet></pre> | |
</blockquote> | |
<p>The output of running this stylesheet (with any XML input source) is a comma-delimited list of | |
the element names in the node-set<br /> | |
<code><out>elem1,elem1a,elem1b,elem2,elem2a</out></code> | |
</p> | |
<table class="note"> | |
<tr> | |
<td class="noteImg"> | |
<img src="resources/note.gif" alt="note" /> | |
</td> | |
<td class="noteTxt">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.</td> | |
</tr> | |
</table> | |
<a name="nodeinfo">‌</a> | |
<p align="right" size="2"> | |
<a href="#content">(top)</a> | |
</p> | |
<h3>NodeInfo</h3> | |
<p> | |
<a href="apidocs/org/apache/xalan/lib/NodeInfo.html">org.apache.xalan.lib.NodeInfo</a> provides | |
extension elements that you can use to get information about the location of nodes in the source | |
document:</p> | |
<ul> | |
<li> | |
<a href="#systemid">systemId</a> | |
</li> | |
<li> | |
<a href="#publicid">publicId</a> (to be done)</li> | |
<li> | |
<a href="#linenumber">lineNumber</a> | |
</li> | |
<li> | |
<a href="#columnnumber">columnNumber</a> | |
</li> | |
</ul> | |
<table class="note"> | |
<tr> | |
<td class="noteImg"> | |
<img src="resources/note.gif" alt="note" /> | |
</td> | |
<td class="noteTxt">If you want to use the NodeInfo extension elements, you MUST set the TransformerFactory | |
<a href="features.html#source_location">source_location</a> attribute to true. | |
You can use the <a href="commandline.html">command-line utility</a> -L flag or the | |
<a href="apidocs/javax/xml/transform/TransformerFactory.html#setAttribute(java.lang.String, java.lang.Object)">TransformerFactory.setAttribute()</a> method to set this attribute.</td> | |
</tr> | |
</table> | |
<a name="systemid">‌</a> | |
<p align="right" size="2"> | |
<a href="#content">(top)</a> | |
</p> | |
<h4>systemId</h4> | |
<p>Implemented in <a href="apidocs/org/apache/xalan/lib/NodeInfo.html"> | |
org.apache.xalan.lib.NodeInfo</a>, | |
<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> | |
<a name="publicid">‌</a> | |
<p align="right" size="2"> | |
<a href="#content">(top)</a> | |
</p> | |
<h4>publicId</h4> | |
<p> | |
<b>To be done.</b> Implemented in <a href="apidocs/org/apache/xalan/lib/NodeInfo.html"> | |
org.apache.xalan.lib.NodeInfo</a>, | |
<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> | |
<a name="linenumber">‌</a> | |
<p align="right" size="2"> | |
<a href="#content">(top)</a> | |
</p> | |
<h4>lineNumber</h4> | |
<p>Implemented in <a href="apidocs/org/apache/xalan/lib/NodeInfo.html"> | |
org.apache.xalan.lib.NodeInfo</a>, | |
<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> | |
<table class="note"> | |
<tr> | |
<td class="noteImg"> | |
<img src="resources/note.gif" alt="note" /> | |
</td> | |
<td class="noteTxt">This function returns -1 if the line number is not known (for example, the source is a | |
DOM Document).</td> | |
</tr> | |
</table> | |
<a name="columnnumber">‌</a> | |
<p align="right" size="2"> | |
<a href="#content">(top)</a> | |
</p> | |
<h4>columnNumber</h4> | |
<p>Implemented in <a href="apidocs/org/apache/xalan/lib/NodeInfo.html"> | |
org.apache.xalan.lib.NodeInfo</a>, <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> | |
<table class="note"> | |
<tr> | |
<td class="noteImg"> | |
<img src="resources/note.gif" alt="note" /> | |
</td> | |
<td class="noteTxt">This function returns -1 if the column number is not known (for example, the source is a DOM | |
Document).</td> | |
</tr> | |
</table> | |
<a name="sql">‌</a> | |
<p align="right" size="2"> | |
<a href="#content">(top)</a> | |
</p> | |
<h3>SQL library</h3> | |
<ul> | |
<li> | |
<a href="#sqlconn">Setting up a connection</a> | |
</li> | |
<li> | |
<a href="#sqlparam">Parameterized queries</a> | |
</li> | |
<li> | |
<a href="#ex-sql">SQL library example</a> | |
</li> | |
<li> | |
<a href="samples.html#sql">SQL library sample applications</a> | |
</li> | |
</ul> | |
<p>The namespace for the SQL extension is:</p> | |
<code>http://xml.apache.org/xalan/sql</code> | |
<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> | |
<b>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.</b> | |
</p> | |
<table class="note"> | |
<tr> | |
<td class="noteImg"> | |
<img src="resources/note.gif" alt="note" /> | |
</td> | |
<td class="noteTxt">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 <a href="samples.html#sql">SQL library samples</a>. | |
</td> | |
</tr> | |
</table> | |
<p> | |
<a href="apidocs/org/apache/xalan/lib/sql/XConnection.html">org.apache.xalan.lib.sql.XConnection</a> | |
provides a number of extension functions that you can use in your stylesheet.</p> | |
<ol> | |
<li>new() -- Use one of the XConnection constructors to connect to a data source, and return an | |
XConnection object. You can use one of the constructors creates a connection pool from which | |
stylesheets can obtain connections to a datasource. To support connection pools, SQL library | |
includes a ConnectionPool interface and a implementation: DefaultConnectionPool. You can also | |
provide your own ConnectionPool implementation.<br /> | |
<br /> | |
</li> | |
<li>query() -- Use the XConnection object query() method to return a "streamable" result set in | |
the form of a row-set node. Work your way through the row-set one row at a time. The same row | |
element is used over and over again, so you can begin "transforming" the row-set before the | |
entire result set has been returned.<br /> | |
<br /> | |
</li> | |
<li>pquery(), addParameter(), addParameterFromElement(), clearParameters() -- | |
Use the XConnection pquery() method in conjunction with these other methods to | |
set up and execute parameterized queries.<br /> | |
<br /> | |
</li> | |
<li>Use enableStreamingMode() to use a single row node to "stream" through the result set, and | |
disableStreamingMode() to cache the query result set. <br /> | |
<br /> | |
<table class="note"> | |
<tr> | |
<td class="noteImg"> | |
<img src="resources/note.gif" alt="note" /> | |
</td> | |
<td class="noteTxt"> | |
enableStreamingMode and disableStreamingMode() are depricated | |
See <a href="extensionslib.html#sql-ext-features">SQL Extension Features</a>. | |
</td> | |
</tr> | |
</table> | |
<br /> | |
</li> | |
<li>close() -- Use the XConnection object close() method to terminate the connection.</li> | |
</ol> | |
<a name="sql-ext-features">‌</a> | |
<p align="right" size="2"> | |
<a href="#content">(top)</a> | |
</p> | |
<h4>SQL Extension Feature Settings</h4> | |
<p>The SQL Extension allows features of the extension to be set through the setFeature / getFeature interface.</p> | |
<p>To set a feature, use: <br /> | |
<code> | |
<xsl:value-of select="<br /> | |
sql:setFeature($db, 'feature-name', 'feature-value')"/> | |
</code> | |
<br /> | |
<br /> | |
To retrive the current value of the feature, use: <br /> | |
<code> | |
<xsl:value-of select="<br /> | |
sql:getFeature($db, 'feature-name')"/> | |
</code> | |
<br /> | |
</p> | |
<table border="1"> | |
<tr> | |
<th class="content" rowspan="1" colspan="1">Feature</th> | |
<th class="content" rowspan="1" colspan="1">Valid Values</th> | |
</tr> | |
<tr> | |
<td class="content" rowspan="1" colspan="1">streaming</td> | |
<td class="content" rowspan="1" colspan="1">true or false</td> | |
</tr> | |
</table> | |
<p>The query() and pquery() extension functions return a Document node that contains (as needed) | |
an array of column-header elements, a single row element that is used repeatedly, and an array | |
of col elements. Each column-header element (one per column in the row-set) contains an attribute | |
(ColumnAttribute) for each of the column descriptors in the ResultSetMetaData object. Each col | |
element contains a text node with a textual representation of the value for that column in the | |
current row.</p> | |
<a name="sqlconn">‌</a> | |
<p align="right" size="2"> | |
<a href="#content">(top)</a> | |
</p> | |
<h4>Setting up a connection</h4> | |
<p>You can place connection information (JDBC driver, datasource URL, and usually user ID | |
and password) in stylesheets or in XML source documents.</p> | |
<p>The following stylesheet fragment uses stylesheet parameters to designate a JDBC driver | |
and datasource. The default parameter values can be overridden with runtime parameter values.</p> | |
<blockquote class="source"> | |
<pre> | |
<xsl:param name="driver" select="'org.apache.derby.jdbc.EmbeddedDriver'"/> | |
<xsl:param name="datasource" select="'jdbc:derby:sampleDB'"/> | |
<xsl:param name="query" select="'SELECT * FROM import1'"/> | |
</pre> | |
</blockquote> | |
<p>You can also obtain connection information from the XML source document that you use for the | |
transformation. Suppose you have the following DBINFO nodeset in an XML document:</p> | |
<blockquote class="source"> | |
<pre> | |
<DBINFO> | |
<dbdriver>org.apache.derby.jdbc.EmbeddedDriver</dbdriver> | |
<dburl>jdbc:derby:sampleDB</dburl> | |
<user>jbloe</user> | |
<password>geron07moe</password> | |
</DBINFO> | |
</pre> | |
</blockquote> | |
<p>In the stylesheet, you can extract this information as follows:</p> | |
<blockquote class="source"> | |
<pre> | |
<xsl:stylesheet version 1.0 | |
xmlns:xsl="http://www.w3.org/1999/XSL/Transform" | |
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)"/> | |
.... | |
</pre> | |
</blockquote> | |
<p>For an example of both approaches, see <a href="samples.html#basic-conn">Basic Connection</a> | |
samples.</p> | |
<p>You can also create a named connection pool that is maintained external to Xalan-Java.</p> | |
<blockquote class="source"> | |
<pre> | |
import org.apache.xalan.lib.sql.DefaultConnectionPool; | |
import org.apache.xalan.lib.sql.XConnectionPoolManager; | |
... | |
DefaultConnectionPool cp = new DefaultConnectionPool(); | |
cp.setDriver("org.apache.derby.jdbc.EmbeddedDriver"); | |
cp.setURL("jdbc:derby:sampleDB"); | |
cp.setUser(""); | |
cp.setPassword(""); | |
// Start with 10 connections. | |
cp.setMinConnections(10); | |
cp.enablePool(); | |
// Register the connection pool so stylesheets can use it. | |
XConnectionPoolManager pm = new XConnectionPoolManager(); | |
pm.registerPool("extpool", cp); | |
</pre> | |
</blockquote> | |
<p>A stylesheet can use this connection pool as follows:</p> | |
<blockquote class="source"> | |
<pre> | |
<xsl:stylesheet version 1.0 | |
xmlns:xsl="http://www.w3.org/1999/XSL/Transform" | |
xmlns:sql="http://xml.apache.org/xalan/sql" | |
extension-element-prefixes="sql"> | |
... | |
<xsl:variable name="db" select="sql:new($driver, 'extpool')"/> | |
</pre> | |
</blockquote> | |
<p>For an example, see the <a href="samples.html#ext-conn">ExternalConnection</a> | |
sample.</p> | |
<a name="sqlparam">‌</a> | |
<p align="right" size="2"> | |
<a href="#content">(top)</a> | |
</p> | |
<h4>Parameterized queries</h4> | |
<p>To define a parameterized query, use a SQL query string with a question mark (?) for each | |
parameter. You can provide the parameter values at runtime with stylesheet parameters or with | |
nodes in the XML source document. | |
For each parameter, you should also designate the SQL data type.</p> | |
<p>XConnection provides a number of addParameter() methods and an addParameterFromElement() method | |
that you can use as extension functions to pull in the parameter values (in the order the | |
parameters appear in the query). To execute the query and return the result set, call the pquery() | |
method as an extension function. There are two variations of the pquery() method. The one you | |
should ordinarily use includes as arguments the SQL query string and a string list | |
(delimited by the space, tab, or line feeds) of parameter types. For example:</p> | |
<blockquote class="source"> | |
<pre> | |
<xsl:variable name="resultset" | |
select=sql:pquery($XConnectionObj, | |
'select * from X where Y = ? and Z = ?', | |
'int string')"/> | |
</pre> | |
</blockquote> | |
<p> | |
For a complete example, see the <a href="samples.html#pquery">Parameterized query</a> sample. | |
</p> | |
<a name="ex-sql">‌</a> | |
<p align="right" size="2"> | |
<a href="#content">(top)</a> | |
</p> | |
<h4>Example with SQL library</h4> | |
<p>This example displays the result set from a table in a sample Derby database. It is also | |
available as a sample application; see <a href="samples.html#sql">SQl Extension Samples</a>.</p> | |
<blockquote class="source"> | |
<pre> | |
<?xml version="1.0"?> | |
<xsl:stylesheet xmlns:xsl="http://www.w3.org/1999/XSL/Transform" | |
version="1.0" | |
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'"/> | |
<xsl:template match="/"> | |
<!-- 1. Make the connection --> | |
<xsl:variable name="products" | |
select="sql:new('org.apache.derby.jdbc.EmbeddedDriver', | |
'jdbc:derby:sampleDB')"/> | |
<HTML> | |
<HEAD> | |
</HEAD> | |
<BODY> | |
<TABLE border="1"> | |
<!--2. Execute the query --> | |
<xsl:variable name="table" select='sql:query($products, $query)'/> | |
<TR> | |
<!-- Get column-label attribute from each column-header--> | |
<xsl:for-each select="$table/sql/metadata/column-header"> | |
<TH><xsl:value-of select="@column-label"/></TH> | |
</xsl:for-each> | |
</TR> | |
<xsl:apply-templates select="$table/sql/row-set/row"/> | |
<xsl:text>&#10;</xsl:text> | |
</TABLE> | |
</BODY> | |
</HTML> | |
<!-- 3. Close the connection --> | |
<xsl:value-of select="sql:close($products)"/> | |
</xsl:template> | |
<xsl:template match="row"> | |
<TR> | |
<xsl:apply-templates select="col"/> | |
</TR> | |
</xsl:template> | |
<xsl:template match="col"> | |
<TD> | |
<!-- Here is the column data --> | |
<xsl:value-of select="text()"/> | |
</TD> | |
</xsl:template> | |
</xsl:stylesheet> | |
</pre> | |
</blockquote> | |
<a name="pipedocument">‌</a> | |
<p align="right" size="2"> | |
<a href="#content">(top)</a> | |
</p> | |
<h3>pipeDocument</h3> | |
<p>Implemented in <a href="apidocs/org/apache/xalan/lib/PipeDocument.html"> | |
org.apache.xalan.lib.PipeDocument</a>,<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 transformation 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> | |
<p align="right" size="2"> | |
<a href="#content">(top)</a> | |
</p> | |
<h4>Sample: generating a table of contents and an HTML "book"</h4> | |
<p>An XML "book" document contains a number of doc elements like the following:<br /> | |
<code><doc source="sources/intro.xml" id="intro" label="Introduction"></code> | |
</p> | |
<p>The source attribute identifies the document to be transformed, the id is the output file name, | |
and the primary stylesheet places the label in the table-of-contents link.</p> | |
<p>The stylesheet declares the pipeDocument namespace, designates the namespace prefix as an | |
extension element prefix, and contains a parameter designating where the output files are to | |
be placed:</p> | |
<blockquote class="source"> | |
<pre><xsl:stylesheet version="1.0" | |
xmlns:xsl="http://www.w3.org/1999/XSL/Transform" | |
xmlns:pipe="http://xml.apache.org/xalan/PipeDocument" | |
extension-element-prefixes="pipe"> | |
<xsl:param name="destdir" value="html/output"> | |
...</pre> | |
</blockquote> | |
<p>This stylesheet contains a template where each doc element is processed. For each doc element, the | |
stylesheet adds an entry to the table-of-contents document. The extension element pipes the specified | |
document through a series of two transformations, with an stylesheet input parameter for the first | |
transformation. The pipeDocument target attribute designates the output from the second | |
transformation.</p> | |
<blockquote class="source"> | |
<pre><xsl:template match="doc"> | |
<p> | |
<a href={$destdir}><xsl:value-of select="@label"/><a> | |
</p> | |
<pipe:pipeDocument source="{@source}" target="{$destdir/@id}"> | |
<stylesheet href="ss1.xsl"> | |
<param name="doc-id" value="@id"/> | |
</stylesheet> | |
<stylesheet href="ss2.xsl"/> | |
</pipe:pipeDocument> | |
</xsl:template></pre> | |
</blockquote> | |
<p>Notes:</p> | |
<ul> | |
<li>The base URI for the source attribute is the XML "book" document.</li> | |
<li>The target attribute is taken as is (the base is the current user directory from which this | |
transformation is being run).</li> | |
<li>The stylsheet containg the extension element is the base URI for the stylesheet hrefs.</li> | |
</ul> | |
<p align="right" size="2"> | |
<a href="#content">(top)</a> | |
</p> | |
<h4>Variation: using pipeDocument in an empty stylesheet</h4> | |
<p>Suppose you want to pipe a document through a series of transformations. You can use the pipeDocument | |
extension element to perform this operation by placing the extension element in an otherwise empty | |
stylesheet.</p> | |
<p>The following stylesheet is used to merge the Xalan documents into a book (the first transformation), | |
and transform the book into a tree of formatting objects, which can then be used to generate a PDF file. | |
This transformation is invoked as follows:</p> | |
<p> | |
<code>java org.apache.xalan.xslt.Process -in printbook.xml</code> | |
<br /> | |
<code> -param source printbook.xml</code> | |
<br /> | |
<code> -param target xalanbook.fo</code> | |
</p> | |
<p>There is no XML input document or output document for the primary transformation, which does no more | |
than invoke the extension element.</p> | |
<blockquote class="source"> | |
<pre><?xml version='1.0'?> | |
<xsl:stylesheet version="1.0" | |
xmlns:xsl="http://www.w3.org/1999/XSL/Transform" | |
xmlns:pipe="http://xml.apache.org/xalan/PipeDocument" | |
extension-element-prefixes="pipe"> | |
<xsl:param name="source"/> | |
<xsl:param name="target"/> | |
<xsl:template match="/"> | |
<pipe:pipeDocument | |
source="{$source}" | |
target="{$target}"> | |
<stylesheet href="printbook_assemble.xsl"/> | |
<stylesheet href="bkbook8x11_xalan.xsl"/> | |
</pipe:pipeDocument> | |
</xsl:template> | |
</xsl:stylesheet></pre> | |
</blockquote> | |
<a name="evaluate">‌</a> | |
<p align="right" size="2"> | |
<a href="#content">(top)</a> | |
</p> | |
<h3>evaluate</h3> | |
<p>Implemented in <a href="apidocs/org/apache/xalan/lib/Extensions.html"> | |
org.apache.xalan.lib.Extensions</a>,<br /> | |
<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> | |
<table class="note"> | |
<tr> | |
<td class="noteImg"> | |
<img src="resources/note.gif" alt="note" /> | |
</td> | |
<td class="noteTxt">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.</td> | |
</tr> | |
</table> | |
<a name="tokenize">‌</a> | |
<p align="right" size="2"> | |
<a href="#content">(top)</a> | |
</p> | |
<h3>tokenize</h3> | |
<p>Implemented in <a href="apidocs/org/apache/xalan/lib/Extensions.html"> | |
org.apache.xalan.lib.Extensions</a>,<br /> | |
<code>tokenize (tokenize-string, delimiters)</code> | |
<br /> | |
or<br /> | |
<code>tokenize (tokenize-string)</code> function returns a node-set containing one text node for each | |
token in the tokenize-string.</p> | |
<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> | |
<table class="note"> | |
<tr> | |
<td class="noteImg"> | |
<img src="resources/note.gif" alt="note" /> | |
</td> | |
<td class="noteTxt">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.</td> | |
</tr> | |
</table> | |
<p align="right" size="2"> | |
<a href="#content">(top)</a> | |
</p> | |
</div> | |
<div id="footer">Copyright © 1999-2012 The Apache Software Foundation<br />Apache, Xalan, and the Feather logo are trademarks of The Apache Software Foundation<div class="small">Web Page created on - Sun 03/18/2012</div> | |
</div> | |
</body> | |
</html> |