org.apache.derby.jdbc
Class EmbedXAConnection

java.lang.Object
  extended byorg.apache.derby.jdbc.EmbedPooledConnection
      extended byorg.apache.derby.jdbc.EmbedXAConnection
All Implemented Interfaces:
BrokeredConnectionControl, javax.sql.PooledConnection, javax.sql.XAConnection, javax.transaction.xa.XAResource

final class EmbedXAConnection
extends EmbedPooledConnection
implements javax.sql.XAConnection, javax.transaction.xa.XAResource


Field Summary
protected  BrokeredConnection currentConnectionHandle
           
(package private)  XAXactId currentXid
           
protected  ReferenceableDataSource dataSource
           
protected  int defaultIsolationLevel
           
(package private)  ResourceAdapter ra
           
protected  EmbedConnection realConnection
           
 
Fields inherited from interface javax.transaction.xa.XAResource
TMENDRSCAN, TMFAIL, TMJOIN, TMNOFLAGS, TMONEPHASE, TMRESUME, TMSTARTRSCAN, TMSUCCESS, TMSUSPEND, XA_OK, XA_RDONLY
 
Constructor Summary
(package private) EmbedXAConnection(EmbeddedDataSource ds, ResourceAdapter ra, java.lang.String u, java.lang.String p, boolean requestPassword)
           
 
Method Summary
 void addConnectionEventListener(javax.sql.ConnectionEventListener listener)
          Add an event listener.
protected  void checkActive()
           
 void checkAutoCommit(boolean autoCommit)
          Allow control over setting auto commit mode.
 void checkCommit()
          Allow control over calling commit.
 void checkHoldCursors(int holdability)
          Are held cursors allowed.
 void checkRollback()
          Allow control over calling rollback.
 void checkSavepoint()
          Allow control over creating a Savepoint (JDBC 3.0)
private  void checkUserCredentials(EmbedXAConnection original)
           
private  void checkXAActive()
           
 void close()
          Close the Pooled connection.
protected  void closeCurrentConnectionHandle()
          In this case the Listeners are *not* notified.
private static void closeUnusedConnection(EmbedConnection conn)
          Close an underlying connection object when there is no active XAResource to hand it to.
 boolean closingConnection()
          Close called on BrokeredConnection.
 void commit(javax.transaction.xa.Xid xid, boolean onePhase)
          Commit the global transaction specified by xid.
 void end(javax.transaction.xa.Xid xid, int flags)
          Ends the work performed on behalf of a transaction branch.
 void forget(javax.transaction.xa.Xid xid)
          Tell the resource manager to forget about a heuristically completed transaction branch.
 java.sql.Connection getConnection()
          Create an object handle for a database connection.
protected  java.sql.Connection getNewCurrentConnectionHandle()
           
(package private)  java.lang.String getPassword()
           
 int getPrepareIsolation()
          Get prepare isolation level.
 java.sql.Connection getRealConnection()
          Override getRealConnection to create a a local connection when we are not associated with an XA transaction.
private  XATransactionState getTransactionState(XAXactId xid_im)
           
 int getTransactionTimeout()
          Obtain the current transaction timeout value set for this XAResource instance.
(package private)  java.lang.String getUsername()
           
 javax.transaction.xa.XAResource getXAResource()
           
 boolean isSameRM(javax.transaction.xa.XAResource xares)
          This method is called to determine if the resource manager instance represented by the target object is the same as the resouce manager instance represented by the parameter xares.
 void notifyClose()
           
 void notifyError(java.sql.SQLException exception)
           
 void notifyException(java.sql.SQLException sqle)
          Notify the control class that a SQLException was thrown during a call on one of the brokered connection's methods.
protected  void openRealConnection()
           
 int prepare(javax.transaction.xa.Xid xid)
          Ask the resource manager to prepare for a transaction commit of the transaction specified in xid.
 javax.transaction.xa.Xid[] recover(int flag)
          Obtain a list of prepared transaction branches from a resource manager.
 void removeConnectionEventListener(javax.sql.ConnectionEventListener listener)
          Remove an event listener.
(package private)  void removeXATransaction(XAXactId xid_im)
           
protected  void resetRealConnection()
           
