johng 01/05/13 15:56:26
Modified: java/src/org/apache/xalan/lib/sql Column.java
ColumnAttribute.java ColumnData.java
ColumnHeader.java ConnectionPool.java
DefaultConnectionPool.java ExtensionError.java
PooledConnection.java QueryParameter.java Row.java
RowSet.java SQLExtensionError.java
StreamableNode.java XConnection.java
XConnectionPoolManager.java XStatement.java
package.html
Log:
Updates Javadocs
Submitted by:John Gentilin mailto://[EMAIL PROTECTED]
Revision Changes Path
1.7 +38 -9 xml-xalan/java/src/org/apache/xalan/lib/sql/Column.java
Index: Column.java
===================================================================
RCS file: /home/cvs/xml-xalan/java/src/org/apache/xalan/lib/sql/Column.java,v
retrieving revision 1.6
retrieving revision 1.7
diff -u -r1.6 -r1.7
--- Column.java 2001/04/18 23:24:49 1.6
+++ Column.java 2001/05/13 22:56:24 1.7
@@ -66,32 +66,55 @@
/**
- * <meta name="usage" content="experimental"/>
- * Represents a col node from a row node.
+ * <p>
+ * A JDBC Query returns a resultSet that contains rows of
+ * Data. In each row are entried for each column. The Column
+ * Object is used to represent the information about an
+ * individual column. i.e. It represents the <col> element.
+ * From this object, the attributes of that colum can be interrogated
+ * [EMAIL PROTECTED] org.apache.xalan.lib.sql.ColumnAttribute} or the value
of
+ * the data that the current column rpresents
+ * [EMAIL PROTECTED] org.apache.xalan.lib.sql.ColumnData}
+ *
+ * </p>
+ * <p>
+ * This object only represents the current column but a full array of
+ * all the columns are held in the Parent Row object. The array is
+ * zero based and the position of the current column is held in the
+ * m_columnIndex class field, the parent row information is held
+ * in the m_parentRow and the extent of the array is available in
+ * the m_childCount from the m_parentRow object.
+ *</p>
*/
public class Column extends StreamableNode
{
- /** column Index */
+ /**
+ * column Index, our position in the column line up
+ * The first position being zero.
+ */
int m_columnIndex;
- /** Parent row node */
+ /** Parent row node */
Row m_parent;
/** Flag indicating if in DEBUG mode */
private static final boolean DEBUG = false;
- /** Column data */
+ /** Column data */
ColumnData m_text = null;
/**
- * Constructor Column
- *
+ * Build up an instance of the Column object.
+ * To support cached nodes, the column data will be
+ * fetched in the constructor to assure that a valid
+ * copy exists.
*
* @param statement Current Document
* @param parent Parent row node of this column
* @param columnIndex Index for this column
* @param metadata Meta data (column header).
+ * @param ResultSet [EMAIL PROTECTED] java.sql.ResultSet}
*/
public Column(XStatement statement, Row parent, int columnIndex,
ResultSetMetaData metadata, ResultSet resultSet)
@@ -146,7 +169,12 @@
/**
* Return the next col element for the current row.
- * @return a Column node or null.
+ * @return a Column node or null if we are at the end
+ * of the column array.
+ *
+ * The column array list is built and maintained in the
+ * parent row object.
+ *
*/
public Node getNextSibling()
{
@@ -191,7 +219,8 @@
}
/**
- * Return the metadata for this column.
+ * From the XConnection (the root of the variable), retrive
+ * the ColumnAttributes object.
*
* @return the metadata for this column(column header).
*/
1.10 +1 -2
xml-xalan/java/src/org/apache/xalan/lib/sql/ColumnAttribute.java
Index: ColumnAttribute.java
===================================================================
RCS file:
/home/cvs/xml-xalan/java/src/org/apache/xalan/lib/sql/ColumnAttribute.java,v
retrieving revision 1.9
retrieving revision 1.10
diff -u -r1.9 -r1.10
--- ColumnAttribute.java 2001/04/18 23:24:49 1.9
+++ ColumnAttribute.java 2001/05/13 22:56:24 1.10
@@ -72,8 +72,7 @@
/**
- * <meta name="usage" content="experimental"/>
- * Represents a column attribute on a column-header element.
+ * Represents a column attribute on a column-header element.
* Each column-header element can contain any of the following
* attributes, depending on the ResultSetMetadata object returned with
* the query result set.
1.8 +2 -2
xml-xalan/java/src/org/apache/xalan/lib/sql/ColumnData.java
Index: ColumnData.java
===================================================================
RCS file:
/home/cvs/xml-xalan/java/src/org/apache/xalan/lib/sql/ColumnData.java,v
retrieving revision 1.7
retrieving revision 1.8
diff -u -r1.7 -r1.8
--- ColumnData.java 2001/04/18 23:24:50 1.7
+++ ColumnData.java 2001/05/13 22:56:24 1.8
@@ -68,8 +68,7 @@
import org.apache.xalan.res.XSLTErrorResources;
/**
- * <meta name="usage" content="experimental"/>
- * Represents the col element text node, i.e., the column value.
+ * Represents the col element text node, i.e., the column value.
*/
public class ColumnData extends StreamableNode implements Text
{
@@ -93,6 +92,7 @@
*
* @param statement Owning document
* @param parent Owning column
+ * @param ResultSet [EMAIL PROTECTED] java.sql.ResultSet}
* @throws SQLException, make the Column Class deal with the problem
*
*/
1.8 +28 -3
xml-xalan/java/src/org/apache/xalan/lib/sql/ColumnHeader.java
Index: ColumnHeader.java
===================================================================
RCS file:
/home/cvs/xml-xalan/java/src/org/apache/xalan/lib/sql/ColumnHeader.java,v
retrieving revision 1.7
retrieving revision 1.8
diff -u -r1.7 -r1.8
--- ColumnHeader.java 2001/04/18 23:24:50 1.7
+++ ColumnHeader.java 2001/05/13 22:56:24 1.8
@@ -69,9 +69,34 @@
import org.apache.xalan.res.XSLTErrorResources;
/**
- * <meta name="usage" content="experimental"/>
- * This class represents a column-header Node, which contains the metadata
- * for a column.
+ * <p>
+ * The ColumnHeader is a special branch of the document that provides
+ * a mechinsim to interogate columns that are returned from the query
+ * without accessing the data or moving the row counter.
+ * </p>
+ *
+ * <pre>
+ * The DTD is as follows.
+ *
+ * <p><HR>
+ * <row-set>
+ * <column-header <attribute list> />
+ * </row-set>
+ *<HR>
+ *</p>
+ *</pre>
+ *
+ * <p>
+ * To retrive a list of column labels that are available, walk the
+ * column-header elements and access the @column-label attribute.
+ *
+ * The column arrributes are actually store in an array of the RowSet
+ * object.
+ *
+ * This object will only give you the attributes for the current column
+ * header element (a.k.a. the current column) Access to the other columns
+ * is through the parent (row-set) array.
+ * </p>
*/
public class ColumnHeader extends StreamableNode implements NamedNodeMap
{
1.5 +6 -7
xml-xalan/java/src/org/apache/xalan/lib/sql/ConnectionPool.java
Index: ConnectionPool.java
===================================================================
RCS file:
/home/cvs/xml-xalan/java/src/org/apache/xalan/lib/sql/ConnectionPool.java,v
retrieving revision 1.4
retrieving revision 1.5
diff -u -r1.4 -r1.5
--- ConnectionPool.java 2001/03/15 17:50:02 1.4
+++ ConnectionPool.java 2001/05/13 22:56:24 1.5
@@ -64,13 +64,12 @@
import java.sql.SQLException;
/**
- *
- * An interface used to build wrapper classes around existing
- * Connection Pool libraries.
- *
- * Title: ConnectionPool<p>
- * @author John Gentilin
- * @version 1.0
+ *<p>
+ * This interface specification is used to define how Xalan will
+ * interact with a Connection Pool. To adapt a third party connection
+ * pool, either implement this interface as part of that pool or create
+ * a wrapper class that will provide the translation.
+ * </p>
*
*/
1.5 +33 -5
xml-xalan/java/src/org/apache/xalan/lib/sql/DefaultConnectionPool.java
Index: DefaultConnectionPool.java
===================================================================
RCS file:
/home/cvs/xml-xalan/java/src/org/apache/xalan/lib/sql/DefaultConnectionPool.java,v
retrieving revision 1.4
retrieving revision 1.5
diff -u -r1.4 -r1.5
--- DefaultConnectionPool.java 2001/03/15 17:50:03 1.4
+++ DefaultConnectionPool.java 2001/05/13 22:56:24 1.5
@@ -67,6 +67,20 @@
import java.sql.DatabaseMetaData;
import java.sql.DriverManager;
+
+/**
+ * <p>
+ * The default connection pool was implemented so that all connection
+ * to JDBC data sources use connection pools.
+ * </p>
+ * <p>
+ * The Default connection pool can also be used be external programs
+ * that want to use Xalan but don't already have connection pool code.
+ * Note however that this implementation of a connection pool is the
+ * bare minimum.
+ * </p>
+ *
+ */
public class DefaultConnectionPool implements ConnectionPool
{
private final static boolean DEBUG = false;
@@ -109,10 +123,11 @@
public DefaultConnectionPool() {}
/**
- * Are we active, if not then released connections will be
- * closed on release and new connections will be refused.
+ * The call provides a external method to control the connection
+ * pooling. If the pool is disabled, then the number of connections
+ * in use will be the number of connections in the pool. i.e. there
+ * will be no free unused connections.
*
- * @param <code>boolean flag</code>, Set the active flag.
*/
public void disablePool()
{
@@ -120,6 +135,13 @@
freeUnused();
}
+ /**
+ * The call provides a external method to control the connection
+ * pooling. If the pool is disabled, then the number of connections
+ * in use will be the number of connections in the pool. i.e. there
+ * will be no free unused connections.
+ *
+ */
public void enablePool()
{
m_IsActive = true;
@@ -135,6 +157,8 @@
/**
* Set the driver call to be used to create connections
+ *
+ * @param Sting d - The name of the driver to be used.
*/
public void setDriver(String d)
{
@@ -279,9 +303,13 @@
}
}
-
- // Find an available connection
+ /**
+ * Retrives an available connection from the pool. If one does not
+ * exist, the creat a new one.
+ * @throws SQLException
+ * @throws IllegalArgumentException, If connection info is invalid
+ */
public synchronized Connection getConnection()
throws IllegalArgumentException, SQLException
{
1.6 +44 -60
xml-xalan/java/src/org/apache/xalan/lib/sql/ExtensionError.java
Index: ExtensionError.java
===================================================================
RCS file:
/home/cvs/xml-xalan/java/src/org/apache/xalan/lib/sql/ExtensionError.java,v
retrieving revision 1.5
retrieving revision 1.6
diff -u -r1.5 -r1.6
--- ExtensionError.java 2001/03/15 17:50:03 1.5
+++ ExtensionError.java 2001/05/13 22:56:24 1.6
@@ -81,29 +81,30 @@
import org.apache.xpath.axes.ContextNodeList;
/**
- *
+ * <meta name="usage" content="experimental"/>
+ * <p>
* A base class that will convert an exception into an XML stream
* that can be returned in place of the standard result. The XML
* format returned is a follows.
- *
- * <ext-error>
- * <exception-info>
- * <message> Message from the Exception thrown </message>
- * <stack> Current stack information as CData </stack>
- * <exception-info>
+ * </p>
+ * <pre>
+ * <p>
+ * <ext-error>
+ * <exception-info>
+ * <message> Message from the Exception thrown </message>
+ * <exception-info>
*
- * If another class subclasses this class, there will be an
- * oppurtitny to add specific information here. Each Extension
- * class should implement their own specific Extension Error
- * class.
- * <ext-error>
+ * If another class subclasses this class, there will be an
+ * oppurtitny to add specific information here. Each Extension
+ * class should implement their own specific Extension Error class.
+ * </exception-info>
+ * %lt;/ext-error>
*
- * @author John Gentilin
- * @version 1.0
+ * </p>
+ * </pre>
*
*/
-
public class ExtensionError
implements NodeIterator, ContextNodeList, Cloneable
{
@@ -116,12 +117,35 @@
{
}
+ /**
+ *
+ * <meta name="usage" content="experimental"/>
+ *
+ * Initialize an error with the base exception and
+ * extrace the relavent information.
+ *
+ */
public ExtensionError(Exception err)
{
processBaseError(err);
// dump();
}
+ /**
+ * <meta name="usage" content="experimental"/>
+ *
+ * Process the standard error information and build the
+ * base document.
+ *
+ * Note: this implementation should probably extend UnImplNode and
+ * create a light weight representation of the Document instead of
+ * using a full Document implementation.
+ *
+ * Classes that extend this class to extend the error information
+ * need to override the populateSpecificData method so that only
+ * one control creates the return Document.
+ *
+ */
protected void processBaseError(Exception err)
{
try
@@ -147,20 +171,8 @@
text = m_doc.createTextNode(err.getLocalizedMessage());
etmp.appendChild(text);
- // System.out.println("MESSAGE[" + err.getLocalizedMessage() + "]");
-
- //ByteArrayOutputStream bos = new ByteArrayOutputStream();
- //PrintStream ps = new PrintStream(bos);
- //err.printStackTrace(ps);
- //String stack = bos.toString();
-
- // System.out.println(stack);
-
- //etmp = m_doc.createElement("stack");
- //info.appendChild(etmp);
- //cdata = m_doc.createCDATASection(stack);
- //etmp.appendChild(text);
-
+ // If we have been extended then give the extension a chance
+ // to add their information.
populateSpecificData(m_doc, root);
}
@@ -173,9 +185,11 @@
}
/**
- * Other classes that extend this class will overrid this mehood to
+ * Other classes that extend this class will override this mehood to
* add any specific information.
*
+ * @param Document - The document that will be returned to the processor
+ * @param Node - the <ext-error> Element that can be added to.
*/
protected void populateSpecificData(Document doc, Node node)
@@ -269,36 +283,6 @@
{
}
-
- /*
- public void dump()
- {
-
- try
- {
- //Serialize DOM
- OutputFormat format = new OutputFormat();
- //Writer will be a String
- StringWriter stringOut = new StringWriter();
-
- XMLSerializer serial = new XMLSerializer( stringOut, format );
-
- // As a DOM Serializer
- serial.asDOMSerializer();
-
- Element e = m_doc.getDocumentElement();
- serial.serialize(e);
- System.out.println("Extension Error:");
- String display = stringOut.toString();
- System.out.println( display );
- }
- catch(Exception e)
- {
- // Empty
- }
-
- }
- */
public Node getCurrentNode()
{
1.4 +6 -0
xml-xalan/java/src/org/apache/xalan/lib/sql/PooledConnection.java
Index: PooledConnection.java
===================================================================
RCS file:
/home/cvs/xml-xalan/java/src/org/apache/xalan/lib/sql/PooledConnection.java,v
retrieving revision 1.3
retrieving revision 1.4
diff -u -r1.3 -r1.4
--- PooledConnection.java 2001/03/12 02:04:07 1.3
+++ PooledConnection.java 2001/05/13 22:56:24 1.4
@@ -58,6 +58,12 @@
import java.sql.*;
+/**
+ * <p>
+ * A special container that wraps a standard JDBC Connection that is
+ * used to identify the connection inside the Connection Pool.
+ * </p>
+ */
public class PooledConnection
{
1.5 +8 -7
xml-xalan/java/src/org/apache/xalan/lib/sql/QueryParameter.java
Index: QueryParameter.java
===================================================================
RCS file:
/home/cvs/xml-xalan/java/src/org/apache/xalan/lib/sql/QueryParameter.java,v
retrieving revision 1.4
retrieving revision 1.5
diff -u -r1.4 -r1.5
--- QueryParameter.java 2001/04/18 20:20:37 1.4
+++ QueryParameter.java 2001/05/13 22:56:25 1.5
@@ -58,20 +58,21 @@
package org.apache.xalan.lib.sql;
/**
- * Title: <p>
- * Description: <p>
- * Copyright: Copyright (c) <p>
- * Company: <p>
- * @author John Gentilin
- * @version 1.0
+ * <p>
+ * The Query Parameter is a container class that is used to hold the
+ * Parameter information. The Xconnection will maintain a LinkedList
+ * of these parameters and will pass them in the the pquery.
+ * </p>
*/
-
public class QueryParameter
{
private String value;
private String type;
+ /**
+ * create a new entry
+ */
public QueryParameter(String v, String t)
{
value = v;
1.10 +28 -5 xml-xalan/java/src/org/apache/xalan/lib/sql/Row.java
Index: Row.java
===================================================================
RCS file: /home/cvs/xml-xalan/java/src/org/apache/xalan/lib/sql/Row.java,v
retrieving revision 1.9
retrieving revision 1.10
diff -u -r1.9 -r1.10
--- Row.java 2001/04/18 23:24:50 1.9
+++ Row.java 2001/05/13 22:56:25 1.10
@@ -68,11 +68,33 @@
import org.apache.xml.utils.*;
/**
- * <meta name="usage" content="experimental"/>
- * This class represents a row from a query result set. It is used
- * over and over, and so is certainly not fully DOM complient,
- * and will result in strange results in the stylesheet if the
- * user is not carefull.
+ * <p>
+ * This class represents a row from a query result set.
+ * The row object can be accessed in one of two modes.
+ * Streaming or cached.
+ * </p>
+ *
+ * <p>
+ * In <b>streaming mode</b>, the same Row object is used to represent
sequential
+ * database rows. Streaming mode only supports traversing the Document once.
+ * </p>
+ * <p>
+ * In <b>cached mode</b>, as the Document is traversed a new Row objec is
created
+ * for each database row and a full Document is built. Cached mode allows
+ * the Document to be traversed many times.
+ * </p>
+ * <p>
+ * If you are only traversing the Document once transfering the contents
+ * to the result tree, the streaming mode is the better option. The
+ * memory footprint is much less. Also streaming mode may be required
+ * for database queries that return a large number of rows because the memory
+ * footprint is limited to one row.
+ * </p>
+ * <p>
+ * Caching is controlled by two methods on the XConnection object called
+ * enableCacheNodes() or disableCacheNodes().
+ * </p>
+ *
*/
public class Row extends StreamableNode
{
@@ -104,6 +126,7 @@
*
* @param statement Owning document
* @param parent parent node, a row-set
+ * @param prev, the previous node in the row-set
*
*/
public Row(XStatement statement, RowSet parent, Row prev)
1.8 +30 -3 xml-xalan/java/src/org/apache/xalan/lib/sql/RowSet.java
Index: RowSet.java
===================================================================
RCS file: /home/cvs/xml-xalan/java/src/org/apache/xalan/lib/sql/RowSet.java,v
retrieving revision 1.7
retrieving revision 1.8
diff -u -r1.7 -r1.8
--- RowSet.java 2001/04/18 23:24:50 1.7
+++ RowSet.java 2001/05/13 22:56:25 1.8
@@ -67,10 +67,37 @@
import org.apache.xpath.patterns.NodeTest;
/**
- * <meta name="usage" content="experimental"/>
- * This class represents the row-set StreamableNode, a "streamable" holder
- * for the JDBC query result set.
+ * <p>
+ * The row-set is the controlling element in the Document that determines
+ * if the JDB ResultSet is being traversed or if the ResultSet MetaData
+ * is being interogated.
+ * <p>
+ *
+ * <pre>
+ * <p>
+ * The DTD for the Document is a follows.
+ * <row-set>
+ * <column-header [EMAIL PROTECTED]
org.apache.xalan.lib.sql.ColumnAttributes} >
+ * .
+ * . One for each column in the Query
+ * .
+ * <column-header />
+ * <row>
+ * .
+ * . One for each Row in the query
+ * .
+ * <col [EMAIL PROTECTED] ColumnAttribute} > The Data for the
column </col>
+ * .
+ * .
+ * . One for each column in the Row
+ * .
+ * .
+ * </row>
+ * <row-set>
+ * </p>
+ * </pre>
*/
+
public class RowSet extends StreamableNode
{
/** Let's keep track of the branch we are on */
1.6 +17 -7
xml-xalan/java/src/org/apache/xalan/lib/sql/SQLExtensionError.java
Index: SQLExtensionError.java
===================================================================
RCS file:
/home/cvs/xml-xalan/java/src/org/apache/xalan/lib/sql/SQLExtensionError.java,v
retrieving revision 1.5
retrieving revision 1.6
diff -u -r1.5 -r1.6
--- SQLExtensionError.java 2001/04/18 20:20:38 1.5
+++ SQLExtensionError.java 2001/05/13 22:56:25 1.6
@@ -71,14 +71,24 @@
import org.w3c.dom.CDATASection;
/**
- * Title: <p>
- * Description: <p>
- * Copyright: Copyright (c) <p>
- * Company: <p>
- * @author John Gentilin
- * @version 1.0
+ * <p>
+ * An Extension of the Extension Error Class that adds information
+ * about the SQL Exception. [EMAIL PROTECTED] ExtensionError}
+ * </p>
+ * <pre>
+ * <p>
+ * This class adds the following information to the Document
+ *
+ * <ext-error>
+ * <sql-error>
+ * <error-code> The SQL Error Code returned by the driver
</error-code>
+ * <state> The Current SQL Connection State </state>
+ * </sql-error>
+ * <ext-error>
+ * </p>
+ * </pre>
+ *
*/
-
public class SQLExtensionError extends ExtensionError {
private SQLException m_sql_ex = null;
1.12 +9 -2
xml-xalan/java/src/org/apache/xalan/lib/sql/StreamableNode.java
Index: StreamableNode.java
===================================================================
RCS file:
/home/cvs/xml-xalan/java/src/org/apache/xalan/lib/sql/StreamableNode.java,v
retrieving revision 1.11
retrieving revision 1.12
diff -u -r1.11 -r1.12
--- StreamableNode.java 2001/04/18 23:24:51 1.11
+++ StreamableNode.java 2001/05/13 22:56:25 1.12
@@ -69,8 +69,15 @@
import org.apache.xpath.axes.AxesWalker;
/**
- * <meta name="usage" content="experimental"/>
- * This is the superclass for all nodes in the org.apache.xalan.lib.sql
package.
+ * <p>
+ * The StreamableNode really just provides a base implemtation
+ * for the other SQL Node based classes. It support keeping track
+ * of the Document Order Index where it is just incermented to assure
+ * that the node are considered seperate and assign a distance in the
+ * Document. It also provides a common reference to the Document Root
+ * or the XStatement object.
+ * </p>
+ *
*/
public class StreamableNode extends UnImplNode
implements NodeTestFilter, NamedNodeMap, DOMOrder
1.13 +50 -11
xml-xalan/java/src/org/apache/xalan/lib/sql/XConnection.java
Index: XConnection.java
===================================================================
RCS file:
/home/cvs/xml-xalan/java/src/org/apache/xalan/lib/sql/XConnection.java,v
retrieving revision 1.12
retrieving revision 1.13
diff -u -r1.12 -r1.13
--- XConnection.java 2001/04/18 23:24:51 1.12
+++ XConnection.java 2001/05/13 22:56:25 1.13
@@ -75,17 +75,56 @@
import org.apache.xalan.stree.ElementImpl;
/**
- * An XSLT extension that allows a stylesheet to
- * access JDBC data. From the stylesheet perspective,
- * XConnection provides 3 extension functions: new(),
- * query(), and close().
- * Use new() to call one of XConnection constructors, which
- * establishes a JDBC driver connection to a data source and
- * returns an XConnection object.
- * Then use the XConnection object query() method to return a
- * result set in the form of a row-set element.
- * When you have finished working with the row-set, call the
- * XConnection object close() method to terminate the connection.
+ * <p>
+ * The XConnection Object is the main (currently the only) interface
+ * into the SQL Extensions from the Transformer. It is initiated by
+ * supplying connection information and is used by instructing it
+ * to produce a JDBC Query.
+ * </p>
+ * </p>
+ * * The XConnection Object provides several methods of connecting to a
+ * JDBC Source. There are two major connection methods, one where the
+ * actual connection is established outside the scope of the trasformer
+ * [EMAIL PROTECTED] org.apache.xalan.lib.sql.XConnectionPoolManager} and
the other
+ * where the Connection information is supplied as part or either the
+ * XSLT Stylesheet or the XML Document.
+ *</p>
+ * <p>
+ * If the Connection is part of an external connection, the connection is
+ * identified just by its connection pool name. In this mode, the connection
+ * pool manager will be interogated for the connection pool instance and
+ * a new connection is pulled from there.
+ * </p>
+ * <p>
+ * When the Connection information is supplied from the Stylesheet or
Document,
+ * the minimal amount of information that needs to be supplied is the JDBC
+ * class or driver and the URL to connect to that Driver.
+ * </p>
+ * </p>
+ * Top maintain backward compatibility with previous versions of the
extension,
+ * supplying connection information in the constructor is still supported.
+ * </p>
+ * <p>
+ * The new method is to supply the connection information via the connect
+ * method.
+ * </p>
+ * <p>
+ * Once a connection is established, a Database query must be performed to
+ * have data to work with. This can be accomplished in one of two way.
+ * </p>
+ * <p>
+ * The straight query; the query method allow a simple query to be excuted.
+ * This methode qucikly becomes cumbersome when parts of the query are being
+ * created dynamically as part of the data but is easiest to implement for a
+ * simple static query.
+ * </p>
+ * <p>
+ * The parameter based query; the pquery method allows the Stylesheet
designer
+ * to create a simple query with place markers for the dynamic components.
+ * Form there the parameters are added in order. The pquery uses the JDBC
+ * prepated statement to do its work. Parmateres also allow the Stylesheet
+ * designer to specify the parameter type.
+ * </p>
*/
public class XConnection
{
1.5 +19 -10
xml-xalan/java/src/org/apache/xalan/lib/sql/XConnectionPoolManager.java
Index: XConnectionPoolManager.java
===================================================================
RCS file:
/home/cvs/xml-xalan/java/src/org/apache/xalan/lib/sql/XConnectionPoolManager.java,v
retrieving revision 1.4
retrieving revision 1.5
diff -u -r1.4 -r1.5
--- XConnectionPoolManager.java 2001/03/15 17:50:04 1.4
+++ XConnectionPoolManager.java 2001/05/13 22:56:25 1.5
@@ -55,23 +55,32 @@
* <http://www.apache.org/>.
*/
+package org.apache.xalan.lib.sql;
- package org.apache.xalan.lib.sql;
+import java.util.Hashtable;
+import java.lang.IllegalArgumentException;
/**
- * <P>
- * Provides a mechinism where a shared collection of connection
- * pools can exist. Connection Pools are referenced by name.
- * <P><HR>
+ * <p>
+ * The ConnectionPoolManager provides a static container that allows
+ * external programs, inside the same JVM, to supply a set of JDBC
+ * connections to the Xalan transformer.
+ * </p>
+ * <p>
+ * This provides two primary features.
*
- * Title: PoolManager<p>
- * @author John Gentilin
- * @version 1.0
+ * <b>External Connections</b>; The Stylesheet no longer has to have
knowladge
+ * of the database login information. The External program can create the
+ * connections that are already connected to the database. The Stylesheet
+ * only needs to know the name of the connection group.
*
+ * <b>ConnectionPooling</b>; as a performance enhancement the use of database
+ * connections to be pooled and resused. Most of the time in using a
+ * connection is makeing the actual connection to the database, i.e. loging
+ * on. With connection pools, this step is only done once and reused.
+ * </p?
*/
-import java.util.Hashtable;
-import java.lang.IllegalArgumentException;
public class XConnectionPoolManager
{
1.14 +9 -0
xml-xalan/java/src/org/apache/xalan/lib/sql/XStatement.java
Index: XStatement.java
===================================================================
RCS file:
/home/cvs/xml-xalan/java/src/org/apache/xalan/lib/sql/XStatement.java,v
retrieving revision 1.13
retrieving revision 1.14
diff -u -r1.13 -r1.14
--- XStatement.java 2001/04/18 23:24:51 1.13
+++ XStatement.java 2001/05/13 22:56:25 1.14
@@ -84,9 +84,12 @@
import org.apache.xalan.res.XSLTErrorResources;
/**
+ * <p>
* Represents a JDBC query statement. Also acts as both a
* NodeIterator and the Document node for the row-set representation
* of the query result set.
+ * </p>
+ *
*/
public class XStatement extends StreamableNode
implements NodeIterator, ContextNodeList, Cloneable
@@ -259,12 +262,18 @@
m_statement = m_pstatement;
if (DEBUG)
+
System.out.println("Exiting XStatement constructor");
}
/**
* Set the parameter for a Prepared Statement
+ * @param int pos, the Position of the place holder in the prepared
statement
+ * @param PreparedStatement the current pquery being worked on
+ * @param QueryParameter the Vaue and type of that value to be added.
+ *
+ * @throws SQLException - will be converted to an ext-error
*
*/
public void setParameter(int pos, PreparedStatement stmt, QueryParameter p)
1.7 +112 -16 xml-xalan/java/src/org/apache/xalan/lib/sql/package.html
Index: package.html
===================================================================
RCS file: /home/cvs/xml-xalan/java/src/org/apache/xalan/lib/sql/package.html,v
retrieving revision 1.6
retrieving revision 1.7
diff -u -r1.6 -r1.7
--- package.html 2001/05/04 21:02:37 1.6
+++ package.html 2001/05/13 22:56:25 1.7
@@ -1,30 +1,88 @@
<html>
<title>Xalan SQL Extension</title>
<body>
- <p><em>**Experimental**</em> Provides extension functions for connecting
to a JDBC data source, executing a query,
+ <p>Provides extension functions for connecting to a JDBC data source,
executing a query,
and working incrementally through "streamable" result set.<p>
- <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>
+ The SQL Extension operates in on of two modes, streaming or cached. In
streaming modes, there is only
+ one row object that is allocated and its contents are updated as the row
element set is traversed. In
+ this mode, the element set can only be traversed forward since there is
only one row node object, no
+ history is ever kept. Streaming mode is advantages when SQL Queries are
large and memory is an issue
+ since the number of record returned do not affect them memory footprint.
It does however come with
+ the restriction that the result set can only be traversed once. In cached
mode, as the result set
+ is traversed, history of the previous rows are recorded, hence the result
set can then be traversed
+ forward or backward and as many times as necessary. In this mode, there
is a downside that memory
+ is consumed as the result set is traversed.
+
+ The default mode is cached mode and may be changed using the set with the
two methods enableCacheNodes
+ and disableCahcedNodes.
+ </p>
+ <p>
+ <HR>
+ <em>
+ **Experimental** This package has been marked as experimental since the
streaming mode
+ is not fully implemented and is not the default mode. Disabling node
caching (streaming mode) may
+ not return the full result set.
+ <HR>
+ </em>
+ </p>
+
<p>XConnection provides three extension functions that you can use in
your stylesheet.</p>
+ [EMAIL PROTECTED] org.apache.xalan.lib.sql.XConnection}
<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 connction pools, SQL library includes a
ConnectionPool interface and a implementation:
- DefaultConnectionPool. You can also provide your own ConnectionPool
implementation.<br/><br/></li>
+ object. You can use one of the constructors creates a connection pool
from which stylesheets can obtain connections
+ to a data source. To support connection pools, SQL library includes a
Connection-Pool interface and a implementation:
+ DefaultConnectionPool. You can also provide your own Connection-Pool
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
+ <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
+ <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>
+ <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() or pquery() extension function returns 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.
+ 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>
+
+ <h2>XML Sample of the return Data</h2>
+ <p>This example displays the result set from a table in a sample
InstantDB database.</p>
+<pre>
+ <Column-header attribute=value>
+ One column header entry for each column in the query.
+ Each column header contains a set of attributes describing the MetaData
+ for that column. For a list of possible attributes see
ColumnAttribute.java.
+ [EMAIL PROTECTED] ColumnAttribute}
+ <Column-header>
+
+ <row-set>
+
+ <row>
+ In Streaming Mode, Caching Disabled, only one row object is
returned.
+ The benefit of streaming mode is that the memory footprint is the
same
+ regardless of the size of the query. A downside to streaming mode
is that
+ the row elements can <b>ONLY BE TRAVERSED ONCE</b>. In cached
mode, there
+ is a new row element for each row in the result set. The row
elements can
+ be traversed as many times as needed.
+ <b>Currently the default mode is cached, streaming mode is
experimental
+ and currently does not work </b>
+
+ <col>Value attribute=value </col>
+ One column entry for each column in the query.
+ Each column contains a set of attributes describing the MetaData
+ for that column. Foa a list of possible attributes see
ColumnAttribute.java.
+ <col attribute=value >Value</col>
+ <col attribute=value >Value</col>
+ </row>
+
+ </row-set>
+
+
+</pre>
+
<h2>Example</h2>
<p>This example displays the result set from a table in a sample
InstantDB database.</p>
<pre><?xml version="1.0"?>
@@ -34,7 +92,7 @@
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"
@@ -57,7 +115,7 @@
<xsl:text>&#10;</xsl:text>
</TABLE>
</BODY>
- </HTML>
+ </HTML>
<!-- 3. Close the connection -->
<xsl:value-of select="sql:close($products)"/>
</xsl:template>
@@ -76,6 +134,44 @@
</xsl:template>
</xsl:stylesheet>
-</pre>
+</pre>
+
+
+ <h1>Handling of SQL Errors and other exceptions in this extension</h1>
+ <p>
+ <HR>
+ <em>**Experimental**</em> This Extension enhancement is extremelly
experimental
+ and is being used to test its validity. </em>
+ <HR>
+ </p>
+ <p>
+ The SQL Extension package provides a mechinism to capture errors that
occur as a
+ result of an SQL Exception.
+ </p>
+ <p>
+ The document that is returned provides the Exception information along
+ with the SQL Error and SQL State.
+
+ To detect if an error occured, /ext-error can be evaluated using the
xsl:test
+ function. A value of true reflects that an error ha occured.
+
+ See the sample code in java/samples/extension/sql/show-error for a working
example.
+ </p>
+
+ <pre>
+ <p>
+ <h2>Sample of an Error Return in the event of an SQL Error</h2>
+ <ext-error>
+ <exception-info>
+ <message> Message from the Exception thrown </message>
+ <sql-error>
+ <error-code> The SQL Error Code returned by the
driver</error-code>
+ <state> The Current SQL Connection State </state>
+ </sql-error>
+ </exception-info>
+ </ext-error>
+ </p>
+ </pre>
+
</body>
-</html>
\ No newline at end of file
+</html>
---------------------------------------------------------------------
To unsubscribe, e-mail: [EMAIL PROTECTED]
For additional commands, e-mail: [EMAIL PROTECTED]
