org.apache.turbine.util.db.pool
Class DBConnection

java.lang.Object
  |
  +--org.apache.turbine.util.db.pool.DBConnection
All Implemented Interfaces:
javax.sql.ConnectionEventListener, java.util.EventListener

public class DBConnection
extends java.lang.Object
implements javax.sql.ConnectionEventListener

This class wraps the JDBC Connection class, providing built-in exception logging to stderr and a timestamp which indicates how old the Connection is. DBConnection's timestamp is used by the ConnectionPool to expire connections when they get too old. Do not use this class as a shared resource (it is not thread-safe).

Version:
$Id$
Author:
Frank Y. Kim, John D. McNally, Daniel L. Rall, Magnús Þór Torfason, Jon S. Stevens

Field Summary
private  java.sql.Connection connection
          The JDBC database connection.
private  java.util.Vector eventListeners
          ConnectionEventListeners
private  ConnectionPool pool
          The ConnectionPool that this DBConnection came from.
private  javax.sql.PooledConnection pooledConnection
          The JDBC PooledConnection (if supported by the JDBC driver).
private  long timestamp
          The time in milliseconds at which the connection was created.
private  java.lang.String url
          The URL of this connection.
private  java.lang.String username
          The user name for this connection.
 
Constructor Summary
protected DBConnection(java.sql.Connection connection)
          Creates a Turbine DBConnection specifying nothing but a single database Connection.
protected DBConnection(java.sql.Connection connection, java.lang.String url)
          Creates a Turbine DBConnection with the specified attributes.
protected DBConnection(java.sql.Connection connection, java.lang.String url, java.lang.String username)
          Creates a Turbine DBConnection with the specified attributes.
protected DBConnection(java.sql.Connection connection, java.lang.String url, java.lang.String username, ConnectionPool pool)
          Creates a Turbine DBConnection that is part of a pool.
protected DBConnection(javax.sql.PooledConnection pooledConnection, java.lang.String url, java.lang.String username, ConnectionPool pool)
          Creates a Turbine DBConnection that is part of a pool.
 
Method Summary
 void addConnectionEventListener(javax.sql.ConnectionEventListener listener)
          Add an event listener.
 void close()
          Force the close of this database connection.
 void commit()
          Commit the connection.
 void connectionClosed(javax.sql.ConnectionEvent event)
          This will be called if the Connection returned by the getConnection method came from a PooledConnection, and the user calls the close() method of this connection object.
 void connectionErrorOccurred(javax.sql.ConnectionEvent e)
          If a fatal error occurs, close the undelying physical connection so as not to be returned in the future
 java.sql.Statement createStatement()
          Create a Java SQL statement for this connection.
protected  void finalize()
          The finalizer helps prevent ConnectionPool leakage.
 java.sql.Connection getConnection()
          Returns a JDBC connection.
 ConnectionPool getPool()
          Returns the pool this DBConnection came from, or null if it is not linked to any pool
 long getTimestamp()
          Returns a long representing the time this connection was created.
 java.lang.String getUrl()
          Returns the connection URL.
 java.lang.String getUsername()
          Returns the connection user name.
protected  void link(ConnectionPool pool)
          Links this DBConnection with a ConnectionPool.
 java.sql.PreparedStatement prepareStatement(java.lang.String sql)
          Create a prepared Java SQL statement for this connection.
 void removeConnectionEventListener(javax.sql.ConnectionEventListener listener)
          Remove an event listener.
 void rollback()
          Roll back the connection.
 void setAutoCommit(boolean b)
          Set the autocommit flag for the connection.
protected  void unlink(ConnectionPool pool)
          Unlink the DBConnection from it's pool.
 
Methods inherited from class java.lang.Object
, clone, equals, getClass, hashCode, notify, notifyAll, registerNatives, toString, wait, wait, wait
 

Field Detail

pool

private ConnectionPool pool
The ConnectionPool that this DBConnection came from. A null means that the DBConnection either does not belong to any pool, or that it is currently inside it's pool

connection

private java.sql.Connection connection
The JDBC database connection.

pooledConnection

private javax.sql.PooledConnection pooledConnection
The JDBC PooledConnection (if supported by the JDBC driver). If this is null, then this class uses the classic Connection object to manage connection. Else, the PooledConnection object is used.

url

private java.lang.String url
The URL of this connection.

username

private java.lang.String username
The user name for this connection.

timestamp

private long timestamp
The time in milliseconds at which the connection was created.

eventListeners

