org.apache.derby.jdbc
Class EmbedXAConnection

java.lang.Object
  org.apache.derby.jdbc.EmbedPooledConnection
      org.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.