private  void returnConnectionToResource(XATransactionState tranState, XAXactId xid_im)
          Return an underlying connection object back to its XAResource if possible.
 void rollback(javax.transaction.xa.Xid xid)
          Inform the resource manager to roll back work done on behalf of a transaction branch
 void setDrdaID(java.lang.String drdaID)
          set DrdaId for this connection.
 void setPrepareIsolation(int level)
          Set the internal isolation level to use for preparing statements.
 boolean setTransactionTimeout(int seconds)
          Set the current transaction timeout value for this XAResource instance.
 void start(javax.transaction.xa.Xid xid, int flags)
          Start work on behalf of a transaction branch specified in xid If TMJOIN is specified, the start is for joining a transaction previously seen by the resource manager.
 java.lang.String toString()
          Get the string representation of this pooled connection.
private static javax.transaction.xa.XAException wrapInXAException(java.sql.SQLException se)
          Map a SQL exception to appropriate XAException.
private static javax.transaction.xa.XAException wrapInXAException(StandardException se)
          Map a Standard exception to appropriate XAException.
 java.sql.CallableStatement wrapStatement(java.sql.CallableStatement cs, java.lang.String sql)
          Wrap and control a PreparedStatement
 java.sql.PreparedStatement wrapStatement(java.sql.PreparedStatement ps, java.lang.String sql, java.lang.Object generatedKeys)
          Wrap and control a PreparedStatement
 java.sql.Statement wrapStatement(java.sql.Statement s)
          Wrap and control a Statement
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait
 
Methods inherited from interface javax.sql.PooledConnection
addConnectionEventListener, close, removeConnectionEventListener
 

Field Detail

ra

final ResourceAdapter ra

currentXid

XAXactId currentXid

realConnection

protected EmbedConnection realConnection

defaultIsolationLevel

protected int defaultIsolationLevel

currentConnectionHandle

protected BrokeredConnection currentConnectionHandle

dataSource

protected final ReferenceableDataSource dataSource
Constructor Detail

EmbedXAConnection

EmbedXAConnection(EmbeddedDataSource ds,
                  ResourceAdapter ra,
                  java.lang.String u,
                  java.lang.String p,
                  boolean requestPassword)
            throws java.sql.SQLException
Method Detail

getXAResource

public final javax.transaction.xa.XAResource getXAResource()
                                                    throws java.sql.SQLException
Specified by:
getXAResource in interface javax.sql.XAConnection
Throws:
java.sql.SQLException

start

public final void start(javax.transaction.xa.Xid xid,
                        int flags)
                 throws javax.transaction.xa.XAException
Start work on behalf of a transaction branch specified in xid If TMJOIN is specified, the start is for joining a transaction previously seen by the resource manager. If TMRESUME is specified, the start is to resume a suspended transaction specified in the parameter xid. If neither TMJOIN nor TMRESUME is specified and the transaction specified by xid has previously been seen by the resource manager, the resource manager throws the XAException exception with XAER_DUPID error code.

Specified by:
start in interface javax.transaction.xa.XAResource
Parameters:
xid - A global transaction identifier to be associated with the resource
flags - One of TMNOFLAGS, TMJOIN, or TMRESUME
Throws:
javax.transaction.xa.XAException - An error has occurred. Possible exceptions are XA_RB*, XAER_RMERR, XAER_RMFAIL, XAER_DUPID, XAER_OUTSIDE, XAER_NOTA, XAER_INVAL, or XAER_PROTO.

end

public final void end(javax.transaction.xa.Xid xid,
                      int flags)
               throws javax.transaction.xa.XAException
Ends the work performed on behalf of a transaction branch. The resource manager disassociates the XA resource from the transaction branch specified and let the transaction be completed.

If TMSUSPEND is specified in flags, the transaction branch is temporarily suspended in incomplete state. The transaction context is in suspened state and must be resumed via start with TMRESUME specified.

If TMFAIL is specified, the portion of work has failed. The resource manager may mark the transaction as rollback-only

If TMSUCCESS is specified, the portion of work has completed successfully.

Specified by:
end in interface javax.transaction.xa.XAResource
Parameters:
xid - A global transaction identifier that is the same as what was used previously in the start method.
flags - One of TMSUCCESS, TMFAIL, or TMSUSPEND
Throws:
javax.transaction.xa.XAException - An error has occurred. Possible XAException values are XAER_RMERR, XAER_RMFAILED, XAER_NOTA, XAER_INVAL, XAER_PROTO, or XA_RB*.

prepare

public final int prepare(javax.transaction.xa.Xid xid)
                  throws javax.transaction.xa.XAException