private java.util.Vector eventListeners
ConnectionEventListeners
Constructor Detail

DBConnection

protected DBConnection(java.sql.Connection connection)
Creates a Turbine DBConnection specifying nothing but a single database Connection.
Parameters:
connection - The JDBC connection to wrap.

DBConnection

protected DBConnection(java.sql.Connection connection,
                       java.lang.String url)
Creates a Turbine DBConnection with the specified attributes.
Parameters:
connection - The JDBC connection to wrap.
url - The URL we're connecting to.

DBConnection

protected DBConnection(java.sql.Connection connection,
                       java.lang.String url,
                       java.lang.String username)
Creates a Turbine DBConnection with the specified attributes.
Parameters:
connection - The JDBC connection to wrap.
url - The URL we're connecting to.
username - The user name we are connecting as

DBConnection

protected DBConnection(java.sql.Connection connection,
                       java.lang.String url,
                       java.lang.String username,
                       ConnectionPool pool)
Creates a Turbine DBConnection that is part of a pool.
Parameters:
connection - The JDBC connection to wrap.
url - The URL we're connecting to.
username - The user name we are connecting as
pool - The ConnectionPool that this DBConnection belongs to

DBConnection

protected DBConnection(javax.sql.PooledConnection pooledConnection,
                       java.lang.String url,
                       java.lang.String username,
                       ConnectionPool pool)
Creates a Turbine DBConnection that is part of a pool.
Parameters:
connection - The JDBC connection to wrap.
url - The URL we're connecting to.
username - The user name we are connecting as
pool - The ConnectionPool that this DBConnection belongs to
Method Detail

finalize

protected void finalize()
                 throws java.lang.Throwable
The finalizer helps prevent ConnectionPool leakage.
Overrides:
finalize in class java.lang.Object

link

protected void link(ConnectionPool pool)
Links this DBConnection with a ConnectionPool.
Parameters:
The - pool to link to.

unlink

protected void unlink(ConnectionPool pool)
               throws java.lang.Exception
Unlink the DBConnection from it's pool.
Parameters:
pool - The pool to unlink from.
Throws:
java.lang.Exception - Attempt to unlink from another pool.

getPool

public ConnectionPool getPool()
Returns the pool this DBConnection came from, or null if it is not linked to any pool
Returns:
The pool this connection came from.

addConnectionEventListener

public void addConnectionEventListener(javax.sql.ConnectionEventListener listener)
Add an event listener.

removeConnectionEventListener

public void removeConnectionEventListener(javax.sql.ConnectionEventListener listener)
Remove an event listener.

getConnection

public java.sql.Connection getConnection()
                                  throws java.sql.SQLException
Returns a JDBC connection.
Returns:
The database connection.

getTimestamp

public long getTimestamp()
Returns a long representing the time this connection was created.
Returns:
The time in milliseconds that this connection was created.

getUrl

public java.lang.String getUrl()
Returns the connection URL.
Returns:
A String with the connection URL.

getUsername

public java.lang.String getUsername()
Returns the connection user name.
Returns:
A String with the connection username.

commit

public void commit()
Commit the connection.

rollback

public void rollback()
Roll back the connection.

setAutoCommit

public void setAutoCommit(boolean b)
Set the autocommit flag for the connection.
Parameters:
b - True if autocommit should be set to true.

createStatement

public java.sql.Statement createStatement()
Create a Java SQL statement for this connection.
Returns:
A new Statement.

prepareStatement

public java.sql.PreparedStatement prepareStatement(java.lang.String sql)
Create a prepared Java SQL statement for this connection.
Parameters:
sql - The SQL statement to prepare.
Returns:
A new PreparedStatement.

close

public void close()
           throws java.sql.SQLException
Force the close of this database connection.
Throws:
java.sql.SQLException - The database connection couldn't be closed.

connectionClosed

public void connectionClosed(javax.sql.ConnectionEvent event)
This will be called if the Connection returned by the getConnection method came from a PooledConnection, and the user calls the close() method of this connection object. What we need to do here is to release this DBConnection from our pool...
Specified by:
connectionClosed in interface javax.sql.ConnectionEventListener

connectionErrorOccurred

public void connectionErrorOccurred(javax.sql.ConnectionEvent e)
If a fatal error occurs, close the undelying physical connection so as not to be returned in the future
Specified by:
connectionErrorOccurred in interface javax.sql.ConnectionEventListener


Copyright © 1999-2001 Apache Software Foundation. All Rights Reserved.