Top Description Inners Fields Constructors Methods
org.postgresql.xa

public Class PGXAConnection

extends PGPooledConnection
implements XAConnection, XAResource
Class Inheritance
All Implemented Interfaces
javax.transaction.xa.XAResource, javax.sql.XAConnection, javax.sql.PooledConnection
Static Imports
org.postgresql.util.internal.Nullness.castNonNull

The PostgreSQL implementation of XAResource.

This implementation doesn't support transaction interleaving (see JTA specification, section 3.4.4) and suspend/resume.

Two-phase commit requires PostgreSQL server version 8.1 or higher.

Author
Heikki Linnakangas ([email protected])

Nested and Inner Type Summary

Modifier and TypeClass and Description
private class
PGXAConnection.ConnectionHandler

private static enum
PGXAConnection.State

Field Summary

Modifier and TypeField and Description
private boolean
committedOrRolledBack

private final BaseConnection
conn

Underlying physical database connection.

private @Nullable Xid
currentXid

private boolean
localAutoCommitMode

private static final Logger
LOGGER

private @Nullable Xid
preparedXid

private PGXAConnection.State
state

Constructor Summary

AccessConstructor and Description
public
PGXAConnection(BaseConnection conn)

Method Summary

Modifier and TypeMethod and Description
public void
commit(Xid
A global transaction identifier
xid, boolean
If true, the resource manager should use a one-phase commit protocol to commit the work done on behalf of xid.
onePhase)

Implements javax.transaction.xa.XAResource.commit.

Commits the global transaction specified by xid.

private void
commitOnePhase(Xid xid)

Preconditions:

  1. xid must in ended state.
private void
commitPrepared(Xid xid)

Commits prepared transaction.

private void
debug(String s)

public void
end(Xid
A global transaction identifier that is the same as the identifier used previously in the start method.
xid, int
One of TMSUCCESS, TMFAIL, or TMSUSPEND.
flags)

Implements javax.transaction.xa.XAResource.end.

Preconditions:

  1. Flags is one of TMSUCCESS, TMFAIL, TMSUSPEND
  2. xid != null
  3. Connection is associated with transaction xid
public void
forget(Xid
A global transaction identifier.
xid)

Implements javax.transaction.xa.XAResource.forget.

Does nothing, since we don't do heuristics.

public Connection
getConnection()

Overrides org.postgresql.ds.PGPooledConnection.getConnection.

Implements javax.sql.PooledConnection.getConnection.

XAConnection interface.

public int
getTransactionTimeout()

Implements javax.transaction.xa.XAResource.getTransactionTimeout.

We don't do transaction timeouts.

public XAResource
getXAResource()

Implements javax.sql.XAConnection.getXAResource.

Retrieves an XAResource object that the transaction manager will use to manage this XAConnection object's participation in a distributed transaction.

private boolean
isPostgreSQLIntegrityConstraintViolation(SQLException sqlException)

public boolean
isSameRM(XAResource
An XAResource object whose resource manager instance is to be compared with the resource manager instance of the target object.
xares)

Implements javax.transaction.xa.XAResource.isSameRM.

This method is called to determine if the resource manager instance represented by the target object is the same as the resource manager instance represented by the parameter xares.

private int
mapSQLStateToXAErrorCode(SQLException sqlException)

public int
prepare(Xid
A global transaction identifier.
xid)

Implements javax.transaction.xa.XAResource.prepare.

Prepares transaction.

public Xid[]
recover(int
One of TMSTARTRSCAN, TMENDRSCAN, TMNOFLAGS. TMNOFLAGS must be used when no other flags are set in the parameter.
flag)

Implements javax.transaction.xa.XAResource.recover.

Recovers transaction.

public void
rollback(Xid
A global transaction identifier.
xid)

Implements javax.transaction.xa.XAResource.rollback.

Preconditions:

  1. xid is known to the RM or it's in prepared state
public boolean
setTransactionTimeout(int
The transaction timeout value in seconds.
seconds)

