org.firebirdsql.jca

Class FBManagedConnection

Implemented Interfaces:
org.firebirdsql.gds.impl.GDSHelper.GDSHelperErrorListener, ManagedConnection, XAResource

public class FBManagedConnection
extends java.lang.Object
implements ManagedConnection, XAResource, org.firebirdsql.gds.impl.GDSHelper.GDSHelperErrorListener

The class FBManagedConnection implements both the ManagedConnection and XAResource interfaces.
Version:
1.0
Author:
David Jencks

Method Summary

void
addConnectionEventListener(ConnectionEventListener listener)
Add an ConnectionEventListener listener.
void
associateConnection(Object connection)
Used by the container to change the association of an application-level connection handle with a ManagedConneciton instance.
void
cleanup()
Application server calls this method to force any cleanup on the ManagedConnection instance.
void
close(AbstractConnection c)
Close this connection with regards to a wrapping AbstractConnection.
void
commit(Xid id, boolean onePhase)
Commits a transaction.
void
destroy()
Destroys the physical connection to the underlying resource manager.
void
end(Xid id, int flags)
Dissociates a resource from a global transaction.
void
errorOccured(GDSException ex)
Notify GDS container that error occured, if the ex represents a "fatal" one
void
forget(Xid id)
Indicates that no further action will be taken on behalf of this transaction (after a heuristic failure).
Object
getConnection(Subject subject, ConnectionRequestInfo cri)
Creates a new connection handle for the underlying physical connection represented by the ManagedConnection instance.
FBConnectionRequestInfo
getConnectionRequestInfo()
Get information about the current connection parameters.
String
getDatabase()
org.firebirdsql.gds.impl.GDSHelper
getGDSHelper()
Get instance of GDSHelper connected with this managed connection.
LocalTransaction
getLocalTransaction()
Returns a javax.resource.spi.LocalTransaction instance.
PrintWriter
getLogWriter()
Gets the log writer for this ManagedConnection instance.
ManagedConnectionFactory
getManagedConnectionFactory()
Get the managed connection factory that created this managed connection.
ManagedConnectionMetaData
getMetaData()
Gets the metadata information for this connection's underlying EIS resource manager instance.
int
getTransactionIsolation()
Get the transaction isolation level of this connection.
TransactionParameterBuffer
getTransactionParameters()
TransactionParameterBuffer
getTransactionParameters(int isolation)
int
getTransactionTimeout()
Gets the transaction timeout.
javax.transaction.xa.XAResource
getXAResource()
Return an XA resource to the caller.
boolean
inTransaction()
void
internalStart(Xid id, int flags)
Perform the internal processing to start associate a JDBC connection with a global transaction.
boolean
isConnectionSharing()
Check if connection sharing is enabled.
boolean
isManagedEnvironment()
boolean
isReadOnly()
Retrieve whether this connection is readonly.
boolean
isSameRM(XAResource res)
Retrieve whether this FBManagedConnection uses the same ResourceManager as res.
int
prepare(Xid xid)
Prepares a transaction to commit.
Xid[]
recover(int flag)
Obtain a list of prepared transaction branches from a resource manager.
void
removeConnectionEventListener(ConnectionEventListener listener)
Remove a ConnectionEventListner from the listing of listeners that will be notified for a ConnectionEvent.
void
rollback(Xid id)
Rolls back the work, assuming it was done on behalf of the specified transaction.
void
setConnectionSharing(boolean connectionSharing)
Enable or disable connection sharing.
void
setLogWriter(PrintWriter out)
Sets the log writer for this ManagedConnection instance.
void
setManagedEnvironment(boolean managedEnvironment)
void
setReadOnly(boolean readOnly)
Set whether this connection is to be readonly
void
setTransactionIsolation(int isolation)
Set the transaction level for this connection.
void
setTransactionParameters(int isolation, TransactionParameterBuffer transactionParams)
void
setTransactionParameters(TransactionParameterBuffer transactionParameters)
boolean
setTransactionTimeout(int timeout)
Sets the transaction timeout.
void
start(Xid id, int flags)
Associates a JDBC connection with a global transaction.

Method Details

addConnectionEventListener

public void addConnectionEventListener(ConnectionEventListener listener)
Add an ConnectionEventListener listener. The listener will be notified when a ConnectionEvent occurs.
Parameters:
listener - The ConnectionEventListener to be added

associateConnection

public void associateConnection(Object connection)
            throws ResourceException
Used by the container to change the association of an application-level connection handle with a ManagedConneciton instance. The container should find the right ManagedConnection instance and call the associateConnection method.

The resource adapter is required to implement the associateConnection method. The method implementation for a ManagedConnection should dissociate the connection handle (passed as a parameter) from its currently associated ManagedConnection and associate the new connection handle with itself.

Parameters:
connection - Application-level connection handle

cleanup

