com.jcorporate.expresso.core.db
Class DBTransaction

java.lang.Object
  com.jcorporate.expresso.core.db.DBTransaction

public class DBTransaction

extends Object

Generic database transaction object - hides the implementation details of using jdbc and allows for JDBC message and exceptions to be handled better than by default. DBTransaction are also designed to be used in conjunction with connection pooling, and have special methods to support this.

Author:

Yves Henri AMAIZO

Field Summary

static String

DEFAULT_DB_CONTEXT_NAME Constant name for the 'Default' database context

Constructor Summary

DBTransaction()
Constructor Create a new connection object

DBTransaction(DBConnectionPool pool)
Constructor Create a new connection object

DBTransaction(String transactionDataContext)
Constructor Create a new connection object

Method Summary

void	clear() Clear all result sets and statements associated with this connection
void	commit() Send a COMMIT to the database, closing the current transaction If the database driver claims it doesn't support transactions, then we skip this.
String	getDataContext() Retrieve the data context name we're associated with
String	getDescription() Returns the text description of this connection.
int	getId() Get transaction id
DBConnectionPool	getPool()
DBConnection	getTransactionConnection() Low level function that allows you to retrieve the JDBC connection associated with this DBConnection.
String	getTransactionIdentifier() Get transaction identifier which is myDescription + transactionId
boolean	isClosed() When this connection has lost its connection to the server, tell whether or not it is available to be re-allocated
boolean	isConnected() When this connection has lost its connection to the server, tell whether or not it is available to be re-allocated
void	release() Releases the DBConnection back into the parent DBConnectionPool.
void	rollback() Roll back the current transaction, as if it were never requested.
void	setDataContext(String newDBName) Sets the data context for the connection.
void	setDescription(String newDescription) Set a description for this database connection.
void	setPool(DBConnectionPool pool)
void	setTransactionDirtyMode() Set EXPRESSO transaction mode for the current DBConnection.
void	setTransactionExclusiveMode() Set EXPRESSO transaction mode for the current DBConnection.
void	setTransactionReadOnlyMode() Set EXPRESSO transaction mode for the current DBConnection.
void	setTransactionRestrictiveMode() Set EXPRESSO transaction mode for the current DBConnection.
void	startTransaction() Sets up the transaction operation on an identitied DBConnectionPool
void	startTransaction(boolean immortal) Sets up the transaction operation on an identitied DBConnectionPool

Methods inherited from class java.lang.Object

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

Field Detail

DEFAULT_DB_CONTEXT_NAME

public static final String DEFAULT_DB_CONTEXT_NAME

Constant name for the 'Default' database context

See Also:

Constant Field Values

Constructor Detail

DBTransaction

public DBTransaction()
              throws DBException

Constructor Create a new connection object

Throws:

DBException - If the information provided cannot be used to create a new connection

DBTransaction

public DBTransaction(DBConnectionPool pool)
              throws DBException

Constructor Create a new connection object

Parameters:

pool - The identified transaction pool connection

Throws:

DBException - If the information provided cannot be used to create a new connection

DBTransaction

public DBTransaction(String transactionDataContext)
              throws DBException

Constructor Create a new connection object

Parameters:

transactionDataContext - The transaction data context connection

Throws:

DBException - If the information provided cannot be used to create a new connection

Method Detail

startTransaction

public void startTransaction()
                      throws DBException

Sets up the transaction operation on an identitied DBConnectionPool

Throws:

DBException

startTransaction

public void startTransaction(boolean immortal)
                      throws DBException

Sets up the transaction operation on an identitied DBConnectionPool

Throws:

DBException

clear

public void clear()
           throws DBException

Clear all result sets and statements associated with this connection

Throws:

DBException

commit

public void commit()
            throws DBException

Send a COMMIT to the database, closing the current transaction If the database driver claims it doesn't support transactions, then we skip this.

Throws:

DBException - If the commit does not succeed