Implements javax.transaction.xa.XAResource.setTransactionTimeout.

We don't do transaction timeouts.

public void
start(Xid
A global transaction identifier to be associated with the resource.
xid, int
One of TMNOFLAGS, TMJOIN, or TMRESUME.
flags)

Implements javax.transaction.xa.XAResource.start.

Preconditions:

  1. Flags must be one of TMNOFLAGS, TMRESUME or TMJOIN
  2. xid != null
  3. Connection must not be associated with a transaction
  4. The TM hasn't seen the xid before
Inherited from org.postgresql.ds.PGPooledConnection:
addConnectionEventListeneraddStatementEventListenerclosecreateConnectionEventremoveConnectionEventListenerremoveStatementEventListener

Field Detail

committedOrRolledBackback to summary
private boolean committedOrRolledBack
connback to summary
private final BaseConnection conn

Underlying physical database connection. It's used for issuing PREPARE TRANSACTION/ COMMIT PREPARED/ROLLBACK PREPARED commands.

currentXidback to summary
private @Nullable Xid currentXid
localAutoCommitModeback to summary
private boolean localAutoCommitMode
LOGGERback to summary
private static final Logger LOGGER
preparedXidback to summary
private @Nullable Xid preparedXid
stateback to summary
private PGXAConnection.State state

Constructor Detail

PGXAConnectionback to summary
public PGXAConnection(BaseConnection conn) throws SQLException

Method Detail

commitback to summary
public void commit(Xid xid, boolean onePhase) throws XAException

Implements javax.transaction.xa.XAResource.commit.

Doc from javax.transaction.xa.XAResource.commit.

Commits the global transaction specified by xid.

Parameters
xid:Xid

A global transaction identifier

onePhase:boolean

If true, the resource manager should use a one-phase commit protocol to commit the work done on behalf of xid.

Annotations
@Override
Exceptions
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.

commitOnePhaseback to summary
private void commitOnePhase(Xid xid) throws XAException

Preconditions:

  1. xid must in ended state.

Implementation deficiency preconditions:

  1. this connection must have been used to run the transaction

Postconditions:

  1. Transaction is committed
commitPreparedback to summary
private void commitPrepared(Xid xid) throws XAException

Commits prepared transaction. Preconditions:

  1. xid must be in prepared state in the server

Implementation deficiency preconditions:

  1. Connection must be in idle state

Postconditions:

  1. Transaction is committed
debugback to summary
private void debug(String s)
endback to summary
public void end(Xid xid, int flags) throws XAException

Implements javax.transaction.xa.XAResource.end.

Preconditions:

  1. Flags is one of TMSUCCESS, TMFAIL, TMSUSPEND
  2. xid != null
  3. Connection is associated with transaction xid

Implementation deficiency preconditions:

  1. Flags is not TMSUSPEND

Postconditions:

  1. Connection is disassociated from the transaction.
Parameters
xid:Xid

Doc from javax.transaction.xa.XAResource.end.

A global transaction identifier that is the same as the identifier used previously in the start method.

flags:int

Doc from javax.transaction.xa.XAResource.end.

One of TMSUCCESS, TMFAIL, or TMSUSPEND.

Annotations
@Override
Exceptions
XAException:

Doc from javax.transaction.xa.XAResource.end.

An error has occurred. Possible XAException values are XAER_RMERR, XAER_RMFAILED, XAER_NOTA, XAER_INVAL, XAER_PROTO, or XA_RB*.

forgetback to summary
public void forget(Xid xid) throws XAException

Implements javax.transaction.xa.XAResource.forget.

Does nothing, since we don't do heuristics.

Parameters
xid:Xid

Doc from javax.transaction.xa.XAResource.forget.

A global transaction identifier.

Annotations
@Override
Exceptions
XAException:

Doc from javax.transaction.xa.XAResource.forget.

