Database Connections
*Providing Connection information in the XSL File
*XConnection(Sring DBDriver, String DBurl)
*XConnection(String DBDriver, String DBurl, String User, String Password)
*XConnection(String DBDriver, String DBurl, NodeList Properties)
*Providing Connection information in the XML File
*XConnection(NodeList ConnectionData)
*Using Existing Connections in a connection pool
*XConnection(String ConnectionName)
*Connection Pools
*Overview
*Creating a new wrapper
*The Default Connection Pool
*Queries
*Standard queries
*Parameter based queries
*Overview
*Handling Value and Type Information
*Examples
*Basic
*External Connections
*PQuery
*The SQL Extension provides 2 basic mechanisms to connect to the database. The connection information can either be provided in the XSL/XML or pulled from a Connection Pool that was created outside the Xalan library.
The XConnection object is used to represent a connection to the database. The actual connection is established through the object constructor. Each of the different mechanisms differs with the signature of the extension.
When the connection information is provided in the XSL or XML sources, a default connection pool will be created on its behalf but due to restrictions in some drivers, the actual pooling of connections will disabled by default. See Connection Pools, The Default Connection Pool.
Providing Connection information in the XSL File
When providing Connection Information from the XSL or XML input sources, the XConnection object will create a default connection pool that will exist for the lifetime of the Transformation object.
XConnection(Sring DBDriver, String DBurl)
Create a standard JDBC connection using the specified driver and URL. This is used primarily for local databases that do not return user identification.
XConnection(String DBDriver, String DBurl, String User, String Password)
Create a standard JDBC Connection, which also provides user identification.
XConnection(String DBDriver, String DBurl, NodeList Properties)
Create a standard JDBC connection that loads the database driver using the specified URL. The NodeList provides will then be converted into a properties object which will be passes in when getting the JDBC connection.
Providing Connection information in the XML File
XConnection(NodeList ConnectionData)
Create connection and pass in the complete connection information as a Nodelist. This allows the XML data to provide the connection information. The node list will be used to create a named value pair list where the Node Name will represent the name and the Node Value will be the value. Required Tags consist of "dbdriver" and "dburl". Optional tags can include "user" and "password" to specify the user identification but can also include any other database connection property.
Using Existing Connections in a connection pool
XConnection(String ConnectionName)
The Xalan SQL Extensions allows the controlling program to create an external JDBC Connection Pool and reference the connection pools by name inside the Stylsheet. Besides providing a mechanism to share connection resources with Xalan, is also allows the Stylesheet to not be concerned with the Connection properties all together.
Connection pools allow the Xalan Transformer to share connections with the rest of the application. Any existing JDBC Connection pool should be compatible with the Xalan Transformer by creating a wrapper class around the specific connection pool and registering it with the XConnectionPoolManager.
The org.apache.xalan.lib.sql.connection is the interface that needs to be implemented be compatible with the Xalan Transformer.
To provide a uniform internal programming model, the XConnection object will create an instance of the DefaultConnectionPool. By default the Default Connection Pool will
query(XConnection conn, String SQL)
Standard queries take a connection as arguments, an XConnection and the SQL String. It is the responsibility of the Stylesheet designer to format the SQL String completely including any quotes that are necessary. For static queries this is fine because the sting can be assembled at design time.
Parameter based queries are used when data that dynamically changes the query needs to be supplied from the XML Data.
The Stylesheet will provide the skeleton template of the query with place holders where the data goes, then provides several mechanisms to apply that data from the XML Data.
Parameter based queries take advantage of the JDBC Prepared statement semantics.
Handling Value and Type Information
When using parameterized query the place markers in the query (a "?") will be replaced with data that is provided using one of the addParameter.. methods. When adding data to a parameter based query, the type of each value must also be included so that real query can be produced. The type information can be passed in as a component of the Query or the Data which ever is more convenient to the Stylesheet designer.
If the type information is missing for a data point, the default type is set to String.
The list of possible value types include, string, bigdecimal, boolean, bytes, date, double, float, long, short, time, timestamp.
pquery(XConnection, query)
When just the query statement is passed as a parameter, the Type information must be passed in as a component of the data.
pquery(XConnection, query, typeinfo)
This allows the query to be specified using the "?" place holders and defining the type for each of the placeholders as a comma separated value string. i.e. "string,int,string,datetime"
addParameter(XConnection, value)
Add a new value to be used with a pquery, each new value is appended to a list that will be merged into the query statement when the pquery statement is executed. All data points must be added prior to executing the pquery statement.
addParameterWithType(XConnection, value,type)
Add a new value specifying the type information also.
addParameterFromElement(XConnection, NodeList)
Add a block of data points from a node list queried from the XML Data Source. Each tag name at the START_TAG and TAG1 level are irrelevant, the only significant information is the value and possibly the type attribute.
If the type attribute is present, it will set the current type. If the type information is missing, it will either be provide through one of the other mechanisms or default to a string.
<START_TAG>
<TAG1> type="int">value</TAG1>
</START_TAG
Typical implementation
<xsl:param name="plist" select="/START_TAG" />
<xsl:addParameterFromElement( $conn, $plist);
All of the following examples use the Enhydra InstantDB which is included as part of the Xalan distribution to operate. Please read the Enhydra documentation on managing an InstantDB http://www.instantdb.co.uk/
The XML/XSL Files (dbinfo.xml and dbtest.xsl) provide an example of implementing a basic connection where the connection information is provided in the XSL file using a static query.
The XML/XSL Files (dbinfo.xml and dbtest-cinfo.xsl) provide an example of implementing a basic connection where the connection information is provided as a node list in the XML file using a static query.
The java file ExternalConnection demonstrates how to build a JDBC connection pool that is independent of Xalan. The actual connection pool used is the Default Connection pool inside the Xalan SQL Extension, which already implements the ConnectionPool interface so no wrapper was required. To implement a third party connection pool, a wrapper function must be implemented.
The XML/XSL file (dbInfo.xml and dbtest.xsl) provide an example of implementing a parameter based query.