org.jboss.minerva.xa
Class XAConnectionImpl

java.lang.Object
  |
  +--org.jboss.minerva.xa.XAConnectionImpl
All Implemented Interfaces:
javax.sql.PooledConnection, PooledObject, javax.sql.XAConnection

public class XAConnectionImpl
extends java.lang.Object
implements javax.sql.XAConnection, PooledObject

A transaction wrapper around a java.sql.Connection. This provides access to an XAResource (there is a one-to-one mapping between XAResource and XAConnection) and a java.sql.Connection (in this implementation, there is also a one-to-one mapping between XAConnection and java.sql.Connection). In order to pool java.sql.Connections in a transactional environment, this is the class that should be pooled - though you could pool the connections, there is no need to create and destroy these wrappers so frequently.

Note that there con only be one transaction at a time accessing one of these wrappers, and requests to a pool for multiple connections on behalf of one transaction should use the same wrapper. This is because there is no distinction between connections and transactions in a java.sql.Connection, and work done by one connection on behalf of a transaction would not be visible to another connection working on behalf of the same transaction - you would have effectively created two transactions.

This also implies that an XAConnection should not be released to a connection pool until the work has been committed or rolled back. However, it must sent the close notification as usual in order to be delisted from the transaction. So the ConnectionEventListener must not release the XAConnection to a pool when it receives the close event. Instead, it should also register a TransactionListener that will be notified when the Transaction is finished, and release the XAConnection at that time.

Version:
$Revision: 1.9 $
Author:
Aaron Mulder (ammulder@alumni.princeton.edu)
See Also:
TransactionListener

Constructor Summary
XAConnectionImpl(java.sql.Connection con, XAResourceImpl resource)
          Creates a new transactional wrapper.
 
Method Summary
 void addConnectionEventListener(javax.sql.ConnectionEventListener listener)
           
 void addPoolEventListener(PoolEventListener listener)
          Adds a new listener.
 void clearTransactionListener()
          Clears the transaction listener.
 void clientConnectionClosed()
          Indicates that the connection given to the client has been closed.
 void close()
          Shuts down this wrapper (and the underlying Connection) permanently.
 java.sql.Connection getConnection()
           
 javax.transaction.xa.XAResource getXAResource()
           
 void removeConnectionEventListener(javax.sql.ConnectionEventListener listener)
           
 void removePoolEventListener(PoolEventListener listener)
          Removes a listener.
 void rollback()
          Rolls back the underlying connection.
 void setConnectionError(java.sql.SQLException e)
          Indicates that the connection given to the client has had an error.
 void setTransactionListener(TransactionListener tl)
          Sets the transaction listener.
 void transactionFailed()
          Indicates that the outstanding transaction has finished with a fatal error, and this object should be closed or permanently removed from a pool.
 void transactionFinished()
          Indicates that the outstanding transaction has finished and this object can be closed or returned to a pool.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Constructor Detail

XAConnectionImpl

public XAConnectionImpl(java.sql.Connection con,
                        XAResourceImpl resource)
Creates a new transactional wrapper.
Parameters:
con - The underlying non-transactional Connection.
resource - The transaction resource used to enlist this connection in a transaction.
Method Detail

setTransactionListener

public void setTransactionListener(TransactionListener tl)
Sets the transaction listener.

clearTransactionListener

public void clearTransactionListener()
Clears the transaction listener.

close

public void close()
Shuts down this wrapper (and the underlying Connection) permanently.
Specified by:
close in interface javax.sql.PooledConnection

clientConnectionClosed

public void clientConnectionClosed()
Indicates that the connection given to the client has been closed. If there is currently a transaction, this object should not be closed or returned to a pool. If not, it can be closed or returned immediately.

transactionFinished

public void transactionFinished()
Indicates that the outstanding transaction has finished and this object can be closed or returned to a pool. This dispatches a close event to all listeners.
See Also:
addConnectionEventListener(javax.sql.ConnectionEventListener)

transactionFailed

public void transactionFailed()
Indicates that the outstanding transaction has finished with a fatal error, and this object should be closed or permanently removed from a pool. This dispatches a close event to all listeners.
See Also:
addConnectionEventListener(javax.sql.ConnectionEventListener)

setConnectionError

public void setConnectionError(java.sql.SQLException e)
Indicates that the connection given to the client has had an error. If there is currently a transaction, this object should not be closed or returned to a pool. If not, it can be closed or returned immediately.

rollback

public void rollback()
              throws java.sql.SQLException
Rolls back the underlying connection. This is used when there is no current transaction and the connection is returned to the pool - since no transaction will be committed or rolled back but this connection will be reused, we must roll it back.

getXAResource

public javax.transaction.xa.XAResource getXAResource()
Specified by:
getXAResource in interface javax.sql.XAConnection

addConnectionEventListener

public void addConnectionEventListener(javax.sql.ConnectionEventListener listener)
Specified by:
addConnectionEventListener in interface javax.sql.PooledConnection

removeConnectionEventListener

public void removeConnectionEventListener(javax.sql.ConnectionEventListener listener)
Specified by:
removeConnectionEventListener in interface javax.sql.PooledConnection

getConnection

public java.sql.Connection getConnection()
Specified by:
getConnection in interface javax.sql.PooledConnection

addPoolEventListener

public void addPoolEventListener(PoolEventListener listener)
Description copied from interface: PooledObject
Adds a new listener.
Specified by:
addPoolEventListener in interface PooledObject

removePoolEventListener

public void removePoolEventListener(PoolEventListener listener)
Description copied from interface: PooledObject
Removes a listener.
Specified by:
removePoolEventListener in interface PooledObject


Copyright © 2000 The jBoss Organization. All Rights Reserved.