An error has occurred. Possible exception values are XAER_RMERR, XAER_RMFAIL, XAER_NOTA, XAER_INVAL, or XAER_PROTO.

getConnectionback to summary
public Connection getConnection() throws SQLException

Overrides org.postgresql.ds.PGPooledConnection.getConnection.

Implements javax.sql.PooledConnection.getConnection.

XAConnection interface.

Returns:Connection

Doc from javax.sql.PooledConnection.getConnection.

a Connection object that is a handle to this PooledConnection object

Annotations
@Override
Exceptions
SQLException:

Doc from javax.sql.PooledConnection.getConnection.

if a database access error occurs

getTransactionTimeoutback to summary
public int getTransactionTimeout()

Implements javax.transaction.xa.XAResource.getTransactionTimeout.

We don't do transaction timeouts. Just returns 0.

Returns:int

Doc from javax.transaction.xa.XAResource.getTransactionTimeout.

the transaction timeout value in seconds.

Annotations
@Override
getXAResourceback to summary
public XAResource getXAResource()

Implements javax.sql.XAConnection.getXAResource.

Doc from javax.sql.XAConnection.getXAResource.

Retrieves an XAResource object that the transaction manager will use to manage this XAConnection object's participation in a distributed transaction.

Returns:XAResource

the XAResource object

Annotations
@Override
isPostgreSQLIntegrityConstraintViolationback to summary
private boolean isPostgreSQLIntegrityConstraintViolation(SQLException sqlException)
isSameRMback to summary
public boolean isSameRM(XAResource xares) throws XAException

Implements javax.transaction.xa.XAResource.isSameRM.

Doc from javax.transaction.xa.XAResource.isSameRM.

This method is called to determine if the resource manager instance represented by the target object is the same as the resource manager instance represented by the parameter xares.

Parameters
xares:XAResource

An XAResource object whose resource manager instance is to be compared with the resource manager instance of the target object.

Returns:boolean

true if it's the same RM instance; otherwise false.

Annotations
@Override
Exceptions
XAException:
An error has occurred. Possible exception values are XAER_RMERR and XAER_RMFAIL.
mapSQLStateToXAErrorCodeback to summary
private int mapSQLStateToXAErrorCode(SQLException sqlException)
prepareback to summary
public int prepare(Xid xid) throws XAException

Implements javax.transaction.xa.XAResource.prepare.

Prepares transaction. Preconditions:

  1. xid != null
  2. xid is in ended state

Implementation deficiency preconditions:

  1. xid was associated with this connection

Postconditions:

  1. Transaction is prepared
Parameters
xid:Xid

Doc from javax.transaction.xa.XAResource.prepare.

A global transaction identifier.

Returns:int

Doc from javax.transaction.xa.XAResource.prepare.

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.

Annotations
@Override
Exceptions
XAException:

Doc from javax.transaction.xa.XAResource.prepare.

An error has occurred. Possible exception values are: XA_RB*, XAER_RMERR, XAER_RMFAIL, XAER_NOTA, XAER_INVAL, or XAER_PROTO.

recoverback to summary
public Xid[] recover(int flag) throws XAException

Implements javax.transaction.xa.XAResource.recover.

Recovers transaction. Preconditions:

  1. flag must be one of TMSTARTRSCAN, TMENDRSCAN, TMNOFLAGS or TMSTARTTRSCAN | TMENDRSCAN
  2. If flag isn't TMSTARTRSCAN or TMSTARTRSCAN | TMENDRSCAN, a recovery scan must be in progress

Postconditions:

  1. list of prepared xids is returned
Parameters
flag:int

Doc from javax.transaction.xa.XAResource.recover.

One of TMSTARTRSCAN, TMENDRSCAN, TMNOFLAGS. TMNOFLAGS must be used when no other flags are set in the parameter.

Returns:Xid[]

Doc from javax.transaction.xa.XAResource.recover.

The resource manager returns zero or more XIDs of 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.

Annotations
@Override
Exceptions
XAException:

