org.apache.xalan.lib.sql
Class XConnection

java.lang.Object
  org.apache.xalan.lib.sql.XConnection

public class XConnection

extends Object

An XSLT extension that allows a stylesheet to access JDBC data. It is accessed by specifying a namespace URI as follows:

    xmlns:sql="http://xml.apache.org/xalan/sql"
 

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.

Field Summary

private static boolean	DEBUG Flag for DEBUG mode
private ConnectionPool	m_ConnectionPool The Current Connection Pool in Use.
private boolean	m_DefaultPoolingEnabled If a default Connection Pool is used. i.e.
private SQLErrorDocument	m_Error Allow the SQL Extensions to return null on error.
private boolean	m_IsDefaultPool
private boolean	m_IsStreamingEnabled This flag will be used to indicate to the SQLDocument to use Streaming mode.
private Vector	m_OpenSQLDocuments As we do queries, we will produce SQL Documents.
private Vector	m_ParameterList For PreparedStatements, we need a place to to store the parameters in a vector.
private ConnectionPoolManager	m_PoolMgr Let's keep a copy of the ConnectionPoolMgr in alive here so we are keeping the static pool alive We will also use this Pool Manager to register our default pools.

Constructor Summary

XConnection()

XConnection(ExpressionContext exprContext, org.w3c.dom.NodeList list)

XConnection(ExpressionContext exprContext, String ConnPoolName)

XConnection(ExpressionContext exprContext, String driver, String dbURL)

XConnection(ExpressionContext exprContext, String driver, String dbURL, org.w3c.dom.Element protocolElem)

XConnection(ExpressionContext exprContext, String driver, String dbURL, String user, String password)

Method Summary

void	addParameter(String value) Add an untyped value to the parameter list.
void	addParameterFromElement(org.w3c.dom.Element e) Add a single parameter to the parameter list formatted as an Element
void	addParameterFromElement(org.w3c.dom.NodeList nl) Add a section of parameters to the Parameter List Do each element from the list
private void	addParameters(org.w3c.dom.Element elem)
void	addParameterWithType(String value, String Type) Add a typed parameter to the parameter list.
private void	buildErrorDocument(ExpressionContext exprContext, Exception excp)
private void	buildErrorDocument(ExpressionContext exprContext, SQLException excp)
void	clearParameters()
void	close() Close the connection to the data source.
void	close(SQLDocument sqldoc) Close the connection to the data source.
XBooleanStatic	connect(ExpressionContext exprContext, org.w3c.dom.Element protocolElem)
XBooleanStatic	connect(ExpressionContext exprContext, org.w3c.dom.NodeList list)
XBooleanStatic	connect(ExpressionContext exprContext, String ConnPoolName) Create an XConnection using the name of an existing Connection Pool
XBooleanStatic	connect(ExpressionContext exprContext, String driver, String dbURL) Create an XConnection object with just a driver and database URL.
XBooleanStatic	connect(ExpressionContext exprContext, String driver, String dbURL, org.w3c.dom.Element protocolElem) Create an XConnection object with a connection protocol
XBooleanStatic	connect(ExpressionContext exprContext, String driver, String dbURL, String user, String password) Create an XConnection object with user ID and password.
void	disableDefaultConnectionPool() See enableDefaultConnectionPool
void	disableStreamingMode() Control how the SQL Document uses memory.
void	enableDefaultConnectionPool() There is a problem with some JDBC drivers when a Connection is open and the JVM shutsdown.
void	enableStreamingMode() Control how the SQL Document uses memory.
protected void	finalize() Called by the garbage collector on an object when garbage collection determines that there are no more references to the object.
DTM	getError() Provide access to the last error that occued.
private void	init(String driver, String dbURL, Properties prop) Initilize is being called because we did not have an existing Connection Pool, so let's see if we created one already or lets create one ourselves.
private void	initFromElement(org.w3c.dom.Element e) Allow the database connection information to be sepcified in the XML tree.
DTM	pquery(ExpressionContext exprContext, String queryString) Execute a parameterized query statement by instantiating an
DTM	pquery(ExpressionContext exprContext, String queryString, String typeInfo) Execute a parameterized query statement by instantiating an
DTM	query(ExpressionContext exprContext, String queryString) Execute a query statement by instantiating an
void	setParameter(int pos, PreparedStatement stmt, QueryParameter p) Set the parameter for a Prepared Statement

Methods inherited from class java.lang.Object

clone, equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

DEBUG

private static final boolean DEBUG

Flag for DEBUG mode

See Also:

Constant Field Values

m_ConnectionPool

private ConnectionPool m_ConnectionPool

The Current Connection Pool in Use. An XConnection can only represent one query at a time, prior to doing some type of query.

m_DefaultPoolingEnabled

private boolean m_DefaultPoolingEnabled

If a default Connection Pool is used. i.e. A connection Pool that is created internally, then do we actually allow pools to be created. Due to the archititure of the Xalan Extensions, there is no notification of when the Extension is being unloaded and as such, there is a good chance that JDBC COnnections are not closed. A finalized is provided to try and catch this situation but since support of finalizers is inconsistant across JVM's this may cause a problem. The robustness of the JDBC Driver is also at issue here. if a controlled shutdown is provided by the driver then default conntectiom pools are OK.