public void cleanup()
            throws ResourceException
Application server calls this method to force any cleanup on the ManagedConnection instance.

The method ManagedConnection.cleanupinitiates a cleanup of the any client-specific state as maintained by a ManagedConnection instance. The cleanup should invalidate all connection handles that had been created using this ManagedConnection instance. Any attempt by an application component to use the connection handle after cleanup of the underlying ManagedConnection should result in an exception.

The cleanup of ManagedConnection is always driven by an application server. An application server should not invoke ManagedConnection.cleanupwhen there is an uncompleted transaction (associated with a ManagedConnection instance) in progress.

The invocation of ManagedConnection.cleanupmethod on an already cleaned-up connection should not throw an exception. The cleanup of ManagedConnection instance resets its client specific state and prepares the connection to be put back in to a connection pool. The cleanup method should not cause resource adapter to close the physical pipe and reclaim system resources associated with the physical connection.


close

public void close(AbstractConnection c)
Close this connection with regards to a wrapping AbstractConnection.
Parameters:
c - The AbstractConnection that is being closed

commit

public void commit(Xid id,
                   boolean onePhase)
            throws XAException
Commits a transaction.

destroy

public void destroy()
            throws ResourceException
Destroys the physical connection to the underlying resource manager. To manage the size of the connection pool, an application server can explictly call ManagedConnection.destroyto destroy a physical connection. A resource adapter should destroy all allocated system resources for this ManagedConnection instance when the method destroy is called.

end

public void end(Xid id,
                int flags)
            throws XAException
Dissociates a resource from a global transaction.

errorOccured

public void errorOccured(GDSException ex)
Notify GDS container that error occured, if the ex represents a "fatal" one
See Also:
FatalGDSErrorHelper.isFatal(GDSException)

forget

public void forget(Xid id)
            throws javax.transaction.xa.XAException
Indicates that no further action will be taken on behalf of this transaction (after a heuristic failure). It is assumed this will be called after a failed commit or rollback. This should actually never be called since we don't use heuristic tx completion on timeout.

getConnection

public Object getConnection(Subject subject,
                            ConnectionRequestInfo cri)
            throws ResourceException
Creates a new connection handle for the underlying physical connection represented by the ManagedConnection instance. This connection handle is used by the application code to refer to the underlying physical connection. A connection handle is tied to its ManagedConnection instance in a resource adapter implementation specific way.

The ManagedConnection uses the Subject and additional ConnectionRequestInfo (which is specific to resource adapter and opaque to application server) to set the state of the physical connection.

Parameters:
subject - security context as JAAS subject
cri - ConnectionRequestInfo instance
Returns:
generic Object instance representing the connection handle. For CCI, the connection handle created by a ManagedConnection instance is of the type javax.resource.cci.Connection.

getConnectionRequestInfo

public FBConnectionRequestInfo getConnectionRequestInfo()
Get information about the current connection parameters.
Returns:
instance of FBConnectionRequestInfo.

getDatabase

public String getDatabase()

getGDSHelper

public org.firebirdsql.gds.impl.GDSHelper getGDSHelper()
            throws GDSException
Get instance of GDSHelper connected with this managed connection.
Returns:
instance of GDSHelper.

getLocalTransaction

public LocalTransaction getLocalTransaction()
Returns a javax.resource.spi.LocalTransaction instance. The LocalTransaction interface is used by the container to manage local transactions for a RM instance.
Returns:
LocalTransaction instance

getLogWriter

public PrintWriter getLogWriter()
Gets the log writer for this ManagedConnection instance.

The log writer is a character output stream to which all logging and tracing messages for this ManagedConnection instance will be printed. ConnectionManager manages the association of output stream with the ManagedConnection instance based on the connection pooling requirements.

The Log writer associated with a ManagedConnection instance can be one set as default from the ManagedConnectionFactory (that created this connection) or one set specifically for this instance by the application server.

Returns:
Character ourput stream associated with this ManagedConnection

getManagedConnectionFactory

public ManagedConnectionFactory getManagedConnectionFactory()
Get the managed connection factory that created this managed connection.
Returns:
instance of ManagedConnectionFactory.

getMetaData

public ManagedConnectionMetaData getMetaData()
            throws ResourceException
Gets the metadata information for this connection's underlying EIS resource manager instance. The ManagedConnectionMetaData interface provides information about the underlying EIS instance associated with the ManagedConenction instance.
Returns:
ManagedConnectionMetaData instance

getTransactionIsolation

public int getTransactionIsolation()
            throws ResourceException
