org.slamb.axamol.library
Class LibraryConnection

java.lang.Object
  org.slamb.axamol.library.LibraryConnection

public class LibraryConnection
extends java.lang.Object

Library of SQL statements with associated connection. This is typically the only place SQL statements are executed in an Axamol SQL Library-based program.

Todo

Add data structures, logic for tracking how much cached prepared statements are used and ejecting infrequently-used ones from the cache when it gets large. As is, calling a bindlist-based query repeatedly with many different arguments could cause the cache to grow tremendously.

Version:

$Id: LibraryConnection.java 1234 2005-07-03 02:46:16Z slamb $

Author:

Scott Lamb <slamb@slamb.org>

Constructor Summary

LibraryConnection(Library library, java.sql.Connection conn)
Prepares to use an existing connection for use of the library.

LibraryConnection(Library library, javax.sql.DataSource src)
Prepares to use a datasource with the library.

LibraryConnection(Library library, java.lang.String driverClassName, java.lang.String jdbcURL)
Creates a new connection exclusively for use by this LibraryConnection.

LibraryConnection(Library library, java.lang.String driverClassName, java.lang.String jdbcURL, java.util.Properties info)
Creates a new connection exclusively for use by this LibraryConnection.

LibraryConnection(Library library, java.lang.String driverClassName, java.lang.String jdbcURL, java.lang.String user, java.lang.String pass)
Creates a new connection exclusively for use by this LibraryConnection.

Method Summary

void	close() Closes all active prepared statements and possibly the connection itself.
void	commit() Passes the commit through to the Connection.
java.sql.ResultSet	executeQuery(java.lang.String statementName, java.util.Map params) Executes a query statement.
java.sql.ResultSet	executeQuery(java.lang.String statementName, java.util.Map params, java.lang.String orderByClause) Executes a query statement with an optional "order by" clause.
int	executeUpdate(java.lang.String statementName, java.util.Map params) Executes an update statement.
java.sql.ResultSet	explain(java.lang.String statementName, java.util.Map params) Executes a PostgreSQL "explain analyze" on a query.
java.sql.ResultSet	explain(java.lang.String statementName, java.util.Map params, java.lang.String orderByClause) Executes a PostgreSQL "explain analyze" on a query.
protected void	finalize()
java.util.Map	getColumns(java.lang.String query)
void	rollback() Passes the rollback through to the Connection.
void	setAutoCommit(boolean autoCommit) Passes the request through to the Connection.

Methods inherited from class java.lang.Object

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

Constructor Detail

LibraryConnection

public LibraryConnection(Library library,
                         java.sql.Connection conn)

Prepares to use an existing connection for use of the library. Does not assume ownership of the connection, soLibraryConnection.close will not close the connection. This is the best way to use a LibraryConnection in an existing program with non-library-based queries.

See Also:

Library.Library(Class, String)

LibraryConnection

public LibraryConnection(Library library,
                         javax.sql.DataSource src)
                  throws java.sql.SQLException

Prepares to use a datasource with the library. Assumes ownership of the connection, so LibraryConnection.close will close the connection. This is the most convenient way to use a LibraryConnection in new web applications.

Throws:

java.sql.SQLException

LibraryConnection

public LibraryConnection(Library library,
                         java.lang.String driverClassName,
                         java.lang.String jdbcURL)
                  throws java.sql.SQLException

Creates a new connection exclusively for use by this LibraryConnection.

Parameters:

library -

driverClassName - If non-null, this class will be initialized before asking the DriverManager for a connection. This gives it a chance to register itself with the DriverManager.

jdbcURL - The JDBC connection URL.

Throws:

java.sql.SQLException

See Also:

DriverManager.getConnection(java.lang.String)

LibraryConnection

public LibraryConnection(Library library,
                         java.lang.String driverClassName,
                         java.lang.String jdbcURL,
                         java.lang.String user,
                         java.lang.String pass)
                  throws java.sql.SQLException

Creates a new connection exclusively for use by this LibraryConnection.

Parameters:

library -

driverClassName - If non-null, this class will be initialized before asking the DriverManager for a connection. This gives it a chance to register itself with the DriverManager.

jdbcURL - The JDBC connection URL.

user -

pass -