getTransactionConnection

public DBConnection getTransactionConnection()

Low level function that allows you to retrieve the JDBC connection associated with this DBConnection. This allows you to do several fancy things that would not normally happen within Expresso itself such as prepared statements, and other low level entities.

NOTE: Once you grab the connection yourself, you are on your own as far as the framework is concerned. It doesn't help you to get your connection back in place. So, for example, if you close the connection manually, it will mess up the connection pool. Or if you fail to free a prepared statement, it will register as a resource leak. Be sure to restore your connection to pristine order before releasing this DBConnection back into the pool.

Returns:

a java.sql.Connection JDBC connection.

getDescription

public String getDescription()

Returns the text description of this connection. When the connection is put in use by a client program a description is set, this method retrieves the description.

Returns:

String A text description of this database connection's purpose

isClosed

public boolean isClosed()
                 throws DBException

When this connection has lost its connection to the server, tell whether or not it is available to be re-allocated

Returns:

boolean True if the connection has been lost, false if it is still usable

Throws:

DBException

isConnected

public boolean isConnected()

When this connection has lost its connection to the server, tell whether or not it is available to be re-allocated

Returns:

boolean True if the connection has been lost, false if it is still usable

rollback

public void rollback()
              throws DBException

Roll back the current transaction, as if it were never requested. If the JDBC driver claims it doesn't support transactions, then this method is a NOOP except for touching the connection

Throws:

DBException - If the rollback encounters an error

setDescription

public void setDescription(String newDescription)

Set a description for this database connection. When status is requested from the connection pool, this is used to describe the connection. Any client requesting a connection from the pool should set the description of the connection as soon as it's returned

Parameters:

newDescription - Description of this connection

setDataContext

public void setDataContext(String newDBName)

Sets the data context for the connection.

Parameters:

newDBName - the datacontext name to use

getDataContext

public String getDataContext()

Retrieve the data context name we're associated with

Returns:

java.lang.String of the current data Context

release

public void release()
             throws DBException

Releases the DBConnection back into the parent DBConnectionPool. Allows for syntax like:

DBConnection connection = DBConnectionPool.getInstance("default").getConnection();
[do stuff]
connection.release();


Throws:

DBException

getPool

public DBConnectionPool getPool()

Returns:

setPool

public void setPool(DBConnectionPool pool)

Parameters:

pool -

setTransactionReadOnlyMode

public void setTransactionReadOnlyMode()
                                throws DBException

Set EXPRESSO transaction mode for the current DBConnection.

author Yves Henri AMAIZO, Mon Dec 22 10:30:59 2003

Throws:

DBException

Since:

Expresso 5.3

setTransactionDirtyMode

public void setTransactionDirtyMode()
                             throws DBException

Set EXPRESSO transaction mode for the current DBConnection.

author Yves Henri AMAIZO, Mon Dec 22 10:30:59 2003

Throws:

DBException

Since:

Expresso 5.3

setTransactionRestrictiveMode

public void setTransactionRestrictiveMode()
                                   throws DBException

Set EXPRESSO transaction mode for the current DBConnection.

author Yves Henri AMAIZO, Mon Dec 22 10:30:59 2003

Throws:

DBException

Since:

Expresso 5.3

setTransactionExclusiveMode

public void setTransactionExclusiveMode()
                                 throws DBException

Set EXPRESSO transaction mode for the current DBConnection.

author Yves Henri AMAIZO, Mon Dec 22 10:30:59 2003

Throws:

DBException

Since:

Expresso 5.3

getId

public int getId()

Get transaction id

Returns:

int

author Yves Henri AMAIZO, Mon Dec 22 10:30:59 2003

Since:

Expresso 5.3

getTransactionIdentifier

public String getTransactionIdentifier()

Get transaction identifier which is myDescription + transactionId

Returns:

String

author Yves Henri AMAIZO, Mon Dec 22 10:30:59 2003

Since:

Expresso 5.3