Get the transaction isolation level of this connection. The level is one of the static final fields of java.sql.Connection (i.e. TRANSACTION_READ_COMMITTED, TRANSACTION_READ_UNCOMMITTED, TRANSACTION_REPEATABLE_READ, TRANSACTION_SERIALIZABLE.
Returns:
Value representing a transaction isolation level defined in java.sql.Connection.

getTransactionParameters

public TransactionParameterBuffer getTransactionParameters()

getTransactionParameters

public TransactionParameterBuffer getTransactionParameters(int isolation)

getTransactionTimeout

public int getTransactionTimeout()
            throws javax.transaction.xa.XAException
Gets the transaction timeout.

getXAResource

public javax.transaction.xa.XAResource getXAResource()
Return an XA resource to the caller.

In both javax.sql.XAConnection and javax.resource.spi.MangagedConnection.

Returns:
the XAResource

inTransaction

public boolean inTransaction()

internalStart

public void internalStart(Xid id,
                          int flags)
            throws XAException,
                   GDSException
Perform the internal processing to start associate a JDBC connection with a global transaction.
Parameters:
id - A global transaction identifier to be associated with the resource
flags - One of TMNOFLAGS, TMJOIN, or TMRESUME

isConnectionSharing

public boolean isConnectionSharing()
Check if connection sharing is enabled. When connection sharing is enabled, multiple connection handles (AbstractConnection instances) can access this managed connection in thread-safe manner (they synchronize on this instance). This feature can be enabled only in JCA environment, any other environment must not use connection sharing.
Returns:
true if connection sharing is enabled.

isManagedEnvironment

public boolean isManagedEnvironment()

isReadOnly

public boolean isReadOnly()
Retrieve whether this connection is readonly.
Returns:
true if this connection is readonly, false otherwise

isSameRM

public boolean isSameRM(XAResource res)
            throws javax.transaction.xa.XAException
Retrieve whether this FBManagedConnection uses the same ResourceManager as res. This method relies on res being a Firebird implementation of XAResource.
Parameters:
res - The other XAResource to compare to
Returns:
true if res uses the same ResourceManager, false otherwise

prepare

public int prepare(Xid xid)
            throws javax.transaction.xa.XAException
Prepares a transaction to commit.

recover

public 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.
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.

removeConnectionEventListener

public void removeConnectionEventListener(ConnectionEventListener listener)
Remove a ConnectionEventListner from the listing of listeners that will be notified for a ConnectionEvent.
Parameters:
listener - The ConnectionEventListener to be removed

rollback

public void rollback(Xid id)
            throws XAException
Rolls back the work, assuming it was done on behalf of the specified transaction.

setConnectionSharing

public void setConnectionSharing(boolean connectionSharing)
Parameters:
connectionSharing - true if connection sharing must be enabled.

setLogWriter

public void setLogWriter(PrintWriter out)
Sets the log writer for this ManagedConnection instance.

The log writer is a character output stream to which all logging and tracing messages for this ManagedConnection instance will be printed. Application Server manages the association of output stream with the ManagedConnection instance based on the connection pooling requirements.

When a ManagedConnection object is initially created, the default log writer associated with this instance is obtained from the ManagedConnectionFactory. An application server can set a log writer specific to this ManagedConnection to log/trace this instance using setLogWriter method.

Parameters:
out - Character Output stream to be associated

setManagedEnvironment

public void setManagedEnvironment(boolean managedEnvironment)
            throws ResourceException

setReadOnly

public void setReadOnly(boolean readOnly)
Set whether this connection is to be readonly
Parameters:
readOnly - If true, the connection will be set read-only, otherwise it will be writable

setTransactionIsolation

public void setTransactionIsolation(int isolation)
            throws ResourceException
Set the transaction level for this connection. The level is one of the static final fields of java.sql.Connection (i.e. TRANSACTION_READ_COMMITTED, TRANSACTION_READ_UNCOMMITTED, TRANSACTION_REPEATABLE_READ, TRANSACTION_SERIALIZABLE.
Parameters:
isolation - Value representing a transaction isolation level defined in java.sql.Connection.

setTransactionParameters

public void setTransactionParameters(int isolation,
                                     TransactionParameterBuffer transactionParams)

setTransactionParameters

public void setTransactionParameters(TransactionParameterBuffer transactionParameters)

setTransactionTimeout

public boolean setTransactionTimeout(int timeout)
            throws javax.transaction.xa.XAException
Sets the transaction timeout. This is saved, but the value is not used by the current implementation.
Parameters:
timeout - The timeout to be set in seconds

start

public void start(Xid id,
                  int flags)
            throws XAException
Associates a JDBC connection with a global transaction. We assume that end will be called followed by prepare, commit, or rollback. If start is called after end but before commit or rollback, there is no way to distinguish work done by different transactions on the same connection). If start is called more than once before end, either it's a duplicate transaction ID or illegal transaction ID (since you can't have two transactions associated with one DB connection).
Parameters:
id - A global transaction identifier to be associated with the resource
flags - One of TMNOFLAGS, TMJOIN, or TMRESUME

Copyright B) 2001 David Jencks and other authors. All rights reserved.