Ask the resource manager to prepare for a transaction commit of the transaction specified in xid.

Specified by:
prepare in interface javax.transaction.xa.XAResource
Parameters:
xid - A global transaction identifier
Returns:
A value indicating the resource manager's vote on the outcome of the transaction. The possible values are: XA_RDONLY or XA_OK. If the resource manager wants to roll back the transaction, it should do so by raising an appropriate XAException in the prepare method.
Throws:
javax.transaction.xa.XAException - An error has occurred. Possible exception values are: XA_RB*, XAER_RMERR, XAER_RMFAIL, XAER_NOTA, XAER_INVAL, or XAER_PROTO.

commit

public final void commit(javax.transaction.xa.Xid xid,
                         boolean onePhase)
                  throws javax.transaction.xa.XAException
Commit the global transaction specified by xid.

Specified by:
commit in interface javax.transaction.xa.XAResource
Parameters:
xid - A global transaction identifier
onePhase - If true, the resource manager should use a one-phase commit protocol to commit the work done on behalf of xid.
Throws:
javax.transaction.xa.XAException - An error has occurred. Possible XAExceptions are XA_HEURHAZ, XA_HEURCOM, XA_HEURRB, XA_HEURMIX, XAER_RMERR, XAER_RMFAIL, XAER_NOTA, XAER_INVAL, or XAER_PROTO.

If the resource manager did not commit the transaction and the paramether onePhase is set to true, the resource manager may throw one of the XA_RB* exceptions. Upon return, the resource manager has rolled back the branch's work and has released all held resources.


rollback

public final void rollback(javax.transaction.xa.Xid xid)
                    throws javax.transaction.xa.XAException
Inform the resource manager to roll back work done on behalf of a transaction branch

Specified by:
rollback in interface javax.transaction.xa.XAResource
Parameters:
xid - A global transaction identifier
Throws:
javax.transaction.xa.XAException - - An error has occurred

recover

public final javax.transaction.xa.Xid[] recover(int flag)
                                         throws javax.transaction.xa.XAException
Obtain a list of prepared transaction branches from a resource manager. The transaction manager calls this method during recovery to obtain the list of transaction branches that are currently in prepared or heuristically completed states.

Specified by:
recover in interface javax.transaction.xa.XAResource
Parameters:
flag - One of TMSTARTRSCAN, TMENDRSCAN, TMNOFLAGS. TMNOFLAGS must be used when no other flags are set in flags.
Returns:
The resource manager returns zero or more XIDs for the transaction branches that are currently in a prepared or heuristically completed state. If an error occurs during the operation, the resource manager should throw the appropriate XAException.
Throws:
javax.transaction.xa.XAException - An error has occurred. Possible values are XAER_RMERR, XAER_RMFAIL, XAER_INVAL, and XAER_PROTO.

forget

public final void forget(javax.transaction.xa.Xid xid)
                  throws javax.transaction.xa.XAException
Tell the resource manager to forget about a heuristically completed transaction branch.

Specified by:
forget in interface javax.transaction.xa.XAResource
Parameters:
xid - A global transaction identifier
Throws:
javax.transaction.xa.XAException - An error has occurred. Possible exception values are XAER_RMERR, XAER_RMFAIL, XAER_NOTA, XAER_INVAL, or XAER_PROTO.

isSameRM

public final boolean isSameRM(javax.transaction.xa.XAResource xares)
                       throws javax.transaction.xa.XAException
This method is called to determine if the resource manager instance represented by the target object is the same as the resouce manager instance represented by the parameter xares.

Specified by:
isSameRM in interface javax.transaction.xa.XAResource
Parameters:
xares - An XAResource object whose resource manager instance is to be compared with the resource manager instance of the target object.
Returns:
true if it's the same RM instance; otherwise false.
Throws:
javax.transaction.xa.XAException - An error has occurred. Possible exception values are XAER_RMERR, XAER_RMFAIL.

getTransactionTimeout

public int getTransactionTimeout()
Obtain the current transaction timeout value set for this XAResource instance. If XAResource.setTransactionTimeout was not use prior to invoking this method, the return value is the default timeout set for the resource manager; otherwise, the value used in the previous setTransactionTimeout call is returned.

Specified by:
getTransactionTimeout in interface javax.transaction.xa.XAResource
Returns:
the transaction timeout value in seconds.

setTransactionTimeout