m_OpenSQLDocuments

private Vector m_OpenSQLDocuments

As we do queries, we will produce SQL Documents. Any ony may produce one or more SQL Documents so that the current connection information may be easilly reused. This collection will hold a collection of all the documents created. As Documents are closed, they will be removed from the collection and told to free all the used resources.

m_PoolMgr

private ConnectionPoolManager m_PoolMgr

Let's keep a copy of the ConnectionPoolMgr in alive here so we are keeping the static pool alive We will also use this Pool Manager to register our default pools.

m_ParameterList

private Vector m_ParameterList

For PreparedStatements, we need a place to to store the parameters in a vector.

m_Error

private SQLErrorDocument m_Error

Allow the SQL Extensions to return null on error. The Error information will be stored in a seperate Error Document that can easily be retrived using the getError() method. %REVIEW% This functionality will probably be buried inside the SQLDocument.

m_IsDefaultPool

private boolean m_IsDefaultPool

m_IsStreamingEnabled

private boolean m_IsStreamingEnabled

This flag will be used to indicate to the SQLDocument to use Streaming mode. Streeaming Mode will reduce the memory footprint to a fixed amount but will not let you traverse the tree more than once since the Row data will be reused for every Row in the Query.

Constructor Detail

XConnection

public XConnection()

XConnection

public XConnection(ExpressionContext exprContext,
                   String ConnPoolName)

Parameters:

exprContext -

ConnPoolName -

XConnection

public XConnection(ExpressionContext exprContext,
                   String driver,
                   String dbURL)

Parameters:

exprContext -

driver -

dbURL -

XConnection

public XConnection(ExpressionContext exprContext,
                   org.w3c.dom.NodeList list)

Parameters:

exprContext -

list -

XConnection

public XConnection(ExpressionContext exprContext,
                   String driver,
                   String dbURL,
                   String user,
                   String password)

Parameters:

exprContext -

driver -

dbURL -

user -

password -

XConnection

public XConnection(ExpressionContext exprContext,
                   String driver,
                   String dbURL,
                   org.w3c.dom.Element protocolElem)

Parameters:

exprContext -

driver -

dbURL -

protocolElem -

Method Detail

connect

public XBooleanStatic connect(ExpressionContext exprContext,
                              String ConnPoolName)

Create an XConnection using the name of an existing Connection Pool

Parameters:

exprContext -

ConnPoolName -

Returns:

connect

public XBooleanStatic connect(ExpressionContext exprContext,
                              String driver,
                              String dbURL)

Create an XConnection object with just a driver and database URL.

Parameters:

exprContext -

driver - JDBC driver of the form foo.bar.Driver.

dbURL - database URL of the form jdbc:subprotocol:subname.

Returns:

connect

public XBooleanStatic connect(ExpressionContext exprContext,
                              org.w3c.dom.Element protocolElem)

Parameters:

exprContext -

protocolElem -

Returns:

connect

public XBooleanStatic connect(ExpressionContext exprContext,
                              org.w3c.dom.NodeList list)

Parameters:

exprContext -

list -

Returns:

connect

public XBooleanStatic connect(ExpressionContext exprContext,
                              String driver,
                              String dbURL,
                              String user,
                              String password)

Create an XConnection object with user ID and password.

Parameters:

exprContext -

driver - JDBC driver of the form foo.bar.Driver.

dbURL - database URL of the form jdbc:subprotocol:subname.

user - user ID.

password - connection password.

Returns:

connect

public XBooleanStatic connect(ExpressionContext exprContext,
                              String driver,
                              String dbURL,
                              org.w3c.dom.Element protocolElem)

Create an XConnection object with a connection protocol

Parameters:

exprContext -

driver - JDBC driver of the form foo.bar.Driver.

dbURL - database URL of the form jdbc:subprotocol:subname.

protocolElem - list of string tag/value connection arguments, normally including at least "user" and "password".

Returns:

initFromElement

private void initFromElement(org.w3c.dom.Element e)
                      throws SQLException

Allow the database connection information to be sepcified in the XML tree. The connection information could also be externally originated and passed in as an XSL Parameter. The required XML Format is as follows. A document fragment is needed to specify the connection information the top tag name is not specific for this code, we are only interested in the tags inside. Specify the driver name for this connection pool drivername Specify the URL for the driver in this connection pool url Specify the password for this connection pool password Specify the username for this connection pool username You can add extra protocol items including the User Name & Password with the protocol tag. For each extra protocol item, add a new element where the name of the item is specified as the name attribute and and its value as the elements value. value

Parameters:

e -

Returns:

Throws:

SQLException

init

private void init(String driver,
                  String dbURL,
                  Properties prop)
           throws SQLException

Initilize is being called because we did not have an existing Connection Pool, so let's see if we created one already or lets create one ourselves.

Parameters:

driver -

dbURL -

prop -

Returns:

Throws:

SQLException

query