Doc from javax.transaction.xa.XAResource.recover.

An error has occurred. Possible values are XAER_RMERR, XAER_RMFAIL, XAER_INVAL, and XAER_PROTO.

rollbackback to summary
public void rollback(Xid xid) throws XAException

Implements javax.transaction.xa.XAResource.rollback.

Preconditions:

  1. xid is known to the RM or it's in prepared state

Implementation deficiency preconditions:

  1. xid must be associated with this connection if it's not in prepared state.

Postconditions:

  1. Transaction is rolled back and disassociated from connection
Parameters
xid:Xid

Doc from javax.transaction.xa.XAResource.rollback.

A global transaction identifier.

Annotations
@Override
Exceptions
XAException:

Doc from javax.transaction.xa.XAResource.rollback.

An error has occurred.

setTransactionTimeoutback to summary
public boolean setTransactionTimeout(int seconds)

Implements javax.transaction.xa.XAResource.setTransactionTimeout.

We don't do transaction timeouts. Returns false.

Parameters
seconds:int

Doc from javax.transaction.xa.XAResource.setTransactionTimeout.

The transaction timeout value in seconds.

Returns:boolean

Doc from javax.transaction.xa.XAResource.setTransactionTimeout.

true if the transaction timeout value is set successfully; otherwise false.

Annotations
@Override
startback to summary
public void start(Xid xid, int flags) throws XAException

Implements javax.transaction.xa.XAResource.start.

Preconditions:

  1. Flags must be one of TMNOFLAGS, TMRESUME or TMJOIN
  2. xid != null
  3. Connection must not be associated with a transaction
  4. The TM hasn't seen the xid before

Implementation deficiency preconditions:

  1. TMRESUME not supported.
  2. If flags is TMJOIN, we must be in ended state, and xid must be the current transaction
  3. Unless flags is TMJOIN, previous transaction using the connection must be committed or prepared or rolled back

Postconditions:

  1. Connection is associated with the transaction
Parameters
xid:Xid

Doc from javax.transaction.xa.XAResource.start.

A global transaction identifier to be associated with the resource.

flags:int

Doc from javax.transaction.xa.XAResource.start.

One of TMNOFLAGS, TMJOIN, or TMRESUME.

Annotations
@Override
Exceptions
XAException:

Doc from javax.transaction.xa.XAResource.start.

An error has occurred. Possible exceptions are XA_RB*, XAER_RMERR, XAER_RMFAIL, XAER_DUPID, XAER_OUTSIDE, XAER_NOTA, XAER_INVAL, or XAER_PROTO.

org.postgresql.xa back to summary

private Class PGXAConnection.ConnectionHandler

extends Object
implements InvocationHandler
Class Inheritance
All Implemented Interfaces
java.lang.reflect.InvocationHandler

Field Summary

Modifier and TypeField and Description
private final Connection
con

Constructor Summary

AccessConstructor and Description
pack-priv
ConnectionHandler(Connection con)

Method Summary

Modifier and TypeMethod and Description
public @Nullable Object
invoke(Object
the proxy instance that the method was invoked on
proxy, Method
the Method instance corresponding to the interface method invoked on the proxy instance. The declaring class of the Method object will be the interface that the method was declared in, which may be a superinterface of the proxy interface that the proxy class inherits the method through.
method, @Nullable Object[]
an array of objects containing the values of the arguments passed in the method invocation on the proxy instance, or null if interface method takes no arguments. Arguments of primitive types are wrapped in instances of the appropriate primitive wrapper class, such as java.lang.Integer or java.lang.Boolean.
args)

Implements java.lang.reflect.InvocationHandler.invoke.

Processes a method invocation on a proxy instance and returns the result.

Inherited from java.lang.Object:
cloneequalsfinalizegetClasshashCodenotifynotifyAlltoStringwaitwaitwait

Field Detail

conback to summary
private final Connection con

Constructor Detail

ConnectionHandlerback to summary
pack-priv ConnectionHandler(Connection con)