public boolean setTransactionTimeout(int seconds)
Set the current transaction timeout value for this XAResource instance. Once set, this timeout value is effective until setTransactionTimeout is invoked again with a different value. To reset the timeout value to the default value used by the resource manager, set the value to zero. If the timeout operation is performed successfully, the method returns true; otherwise false. If a resource manager does not support transaction timeout value to be set explicitly, this method returns false.

Specified by:
setTransactionTimeout in interface javax.transaction.xa.XAResource
Parameters:
seconds - the transaction timeout value in seconds.
Returns:
true if transaction timeout value is set successfully; otherwise false.
Throws:
javax.transaction.xa.XAException - - An error has occurred. Possible exception values are XAER_RMERR, XAER_RMFAIL, or XAER_INVAL.

checkAutoCommit

public void checkAutoCommit(boolean autoCommit)
                     throws java.sql.SQLException
Allow control over setting auto commit mode.

Specified by:
checkAutoCommit in interface BrokeredConnectionControl
Overrides:
checkAutoCommit in class EmbedPooledConnection
Throws:
java.sql.SQLException

checkHoldCursors

public void checkHoldCursors(int holdability)
                      throws java.sql.SQLException
Are held cursors allowed.

Specified by:
checkHoldCursors in interface BrokeredConnectionControl
Overrides:
checkHoldCursors in class EmbedPooledConnection
Throws:
java.sql.SQLException

checkSavepoint

public void checkSavepoint()
                    throws java.sql.SQLException
Allow control over creating a Savepoint (JDBC 3.0)

Specified by:
checkSavepoint in interface BrokeredConnectionControl
Overrides:
checkSavepoint in class EmbedPooledConnection
Throws:
java.sql.SQLException

checkRollback

public void checkRollback()
                   throws java.sql.SQLException
Allow control over calling rollback.

Specified by:
checkRollback in interface BrokeredConnectionControl
Overrides:
checkRollback in class EmbedPooledConnection
Throws:
java.sql.SQLException

checkCommit

public void checkCommit()
                 throws java.sql.SQLException
Allow control over calling commit.

Specified by:
checkCommit in interface BrokeredConnectionControl
Overrides:
checkCommit in class EmbedPooledConnection
Throws:
java.sql.SQLException

getConnection

public java.sql.Connection getConnection()
                                  throws java.sql.SQLException
Description copied from class: EmbedPooledConnection
Create an object handle for a database connection.

Specified by:
getConnection in interface javax.sql.PooledConnection
Overrides:
getConnection in class EmbedPooledConnection
Returns:
a Connection object
Throws:
java.sql.SQLException - - if a database-access error occurs.

wrapStatement

public java.sql.Statement wrapStatement(java.sql.Statement s)
                                 throws java.sql.SQLException
Wrap and control a Statement

Specified by:
wrapStatement in interface BrokeredConnectionControl
Overrides:
wrapStatement in class EmbedPooledConnection
Throws:
java.sql.SQLException

wrapStatement

public java.sql.PreparedStatement wrapStatement(java.sql.PreparedStatement ps,
                                                java.lang.String sql,
                                                java.lang.Object generatedKeys)
                                         throws java.sql.SQLException
Wrap and control a PreparedStatement

Specified by:
wrapStatement in interface BrokeredConnectionControl
Overrides:
wrapStatement in class EmbedPooledConnection
Throws:
java.sql.SQLException

wrapStatement

public java.sql.CallableStatement wrapStatement(java.sql.CallableStatement cs,
                                                java.lang.String sql)
                                         throws java.sql.SQLException
Wrap and control a PreparedStatement

Specified by:
wrapStatement in interface BrokeredConnectionControl
Overrides:
wrapStatement in class EmbedPooledConnection
Throws:
java.sql.SQLException

getRealConnection

public java.sql.Connection getRealConnection()
                                      throws java.sql.SQLException
Override getRealConnection to create a a local connection when we are not associated with an XA transaction. This can occur if the application has a Connection object (conn) and the following sequence occurs. conn = xac.getConnection(); xac.start(xid, ...) // do work with conn xac.end(xid, ...); // do local work with conn // need to create new connection here.

Specified by:
getRealConnection in interface BrokeredConnectionControl
Overrides:
getRealConnection in class EmbedPooledConnection
Throws:
java.sql.SQLException

getTransactionState

private XATransactionState getTransactionState(XAXactId xid_im)