public DTM query(ExpressionContext exprContext,
                 String queryString)

Execute a query statement by instantiating an

Parameters:

exprContext -

queryString - the SQL query.

Returns:

XStatement implements NodeIterator.

Throws:

SQLException

pquery

public DTM pquery(ExpressionContext exprContext,
                  String queryString)

Execute a parameterized query statement by instantiating an

Parameters:

exprContext -

queryString - the SQL query.

Returns:

XStatement implements NodeIterator.

Throws:

SQLException

pquery

public DTM pquery(ExpressionContext exprContext,
                  String queryString,
                  String typeInfo)

Execute a parameterized query statement by instantiating an

Parameters:

exprContext -

queryString - the SQL query.

typeInfo -

Returns:

XStatement implements NodeIterator.

Throws:

SQLException

addParameter

public void addParameter(String value)

Add an untyped value to the parameter list.

Parameters:

value -

Returns:

addParameterWithType

public void addParameterWithType(String value,
                                 String Type)

Add a typed parameter to the parameter list.

Parameters:

value -

Type -

Returns:

addParameterFromElement

public void addParameterFromElement(org.w3c.dom.Element e)

Add a single parameter to the parameter list formatted as an Element

Parameters:

e -

Returns:

addParameterFromElement

public void addParameterFromElement(org.w3c.dom.NodeList nl)

Add a section of parameters to the Parameter List Do each element from the list

Parameters:

nl -

Returns:

addParameters

private void addParameters(org.w3c.dom.Element elem)

Parameters:

elem -

Returns:

clearParameters

public void clearParameters()

Returns:

enableDefaultConnectionPool

public void enableDefaultConnectionPool()

There is a problem with some JDBC drivers when a Connection is open and the JVM shutsdown. If there is a problem, there is no way to control the currently open connections in the pool. So for the default connection pool, the actuall pooling mechinsm is disabled by default. The Stylesheet designer can re-enabled pooling to take advantage of connection pools. The connection pool can even be disabled which will close all outstanding connections.

Returns:

disableDefaultConnectionPool

public void disableDefaultConnectionPool()

See enableDefaultConnectionPool

Returns:

enableStreamingMode

public void enableStreamingMode()

Control how the SQL Document uses memory. In Streaming Mode, memory consumption is greatly reduces so you can have queries of unlimited size but it will not let you traverse the data more than once.

Returns:

disableStreamingMode

public void disableStreamingMode()

Control how the SQL Document uses memory. In Streaming Mode, memory consumption is greatly reduces so you can have queries of unlimited size but it will not let you traverse the data more than once.

Returns:

getError

public DTM getError()

Provide access to the last error that occued. This error may be over written when the next operation occurs.

Returns:

close

public void close()
           throws SQLException

Close the connection to the data source.

Returns:

Throws:

SQLException

close

public void close(SQLDocument sqldoc)
           throws SQLException

Close the connection to the data source. Only close the connections for a single document.

Parameters:

sqldoc -

Returns:

Throws:

SQLException

setParameter

public void setParameter(int pos,
                         PreparedStatement stmt,
                         QueryParameter p)
                  throws SQLException

Set the parameter for a Prepared Statement

Parameters:

pos -

stmt -

p -

Returns:

Throws:

SQLException

buildErrorDocument

private void buildErrorDocument(ExpressionContext exprContext,
                                SQLException excp)

Parameters:

exprContext -

excp -

Returns:

buildErrorDocument

private void buildErrorDocument(ExpressionContext exprContext,
                                Exception excp)

Parameters:

exprContext -

excp -

Returns:

finalize

protected void finalize()

Description copied from class: Object

Called by the garbage collector on an object when garbage collection determines that there are no more references to the object. A subclass overrides the finalize method to dispose of system resources or to perform other cleanup.

The general contract of finalize is that it is invoked if and when the Java^TM virtual machine has determined that there is no longer any means by which this object can be accessed by any thread that has not yet died, except as a result of an action taken by the finalization of some other object or class which is ready to be finalized. The finalize method may take any action, including making this object available again to other threads; the usual purpose of finalize, however, is to perform cleanup actions before the object is irrevocably discarded. For example, the finalize method for an object that represents an input/output connection might perform explicit I/O transactions to break the connection before the object is permanently discarded.

The finalize method of class Object performs no special action; it simply returns normally. Subclasses of Object may override this definition.

The Java programming language does not guarantee which thread will invoke the finalize method for any given object. It is guaranteed, however, that the thread that invokes finalize will not be holding any user-visible synchronization locks when finalize is invoked. If an uncaught exception is thrown by the finalize method, the exception is ignored and finalization of that object terminates.

After the finalize method has been invoked for an object, no further action is taken until the Java virtual machine has again determined that there is no longer any means by which this object can be accessed by any thread that has not yet died, including possible actions by other objects or classes which are ready to be finalized, at which point the object may be discarded.

The finalize method is never invoked more than once by a Java virtual machine for any given object.

Any exception thrown by the finalize method causes the finalization of this object to be halted, but is otherwise ignored.

Overrides:

finalize in class Object

Returns: