net.windward.datasource.jdbc
Class JdbcDataSource

java.lang.Object
  |
  +--net.windward.datasource.jdbc.JdbcDataSource

All Implemented Interfaces:

DataSourceProvider

public class JdbcDataSource

extends java.lang.Object

implements DataSourceProvider

This supplies a data source to Windward Reports using jdbc. The DataSourceProvider class is built on the concept of xml nodes. For this class, a node is a ResultSet returned by a jdbc call to Statement.executeQuery().
An xml file always has the concept of the current node. This is not the case with a sql database - there is no current ResultSet. A ResultSet is only generated by the wr:query and the wr:foreach tags. Therefore, all other tags only make sense if they use the var attribute from a query or foreach to identify the ResultSet they are to be applied to. A tag not identifying a ResultSet will throw an exception.

A query or foreach tag can reference a var from another query or foreach tag using ${var.item}.. An XPath query can describe a node as well as an element. In this class a query defines a ResultSet and is only an element.
Also, with xml you can use xpath in each tag performing complex logic in determining what text to return. It is very different for sql. The foreach or query can have complex logic. But the other tags can only return an element from a result set that the foreach/query earlier returned or do a single select.

When using a var (<wr:forEach var="result"/>) that identifies a result set, you can use the following in a tag:

• ${result[1]} - is column element [1] in the row presently on (1-based)
• ${result[2][1]} - is column element [1] in the row + 2 presently on (0-based)
• ${result.NAME} - is the column element named NAME in the row presently on
• ${result[2].NAME} - is the column element named NAME in the row + 2 presently on
• ${result.columnNames[1]} - is the name of column 1 (1-based)

The use of result[N] where N is a row number is limited to values of 0...N where N is step-1. result[1] is treated as column 1 of the row presently on, it is only result[0][1] and result[0].NAME that can hit rows other than the row presently on. This functionality requires a result set that can move to previous as well as next. If the JDBC driver you use cannot handle a call to previous, you cannot use this functionality. An <if select= ... > will return true if the passed in select returns a ResultSet with one or more rows. An <if select="select count (*) from customers" notEmpty="true"> will perform two steps. The first step is it will return false if there are no results returned. If results are returned it assumes the select is a count and will do a return ResultSet.getInt(1) > 0;. This does not look at the select statement, it is the notEmpty="true" that puts it in this mode. Notes: statements are created using Connection.createStatement(ResultSet.TYPE_SCROLL_INSENSITIVE, ResultSet.CONCUR_READ_ONLY) The TYPE_SCROLL_INSENSITIVE or TYPE_SCROLL_SENSITIVE setting is necessary in some jdbc drivers for ResultSet.isLast() to function.

Version:

2.0 2 January 2004

Constructor Summary

JdbcDataSource(java.sql.Connection conn)
Create a DataSourceProvider that uses jdbc to access a SQL database.

JdbcDataSource(java.lang.String className, java.lang.String url)
Create a DataSourceProvider that uses jdbc to access a SQL database.

JdbcDataSource(java.lang.String className, java.lang.String url, java.lang.String username, java.lang.String password)
Create a DataSourceProvider that uses jdbc to access a SQL database.

Method Summary

java.lang.String	addView(java.lang.String key, java.lang.String select) This creates a view using the passed in select statement.
void	close() Called when processing is complete.
java.lang.String	dump() Display the entire dataset.
DataSourceNode	getRootNode() Returns the root node for this data set.
TagAttributes[]	getTagAttributes() Returns the allowed attributes for all tags.
void	log() Log all info about this datasource to debug.
void	setMap(java.util.Map map) Adds a map that is used for ${variable} substitution.
void	validateTag(BaseTag xmlTag) Verifys that a tag has all required attributes and no unknown attributes.

Methods inherited from class java.lang.Object

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

Constructor Detail

JdbcDataSource

public JdbcDataSource(java.lang.String className,
                      java.lang.String url,
                      java.lang.String username,
                      java.lang.String password)
               throws DataSourceException

Create a DataSourceProvider that uses jdbc to access a SQL database. This constructor calls Class.forName().getInstance() followed by DriverManager.getConnection(). It is recomended that you do not use this constructor as it cannot use connection pooling (unless your J2EE application server implements connecion pooling for the DriverManager call).
This object will close the connection created when close is called.

Parameters:

