You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@xalan.apache.org by sh...@apache.org on 2014/05/16 18:11:35 UTC
svn commit: r1595253 [5/18] - in /xalan/java/branches/WebSite: ./ xalan-j/
xalan-j/design/ xalan-j/design/resources/ xalan-j/resources/ xalan-j/xsltc/
xalan-j/xsltc/resources/
Added: xalan/java/branches/WebSite/xalan-j/extensionslib.html
URL: http://svn.apache.org/viewvc/xalan/java/branches/WebSite/xalan-j/extensionslib.html?rev=1595253&view=auto
==============================================================================
--- xalan/java/branches/WebSite/xalan-j/extensionslib.html (added)
+++ xalan/java/branches/WebSite/xalan-j/extensionslib.html Fri May 16 16:11:33 2014
@@ -0,0 +1,1022 @@
+<?xml version="1.0" encoding="UTF-8" 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=UTF-8" />
+<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="http://xalan.apache.org/index.html">Home</a>
+</li></ul><hr /><ul>
+<li>
+<a href="index.html">Xalan-J 2.7.2</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:dev@xalan.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:dev@xalan.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-2014 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 - Thu 2014-05-15</div>
+</div>
+</body>
+</html>
Propchange: xalan/java/branches/WebSite/xalan-j/extensionslib.html
------------------------------------------------------------------------------
svn:eol-style = native
---------------------------------------------------------------------
To unsubscribe, e-mail: commits-unsubscribe@xalan.apache.org
For additional commands, e-mail: commits-help@xalan.apache.org