Throws:

java.sql.SQLException

See Also:

DriverManager.getConnection(java.lang.String, java.lang.String, java.lang.String)

LibraryConnection

public LibraryConnection(Library library,
                         java.lang.String driverClassName,
                         java.lang.String jdbcURL,
                         java.util.Properties info)
                  throws java.sql.SQLException

Creates a new connection exclusively for use by this LibraryConnection.

Parameters:

library -

driverClassName - If non-null, this class will be initialized before asking the DriverManager for a connection. This gives it a chance to register itself with the DriverManager.

jdbcURL - The JDBC connection URL.

info -

Throws:

java.sql.SQLException

See Also:

DriverManager.getConnection(java.lang.String, java.util.Properties)

Method Detail

close

public void close()

Closes all active prepared statements and possibly the connection itself. The connection will be caused if - and only if - it was created by a LibraryConnection constructor. Exceptions are logged but not rethrown.

finalize

protected void finalize()
                 throws java.lang.Throwable

Overrides:

finalize in class java.lang.Object

Throws:

java.lang.Throwable

executeQuery

public java.sql.ResultSet executeQuery(java.lang.String statementName,
                                       java.util.Map params)
                                throws java.sql.SQLException

Executes a query statement. The PreparedStatement will be disposed of automatically. The ResultSet must be disposed of by the caller.

Parameters:

statementName - The statement to use, which must be a query.

params - The parameters. May be null, which is treated as equivalent to empty.

Throws:

java.sql.SQLException

explain

public java.sql.ResultSet explain(java.lang.String statementName,
                                  java.util.Map params)
                           throws java.sql.SQLException

Executes a PostgreSQL "explain analyze" on a query.

Returns:

A ResultSet representing the query plan.

Warning

I haven't implemented a real cross-database mechanism for this. This method could go away at any time.

Throws:

java.sql.SQLException

explain

public java.sql.ResultSet explain(java.lang.String statementName,
                                  java.util.Map params,
                                  java.lang.String orderByClause)
                           throws java.sql.SQLException

Executes a PostgreSQL "explain analyze" on a query.

Returns:

A ResultSet representing the query plan.

Warning

I haven't implemented a real cross-database mechanism for this. This method could go away at any time.

Throws:

java.sql.SQLException

executeQuery

public java.sql.ResultSet executeQuery(java.lang.String statementName,
                                       java.util.Map params,
                                       java.lang.String orderByClause)
                                throws java.sql.SQLException

Executes a query statement with an optional "order by" clause. The PreparedStatement will be disposed of automatically. The ResultSet must be disposed of by the caller.

Parameters:

statementName - The statement to use, which must be a query.

params - The parameters. May be null, which is treated as equivalent to empty.

orderByClause - The "order by" clause, which will be appended if non-null. The actual text order by should not be included, just the clause itself.

Throws:

java.sql.SQLException

executeUpdate

public int executeUpdate(java.lang.String statementName,
                         java.util.Map params)
                  throws java.sql.SQLException

Executes an update statement.

More precisely, this is a DML or DDL statement. But executeDMLorDDL just doesn't have the same ring to it.

The PreparedStatement will be disposed of automatically.

Parameters:

statementName - The statement to use, which must be a DML or DDL statement.

params - The parameters. May be null, which is treated as equivalent to empty.

Throws:

java.sql.SQLException

commit

public void commit()
            throws java.sql.SQLException

Passes the commit through to the Connection. These convenience methods allow you to avoid passing a Connection everywhere you use a LibraryConnection.

Throws:

java.sql.SQLException

See Also:

Connection.commit()

rollback

public void rollback()
              throws java.sql.SQLException

Passes the rollback through to the Connection. These convenience methods allow you to avoid passing a Connection everywhere you use a LibraryConnection.

Throws:

java.sql.SQLException

See Also:

Connection.rollback()

setAutoCommit

public void setAutoCommit(boolean autoCommit)
                   throws java.sql.SQLException

Passes the request through to the Connection. These convenience methods allow you to avoid passing a Connection everywhere you use a LibraryConnection.

Throws:

java.sql.SQLException

See Also:

Connection.setAutoCommit(boolean)

getColumns

public java.util.Map getColumns(java.lang.String query)