className - The classname for the jdbc driver. An example would be sun.jdbc.odbc.JdbcOdbcDriver

url - The url of the of the database. An example would be jdbc:odbc:sampledb

username - The username to log in to the database. This can be an empty string.

password - Thepassword to log in to the database. This can be an empty string.

Throws:

DataSourceException - thrown if anything goes wrong.

JdbcDataSource

public JdbcDataSource(java.lang.String className,
                      java.lang.String url)
               throws DataSourceException

Create a DataSourceProvider that uses jdbc to access a SQL database. This constructor calls Class.forName().getInstance() followed by DriverManager.getConnection(). It is recomended that you do not use this constructor as it cannot use connection pooling (unless your J2EE application server implements connecion pooling for the DriverManager call).
This object will close the connection created when close is called.

Parameters:

className - The classname for the jdbc driver. An example would be sun.jdbc.odbc.JdbcOdbcDriver

url - The url of the of the database. An example would be jdbc:odbc:sampledb

Throws:

DataSourceException - thrown if anything goes wrong.

JdbcDataSource

public JdbcDataSource(java.sql.Connection conn)

Create a DataSourceProvider that uses jdbc to access a SQL database. It is strongly recomended that the created Connection be ResultSet.TYPE_SCROLL_INSENSITIVE, ResultSet.CONCUR_READ_ONLY. The TYPE_SCROLL_INSENSITIVE or TYPE_SCROLL_SENSITIVE setting is necessary in some jdbc drivers for ResultSet.isLast() to function. This object will not close the connection created when close is called.

Parameters:

conn - A connection to the sql database to use as the datasource.

Method Detail

getTagAttributes

public TagAttributes[] getTagAttributes()

Returns the allowed attributes for all tags.

Specified by:

getTagAttributes in interface DataSourceProvider

Returns:

The tag attributes.

validateTag

public void validateTag(BaseTag xmlTag)
                 throws TagException

Verifys that a tag has all required attributes and no unknown attributes.

Specified by:

validateTag in interface DataSourceProvider

Parameters:

xmlTag - The tag to check

Throws:

TagException - thrown if illegal parameters passed in.

setMap

public void setMap(java.util.Map map)

Adds a map that is used for ${variable} substitution. The map should be string pairs and the key values cannot have any of the characters ${} in them. When ${key} is found in any tag, it is replaced with the matching value. The key and value strings are not evaluated in any way, it is just a text replace. This replace occurs before any other evaluation of a tag so the value string can have ${variable} values that will then be evaluated.
This call sets the map so calling it a second time replaces the map passed in the first time. The map is copied so on return changes to the passed in map will not affect the data source.

Specified by:

setMap in interface DataSourceProvider

Parameters:

map - The map of string pairs.

addView

public java.lang.String addView(java.lang.String key,
                                java.lang.String select)
                         throws java.sql.SQLException

This creates a view using the passed in select statement. It will then substitute in this view by it's name where ${key} is used in the template. This is the equivilent of creating the view yourself and then calling setMap passing it this key and the view name.
If you put an identical key in for both addView and setMap then there is no gaurantee as to which will be used. The view will automatically be deleted when close() is called.

Parameters:

key - The ${name} used to reference this view.

select - The select part of the sql statement to create the view. Example: "select * from INVENTORY where PRICE > 10"

Returns:

The view name. You must not delete the view but you can use it until close() is called.

getRootNode

public DataSourceNode getRootNode()

Returns the root node for this data set. Outside of forEach loops this is the node all tag requests will be evaluated against.

Specified by:

getRootNode in interface DataSourceProvider

Returns:

The root node.

close

public void close()
           throws DataSourceException

Called when processing is complete. Used to close any resources opened by this object. Will close the jdbc connection if this object created the connection.

Specified by:

close in interface DataSourceProvider

Following copied from interface: net.windward.datasource.DataSourceProvider

Throws:

DataSourceException - Could not retrieve the data. Generally wraps a SqlException or XpathException.

log

public void log()

Log all info about this datasource to debug.

Specified by:

log in interface DataSourceProvider

dump

public java.lang.String dump()
                      throws DataSourceException

Display the entire dataset. This is used for debug level logging only.

Specified by:

dump in interface DataSourceProvider

Returns:

The entire dataset in a human readable format.

Throws:

DataSourceException - thrown if has any problems reading the dataset.