Method Detail

invokeback to summary
public @Nullable Object invoke(Object proxy, Method method, @Nullable Object[] args) throws Throwable

Implements java.lang.reflect.InvocationHandler.invoke.

Doc from java.lang.reflect.InvocationHandler.invoke.

Processes a method invocation on a proxy instance and returns the result. This method will be invoked on an invocation handler when a method is invoked on a proxy instance that it is associated with.

Parameters
proxy:Object

the proxy instance that the method was invoked on

method:Method

the Method instance corresponding to the interface method invoked on the proxy instance. The declaring class of the Method object will be the interface that the method was declared in, which may be a superinterface of the proxy interface that the proxy class inherits the method through.

args:@Nullable Object[]

an array of objects containing the values of the arguments passed in the method invocation on the proxy instance, or null if interface method takes no arguments. Arguments of primitive types are wrapped in instances of the appropriate primitive wrapper class, such as java.lang.Integer or java.lang.Boolean.

Returns:@Nullable Object

the value to return from the method invocation on the proxy instance. If the declared return type of the interface method is a primitive type, then the value returned by this method must be an instance of the corresponding primitive wrapper class; otherwise, it must be a type assignable to the declared return type. If the value returned by this method is null and the interface method's return type is primitive, then a NullPointerException will be thrown by the method invocation on the proxy instance. If the value returned by this method is otherwise not compatible with the interface method's declared return type as described above, a ClassCastException will be thrown by the method invocation on the proxy instance.

Annotations
@Override
@SuppressWarnings:throwing.nullable
Exceptions
Throwable:
the exception to throw from the method invocation on the proxy instance. The exception's type must be assignable either to any of the exception types declared in the throws clause of the interface method or to the unchecked exception types java.lang.RuntimeException or java.lang.Error. If a checked exception is thrown by this method that is not assignable to any of the exception types declared in the throws clause of the interface method, then an UndeclaredThrowableException containing the exception that was thrown by this method will be thrown by the method invocation on the proxy instance.
org.postgresql.xa back to summary

private final Enum PGXAConnection.State

extends Enum<PGXAConnection.State>
Class Inheritance

Field Summary

Modifier and TypeField and Description
public static final PGXAConnection.State
ACTIVE

start(Xid, int) has been called, and we're associated with an XA transaction.

public static final PGXAConnection.State
ENDED

end(Xid, int) has been called, but the transaction has not yet been prepared.

public static final PGXAConnection.State
IDLE

PGXAConnection not associated with a XA-transaction.

Constructor Summary

AccessConstructor and Description
private
State()

Method Summary

Modifier and TypeMethod and Description
public static PGXAConnection.State
valueOf(String name)

public static PGXAConnection.State[]
values()

Inherited from java.lang.Enum:
clonecompareTodescribeConstableequalsfinalizegetDeclaringClasshashCodenameordinaltoStringvalueOf

Field Detail

ACTIVEback to summary
public static final PGXAConnection.State ACTIVE

start(Xid, int) has been called, and we're associated with an XA transaction. currentXid is valid. autoCommit is false on a connection returned by getConnection, and should not be messed with by the caller or the XA transaction will be broken.

ENDEDback to summary
public static final PGXAConnection.State ENDED

end(Xid, int) has been called, but the transaction has not yet been prepared. currentXid is still valid. You shouldn't use the connection for anything else than issuing a XAResource#commit(Xid, boolean) or rollback.

IDLEback to summary
public static final PGXAConnection.State IDLE

PGXAConnection not associated with a XA-transaction. You can still call getConnection() and use the connection outside XA. currentXid is null. autoCommit is true on a connection by getConnection, per normal JDBC rules, though the caller can change it to false and manage transactions itself using Connection.commit and rollback.

Constructor Detail

Stateback to summary
private State()

Method Detail

valueOfback to summary
public static PGXAConnection.State valueOf(String name)
valuesback to summary
public static PGXAConnection.State[] values()