wrapInXAException

private static javax.transaction.xa.XAException wrapInXAException(java.sql.SQLException se)
Map a SQL exception to appropriate XAException. Return the mapped XAException.


wrapInXAException

private static javax.transaction.xa.XAException wrapInXAException(StandardException se)
Map a Standard exception to appropriate XAException. Return the mapped XAException.


removeXATransaction

void removeXATransaction(XAXactId xid_im)

returnConnectionToResource

private void returnConnectionToResource(XATransactionState tranState,
                                        XAXactId xid_im)
Return an underlying connection object back to its XAResource if possible. If not close the connection.


checkXAActive

private void checkXAActive()
                    throws javax.transaction.xa.XAException
Throws:
javax.transaction.xa.XAException

checkUserCredentials

private void checkUserCredentials(EmbedXAConnection original)
                           throws javax.transaction.xa.XAException
Throws:
javax.transaction.xa.XAException

closeUnusedConnection

private static void closeUnusedConnection(EmbedConnection conn)
Close an underlying connection object when there is no active XAResource to hand it to.


getUsername

java.lang.String getUsername()

getPassword

java.lang.String getPassword()

openRealConnection

protected final void openRealConnection()
                                 throws java.sql.SQLException
Throws:
java.sql.SQLException

getNewCurrentConnectionHandle

protected final java.sql.Connection getNewCurrentConnectionHandle()

closeCurrentConnectionHandle

protected void closeCurrentConnectionHandle()
                                     throws java.sql.SQLException
In this case the Listeners are *not* notified. JDBC 3.0 spec section 11.4

Throws:
java.sql.SQLException

resetRealConnection

protected void resetRealConnection()
                            throws java.sql.SQLException
Throws:
java.sql.SQLException

close

public void close()
           throws java.sql.SQLException
Close the Pooled connection.

Specified by:
close in interface javax.sql.PooledConnection
Throws:
java.sql.SQLException - - if a database-access error occurs.

addConnectionEventListener

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

Specified by:
addConnectionEventListener in interface javax.sql.PooledConnection

removeConnectionEventListener

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

Specified by:
removeConnectionEventListener in interface javax.sql.PooledConnection

notifyError

public void notifyError(java.sql.SQLException exception)

notifyClose

public void notifyClose()

checkActive

protected final void checkActive()
                          throws java.sql.SQLException
Throws:
java.sql.SQLException

notifyException

public void notifyException(java.sql.SQLException sqle)
Notify the control class that a SQLException was thrown during a call on one of the brokered connection's methods.

Specified by:
notifyException in interface BrokeredConnectionControl

closingConnection

public boolean closingConnection()
                          throws java.sql.SQLException
Close called on BrokeredConnection. If this call returns true then getRealConnection().close() will be called. Don't close the underlying real connection as it is pooled.

Specified by:
closingConnection in interface BrokeredConnectionControl
Throws:
java.sql.SQLException

setDrdaID

public void setDrdaID(java.lang.String drdaID)
set DrdaId for this connection. Used by network server to identify connection.

Specified by:
setDrdaID in interface BrokeredConnectionControl
Parameters:
drdaID - drda connection identifier

setPrepareIsolation

public void setPrepareIsolation(int level)
                         throws java.sql.SQLException
Set the internal isolation level to use for preparing statements. Subsequent prepares will use this isoalation level

Specified by:
setPrepareIsolation in interface BrokeredConnectionControl
Parameters:
level - internal isolation level
Throws:
java.sql.SQLException
See Also:
BrokeredConnection.setPrepareIsolation(int)

getPrepareIsolation

public int getPrepareIsolation()
                        throws java.sql.SQLException
Get prepare isolation level. For network server this will be the isolation level at which statements will be prepared.

Specified by:
getPrepareIsolation in interface BrokeredConnectionControl
Returns:
isolation level
Throws:
java.sql.SQLException

toString

public java.lang.String toString()
Get the string representation of this pooled connection. A pooled connection is assigned a separate id from a physical connection. When a container calls PooledConnection.toString(), it gets the string representation of this id. This is useful for developers implementing connection pools when they are trying to debug pooled connections.

Returns:
a string representation of the uniquie id for this pooled connection.

Built on Tue 2006-10-10 19:23:47+0200, from revision exported

Apache Derby V10.1 Engine Documentation - Copyright © 1997,2005 The Apache Software Foundation or its licensors, as applicable.