You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@xalan.apache.org by dl...@apache.org on 2001/05/02 23:38:14 UTC
cvs commit: xml-xalan/java/xdocs/sources/xalan extensionslib.xml samples.xml
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 (johnglinux@eyecatching.com), 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
+ (johnglinux@eyecatching.com) 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 (johnglinux@eyecatching.com).</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 (johnglinux@eyecatching.com).</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 (johnglinux@eyecatching.com).</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 (johnglinux@eyecatching.com).</em></p>
+ <p>What it does: Illustrates enabling and disabling of caching the streamable result set returned by a query.</p>
+ <p>The stylesheets use the XConnection enableCacheNodes() and disableCacheNodes() methods.</p>
+ <p>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 (johnglinux@eyecatching.com).</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: xalan-cvs-unsubscribe@xml.apache.org
For additional commands, e-mail: xalan-cvs-help@xml.apache.org