dleslie 01/05/02 14:38:14
Modified: java/xdocs/sources/xalan extensionslib.xml samples.xml
Log:
Added info on John Gentilin's addtions to the SQL extensions
libary and associated sample apps.
Revision Changes Path
1.12 +90 -10 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.11
retrieving revision 1.12
diff -u -r1.11 -r1.12
--- extensionslib.xml 2001/02/21 14:08:04 1.11
+++ extensionslib.xml 2001/05/02 21:38:07 1.12
@@ -66,7 +66,7 @@
<li><link anchor="difference">difference</link></li>
<li><link anchor="distinct">distinct</link></li>
<li><link anchor="hassamenodes">hasSameNodes</link></li>
-<li><link anchor="sql">SQL extensions</link></li>
+<li><link anchor="sql">SQL library</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>
@@ -213,29 +213,108 @@
<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="sql"/>
<s2 title= "SQL library">
+<ul>
+<li><link anchor="sqlconn">Setting up a connection</link></li>
+<li><link anchor="sqlparam">Parameterized queries</link></li>
+<li><link anchor="ex-sql">SQL library example</link></li>
+<li><link idref="samples" anchor="sql">SQL library sample
applications</link></li>
+</ul>
<p><em>**Experimental**</em> Provides extension functions for connecting to
a JDBC data source, executing a query,
and working incrementally through "streamable" result set.</p>
+<note>Many features of the SQL library, including support for connection
pools, parameterized queries, caching streamable
+result sets, and added support for extracting connection information and
query parameters from XML source documents exist
+thanks to John Gentilin ([EMAIL PROTECTED]), who has also added a number of
SQL library samples.</note>
<p><em>The SQL extension use of a single row-set node to incrementally
return a query result set is experimental. Keep in mind that 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>
-<p><jump
href="apidocs/org/apache/xalan/lib/sql/XConnection.html">org.apache.xalan.lib.sql.XConnection</jump>
provides three extension functions that you can use in your stylesheet.</p>
+<p><jump
href="apidocs/org/apache/xalan/lib/sql/XConnection.html">org.apache.xalan.lib.sql.XConnection</jump>
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.<br/><br/></li>
+ object. You can use one of the constructors creates a connection pool
from which stylesheets can obtain connections
+ to a datasource. To support connction 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>enableCacheNodes(), disableCacheNodes() -- Use these XConnection
methods to manage the caching of the streamable
+ nodes returned by queries.<br/><br/></li>
<li>close() -- Use the XConnection object close() method to terminate
the connection.</li>
</ol>
- <p>The query() extension function returns a Document node that contains
(as needed) an array of column-header elements,
+ <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>
- <anchor name="ex-sql"/>
+ <anchor name="sqlconn"/>
+ <s3 title="Setting up a connection">
+ <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>
+ <source><xsl:param name="driver"
select="'org.enhydra.instantdb.jdbc.idbDriver'"/>
+<xsl:param name="datasource"
select="'jdbc:idb:../../instantdb/sample.prp'"/>
+<xsl:param name="query" select="'SELECT * FROM import1'"/></source>
+ <p>You can also obtain connection information from the XML source
document that you use for the transformationl. Suppose
+ you have the following DBINFO nodeset in an XML document:</p>
+ <source><DBINFO>
+ <dbdriver>org.enhydra.instantdb.jdbc.idbDriver</dbdriver>
+ <dburl>jdbc:idb:../../instantdb/sample.prp</dburl>
+ <user>jbloe</user>
+ <password>geron07moe</password>
+</DBINFO></source>
+ <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"
+ extension-element-prefixes="sql">
+ <xsl:param name="cinfo" select="//DBINFO"/>
+ <xsl:variable name="db" select="sql:new($cinfo)"/>
+....</source>
+ <p>For an example of both approaches, see <link idref="samples"
anchor="basic-conn">Basic Connection</link> samples.</p>
+ <p>You can also create a named connection pool that is maintained
external to &xslt4j;.</p>
+ <source>import org.apache.xalan.lib.sql.DefaultConnectionPool;
+import org.apache.xalan.lib.sql.XConnectionPoolManager;
+...
+DefaultConnectionPool cp = new DefaultConnectionPool();
+cp.setDriver("org.enhydra.instantdb.jdbc.idbDriver");
+cp.setURL("jdbc:idb:../../instantdb/sample.prp");
+cp.setUser("jbloe");
+cp.setPassword("geron07moe");
+// 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);</source>
+ <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"
+ extension-element-prefixes="sql">
+...
+ <xsl:variable name="db" select="sql:new($driver,
'extpool')"/></source>
+ <p>For an example, see the <link idref="samples"
anchor="ext-conn">ExternalConnection</link> sample.</p>
+ </s3><anchor name="sqlparam"/>
+ <s3 title="Parameterized queries">
+ <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>
+ <source><xsl:variable name="resultset"
+ select=sql:pquery($XConnectionObj,
+ 'select * from X where Y = ? and Z = ?',
+ 'int string')"/></source>
+ <p>For a complete example, see the <link idref="samples"
anchor="pquery">Parameterized query</link> sample.</p>
+ </s3><anchor name="ex-sql"/>
<s3 title="Example with SQL library">
<p>This example displays the result set from a table in a sample
InstantDB database. It is also
- available as a sample application; see
- <link idref="samples" anchor="ext6">6-sqllib-instantdb</link>.</p>
+ available as a sample application; see <link idref="samples"
anchor="ext6">6-sqllib-instantdb</link>.</p>
<source><?xml version="1.0"?>
<xsl:stylesheet xmlns:xsl="http://www.w3.org/1999/XSL/Transform";
version="1.0"
@@ -287,9 +366,10 @@
</xsl:stylesheet>
</source>
</s3>
-</s2><anchor name="evaluate"/>
-<s2 title= "evaluate">
-<p>Implemented in <jump
href="apidocs/org/apache/xalan/lib/Extensions.html">org.apache.xalan.lib.Extensions</jump>,<br/>
+
+ </s2><anchor name="evaluate"/>
+ <s2 title= "evaluate">
+ <p>Implemented in <jump
href="apidocs/org/apache/xalan/lib/Extensions.html">org.apache.xalan.lib.Extensions</jump>,<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>
1.29 +96 -13 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.28
retrieving revision 1.29
diff -u -r1.28 -r1.29
--- samples.xml 2001/04/27 20:03:27 1.28
+++ samples.xml 2001/05/02 21:38:09 1.29
@@ -295,7 +295,7 @@
<li><link anchor="ext3">3-java-namespace</link></li>
<li><link anchor="ext4">4-numlistJava</link></li>
<li><link anchor="ext5">5-numlistJScript</link></li>
- <li><link anchor="ext6">6-sqllib-instantdb</link></li>
+ <li><link anchor="sql">SQL library extensions</link></li>
</ul>
<p>The extensions subdirectory contains six samples with &xslt4j;
extensions. Two of the samples use
extensions implemented in JavaScript, and four of the samples use
extensions implemented in Java.</p>
@@ -350,22 +350,105 @@
<p>Run this sample from the extensions subdirectory with</p>
<p><code> java org.apache.xalan.xslt.Process -in numlist.xml</code>
<br/> <code>-xsl 5-numlistJscript.xsl</code></p>
- </s3><anchor name="ext6"/>
- <s3 title="6-sqllib-instantdb">
- <p>What it does: Uses <link idref="extensionslib" anchor="sql">SQL
library XConnection
- extension</link> to connect to an InstantDB sample database, perform a
query, and display the
- query result in an HTML table.</p>
- <note>You must include idb.jar on the classpath. We have placed a copy
of idb.jar from
+ </s3>
+ </s2><anchor name="sql"/>
+ <s2 title="SQL Library extensions">
+ <p>The SQL Library extension samples use <link idref="extensionslib"
anchor="sql">SQL library XConnection
+ extension</link>to connect to an InstantDB datasource, perform
queries, and return query result sets.</p>
+ <note>To run these samples, you must include idb.jar on the classpath.
We have placed a copy of idb.jar from
InstantDB version 3.25 in samples/extensions/instantdb. For
information about InstantDB, see
<jump
href="http://instantdb.enhydra.org/software/documentation/index.html";>InstantDB</jump>
and the <jump
href="http://instantdb.enhydra.org/software/license/index.html";>Enydra Public
- License</jump>.</note>
- <p>Run this sample from the extensions subdirectory with (adjust the
Windows classpath setting
- below for your operating environment):</p>
- <p><code>java -cp instantdb/idb.jar;%classpath%</code>
- <br/> org.apache.xalan.xslt.Process<code></code>
+ License</jump>.</note>
+ <ul>
+ <li><link anchor="ext6">6-sqllib-instantdb</link></li>
+ <li><link anchor="basic-conn">Basic Connections</link></li>
+ <li><link anchor="ext-conn">ExternalConnection</link></li>
+ <li><link anchor="pquery">Parameterized query</link></li>
+ <li><link anchor="streamable">Streamable</link></li>
+ <li><link anchor="showerror">Show-error</link></li>
+ </ul>
+ <note>Except for 6-sqllib-instantdb, all these samples have been
created by John Gentilin
+ ([EMAIL PROTECTED]) to take illustrate the rich feature set he has
contributed to the SQL Library.
+ To run each of these samples, be sure you are in the appropriate
extensions/sql subdirectory.</note>
+ <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>Add idb.jar to the classpath, 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>
+ </s3><anchor name="basic-conn"/>
+ <s3 title="Basic-Connection">
+ <p><em>Contributed by John Gentilin ([EMAIL PROTECTED]).</em></p>
+ <p>What it does: illustrates two strategies for connecting to a
database, executing a static query, and returning
+ the query result.</p>
+ <p>The first strategy is to get connection information along with the
static query from the stylesheet (dbtest.xsl)\
+ 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>Add extensions/instantdb/idb.jar to the classpath, 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>
+ <br/> <code>-xsl dbtest.xsl -out import1.html</code></p>
+ <p>2. To get connection information in the form of a nodeset from the
XML source document:</p>
+ <p><code>java org.apache.xalan.xslt.Process</code>
+ <br/> <code>-in dbinfo.xml -xsl dbtest-cinfo.xsl</code>
+ <br/> <code>-out import1.html</code></p>
+ <p>3. To get connection information from the stylesheet and dump the
raw result set to an XML file:</p>
+ <p><code>java org.apache.xalan.xslt.Process</code>
+ <br/> <code>-xsl DumpSQL.xsl -out import1.xml</code></p>
+ </s3> <anchor name="ext-conn"/>
+ <s3 title="ExternalConnection">
+ <p><em>Contributed by John Gentilin ([EMAIL PROTECTED]).</em></p>
+ <p>What it does: The ExternalConnection classes uses the default
implementation of the ConnectionPool interface
+ to create a pool of connections. A stylesheet in turn uses a connection
from this pool to instantiate an
+ 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.</p>
+ <p>The ExternalConnection class is in xalansamples.jar. Be sure
xalansamples.jar and idb.jar are on the classpath, 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 wiht dbtest.xsl, which draws
+ from the pool to instantiate an XConnection object, connect to the
datasource, execute a static query, and return the
+ query result.</p>
+ </s3><anchor name="pquery"/>
+ <s3 title="Parameterized query">
+ <p><em>Contributed by John Gentilin ([EMAIL PROTECTED]).</em></p>
+ <p>What it does: connect to a datasource, execute a parameterized query,
and return the result. The XML source document
+ 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>Be sure idb.jar is on the classpath, 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"/>
+ <s3 title="Streamable">
+ <p><em>Contributed by John Gentilin ([EMAIL PROTECTED]).</em></p>
+ <p>What it does: Illustrates enabling and disabling of caching the
streamable result set returned by a query.</p>
+ <p>The stylesheets use the XConnection enableCacheNodes() and
disableCacheNodes() methods.</p>
+ <p>Be sure idb.jar is on the classpath, 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>
+ <p>1. To turn caching off:</p>
+ <p><code>java org.apache.xalan.xslt.Process</code>
+ <br/><code>-xsl streamNodes.xsl</code></p>
+ <p>3. <ref>To be added</ref></p>
+ </s3><anchor name="showerror"/>
+ <s3 title="Show-error">
+ <p><em>Contributed by John Gentilin ([EMAIL PROTECTED]).</em></p>
+ <p>What it does: use the SQL library ExtensionError class to return an
error message in the output stream. The stylesheet
+ (dbtest.xsl) calls a template with a select statement that only returns
a nodeset if an error has occured:</p>
+ <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>Since the query contains an incorrect table name, this example does
return an error message. Correct the table name (change
+ 'import1X' to 'import1') and the example returns a standard result set.</p>
+ <p>With idb.jar on the classpath, run this sample from the
extensions/sql/show-error subdirectory:</p>
+ <p><code>java org.apache.xalan.xslt.Process</code>
+ <br/><code> -in dbtest.xsl -out dbtestout.html</code></p>
+ </s3>
</s2><anchor name="trace"/>
<s2 title="Trace">
<p>What it does: Trace uses the TraceListener and TraceManager classes
to log transformation events.</p>
---------------------------------------------------------------------
To unsubscribe, e-mail: [EMAIL PROTECTED]
For additional commands, e-mail: [EMAIL PROTECTED]
