Class FBManagedConnection
- java.lang.Object
-
- org.firebirdsql.jca.FBManagedConnection
-
- All Implemented Interfaces:
javax.resource.spi.ManagedConnection,javax.transaction.xa.XAResource,ExceptionListener,Synchronizable
public class FBManagedConnection extends java.lang.Object implements javax.resource.spi.ManagedConnection, javax.transaction.xa.XAResource, ExceptionListener, Synchronizable
The classFBManagedConnectionimplements both the ManagedConnection and XAResource interfaces.- Version:
- 1.0
- Author:
- David Jencks, Mark Rotteveel
-
-
Field Summary
Fields Modifier and Type Field Description static java.lang.StringERROR_NO_CHARSETstatic java.lang.StringWARNING_NO_CHARSET
-
Method Summary
All Methods Instance Methods Concrete Methods Modifier and Type Method Description voidaddConnectionEventListener(javax.resource.spi.ConnectionEventListener listener)Add anConnectionEventListenerlistener.voidassociateConnection(java.lang.Object connection)Used by the container to change the association of an application-level connection handle with a ManagedConneciton instance.voidcleanup()Application server calls this method to force any cleanup on theManagedConnectioninstance.voidclose(FBConnection c)Close this connection with regards to a wrappingAbstractConnection.voidcommit(javax.transaction.xa.Xid id, boolean onePhase)Commits a transaction.voiddestroy()Destroys the physical connection to the underlying resource manager.voiddestroy(javax.resource.spi.ConnectionEvent connectionEvent)voidend(javax.transaction.xa.Xid id, int flags)Dissociates a resource from a global transaction.voiderrorOccurred(java.lang.Object source, java.sql.SQLException ex)Notify about a SQLExceptionprotected javax.transaction.xa.XidfindSingleXid(javax.transaction.xa.Xid externalXid)Obtain a single prepared transaction branch from a resource manager, based on a Xidvoidforget(javax.transaction.xa.Xid id)Indicates that no further action will be taken on behalf of this transaction (after a heuristic failure).java.lang.ObjectgetConnection(javax.security.auth.Subject subject, javax.resource.spi.ConnectionRequestInfo cri)Creates a new connection handle for the underlying physical connection represented by theManagedConnectioninstance.FBConnectionRequestInfogetConnectionRequestInfo()Get information about the current connection parameters.java.lang.StringgetDatabase()GDSHelpergetGDSHelper()Get instance ofGDSHelperconnected with this managed connection.javax.resource.spi.LocalTransactiongetLocalTransaction()Returns ajavax.resource.spi.LocalTransactioninstance.java.io.PrintWritergetLogWriter()Gets the log writer for this ManagedConnection instance.javax.resource.spi.ManagedConnectionFactorygetManagedConnectionFactory()Get the managed connection factory that created this managed connection.javax.resource.spi.ManagedConnectionMetaDatagetMetaData()Gets the metadata information for this connection's underlying EIS resource manager instance.java.lang.ObjectgetSynchronizationObject()Get synchronization object.intgetTransactionIsolation()Get the transaction isolation level of this connection.TransactionParameterBuffergetTransactionParameters()TransactionParameterBuffergetTransactionParameters(int isolation)intgetTransactionTimeout()Gets the transaction timeout.javax.transaction.xa.XAResourcegetXAResource()Return an XA resource to the caller.booleaninDistributedTransaction()voidinternalStart(javax.transaction.xa.Xid id, int flags)Perform the internal processing to start associate a JDBC connection with a global transaction.booleaninTransaction()booleanisConnectionSharing()Check if connection sharing is enabled.booleanisManagedEnvironment()booleanisReadOnly()Retrieve whether this connection is readonly.booleanisSameRM(javax.transaction.xa.XAResource res)Retrieve whether thisFBManagedConnectionuses the same ResourceManager asres.intprepare(javax.transaction.xa.Xid xid)Prepares a transaction to commit.javax.transaction.xa.Xid[]recover(int flags)Obtain a list of prepared transaction branches from a resource manager.voidremoveConnectionEventListener(javax.resource.spi.ConnectionEventListener listener)Remove aConnectionEventListnerfrom the listing of listeners that will be notified for aConnectionEvent.voidrollback(javax.transaction.xa.Xid xid)Rolls back the work, assuming it was done on behalf of the specified transaction.voidsetConnectionSharing(boolean connectionSharing)Enable or disable connection sharing.voidsetLogWriter(java.io.PrintWriter out)Sets the log writer for this ManagedConnection instance.voidsetManagedEnvironment(boolean managedEnvironment)voidsetReadOnly(boolean readOnly)Set whether this connection is to be readonlyvoidsetTransactionIsolation(int isolation)Set the transaction level for this connection.voidsetTransactionParameters(int isolation, TransactionParameterBuffer transactionParams)voidsetTransactionParameters(TransactionParameterBuffer transactionParameters)booleansetTransactionTimeout(int timeout)Sets the transaction timeout.voidstart(javax.transaction.xa.Xid id, int flags)Associates a JDBC connection with a global transaction.
-
-
-
Field Detail
-
WARNING_NO_CHARSET
public static final java.lang.String WARNING_NO_CHARSET
- See Also:
- Constant Field Values
-
ERROR_NO_CHARSET
public static final java.lang.String ERROR_NO_CHARSET
- See Also:
- Constant Field Values
-
-
Method Detail
-
errorOccurred
public void errorOccurred(java.lang.Object source, java.sql.SQLException ex)Description copied from interface:ExceptionListenerNotify about a SQLException- Specified by:
errorOccurredin interfaceExceptionListener- Parameters:
source- The source of the event; note for caller: this should be the object this listener is registered at.ex- error that occurred.
-
getGDSHelper
public GDSHelper getGDSHelper() throws java.sql.SQLException
Get instance ofGDSHelperconnected with this managed connection.- Returns:
- instance of
GDSHelper. - Throws:
java.sql.SQLException- If this connection has no GDSHelper
-
getDatabase
public java.lang.String getDatabase()
-
isManagedEnvironment
public boolean isManagedEnvironment()
-
inTransaction
public boolean inTransaction()
-
setManagedEnvironment
public void setManagedEnvironment(boolean managedEnvironment) throws javax.resource.ResourceException- Throws:
javax.resource.ResourceException
-
isConnectionSharing
public boolean isConnectionSharing()
Check if connection sharing is enabled. When connection sharing is enabled, multiple connection handles (FBConnectioninstances) 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:
trueif connection sharing is enabled.
-
setConnectionSharing
public void setConnectionSharing(boolean connectionSharing) throws javax.resource.ResourceExceptionEnable or disable connection sharing. SeeisConnectionSharing()method for details.- Parameters:
connectionSharing-trueif connection sharing must be enabled.- Throws:
javax.resource.ResourceException- If connection sharing state cannot be changed
-
getLocalTransaction
public javax.resource.spi.LocalTransaction getLocalTransaction()
Returns ajavax.resource.spi.LocalTransactioninstance. The LocalTransaction interface is used by the container to manage local transactions for a RM instance.- Specified by:
getLocalTransactionin interfacejavax.resource.spi.ManagedConnection- Returns:
- LocalTransaction instance
- Throws:
javax.resource.ResourceException- generic exception if operation failsjavax.resource.NotSupportedException- if the operation is not supportedjavax.resource.spi.ResourceAdapterInternalException- resource adapter internal error condition
-
getMetaData
public javax.resource.spi.ManagedConnectionMetaData getMetaData() throws javax.resource.ResourceExceptionGets 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.- Specified by:
getMetaDatain interfacejavax.resource.spi.ManagedConnection- Returns:
- ManagedConnectionMetaData instance
- Throws:
javax.resource.ResourceException- generic exception if operation failsjavax.resource.NotSupportedException- if the operation is not supported
-
setLogWriter
public void setLogWriter(java.io.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.- Specified by:
setLogWriterin interfacejavax.resource.spi.ManagedConnection- Parameters:
out- Character Output stream to be associated- Throws:
javax.resource.ResourceException- generic exception if operation failsjavax.resource.spi.ResourceAdapterInternalException- resource adapter related error condition
-
getLogWriter
public java.io.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.
ConnectionManagermanages the association of output stream with theManagedConnectioninstance based on the connection pooling requirements.The Log writer associated with a
ManagedConnectioninstance can be one set as default from the ManagedConnectionFactory (that created this connection) or one set specifically for this instance by the application server.- Specified by:
getLogWriterin interfacejavax.resource.spi.ManagedConnection- Returns:
- Character ourput stream associated with this
ManagedConnection - Throws:
javax.resource.ResourceException- generic exception if operation fails
-
addConnectionEventListener
public void addConnectionEventListener(javax.resource.spi.ConnectionEventListener listener)
Add anConnectionEventListenerlistener. The listener will be notified when aConnectionEventoccurs.- Specified by:
addConnectionEventListenerin interfacejavax.resource.spi.ManagedConnection- Parameters:
listener- TheConnectionEventListenerto be added
-
removeConnectionEventListener
public void removeConnectionEventListener(javax.resource.spi.ConnectionEventListener listener)
Remove aConnectionEventListnerfrom the listing of listeners that will be notified for aConnectionEvent.- Specified by:
removeConnectionEventListenerin interfacejavax.resource.spi.ManagedConnection- Parameters:
listener- TheConnectionEventListenerto be removed
-
associateConnection
public void associateConnection(java.lang.Object connection) throws javax.resource.ResourceExceptionUsed 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.
- Specified by:
associateConnectionin interfacejavax.resource.spi.ManagedConnection- Parameters:
connection- Application-level connection handle- Throws:
javax.resource.ResourceException- Failed to associate the connection handle with this ManagedConnection instancejavax.resource.spi.IllegalStateException- Illegal state for invoking this methodjavax.resource.spi.ResourceAdapterInternalException- Resource adapter internal error condition
-
cleanup
public void cleanup() throws javax.resource.ResourceExceptionApplication server calls this method to force any cleanup on theManagedConnectioninstance.The method
ManagedConnection.cleanup()initiates 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 thisManagedConnectioninstance. Any attempt by an application component to use the connection handle after cleanup of the underlyingManagedConnectionshould result in an exception.The cleanup of ManagedConnection is always driven by an application server. An application server should not invoke
ManagedConnection.cleanup()when there is an uncompleted transaction (associated with a ManagedConnection instance) in progress.The invocation of
ManagedConnection.cleanup()method on an already cleaned-up connection should not throw an exception. The cleanup ofManagedConnectioninstance 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.- Specified by:
cleanupin interfacejavax.resource.spi.ManagedConnection- Throws:
javax.resource.ResourceException- generic exception if operation failsjavax.resource.spi.ResourceAdapterInternalException- resource adapter internal error conditionjavax.resource.spi.IllegalStateException- Illegal state for calling connection cleanup. Example - if a local transaction is in progress that doesn't allow connection cleanup
-
getConnection
public java.lang.Object getConnection(javax.security.auth.Subject subject, javax.resource.spi.ConnectionRequestInfo cri) throws javax.resource.ResourceExceptionCreates a new connection handle for the underlying physical connection represented by theManagedConnectioninstance. This connection handle is used by the application code to refer to the underlying physical connection. A connection handle is tied to itsManagedConnectioninstance in a resource adapter implementation specific way.The
ManagedConnectionuses the Subject and additionalConnectionRequestInfo(which is specific to resource adapter and opaque to application server) to set the state of the physical connection.- Specified by:
getConnectionin interfacejavax.resource.spi.ManagedConnection- Parameters:
subject- security context as JAAS subjectcri- ConnectionRequestInfo instance- Returns:
- generic
Objectinstance representing the connection handle. For CCI, the connection handle created by aManagedConnectioninstance is of the typejavax.resource.cci.Connection. - Throws:
javax.resource.ResourceException- generic exception if operation failsjavax.resource.spi.ResourceAdapterInternalException- resource adapter internal error conditionjavax.resource.spi.SecurityException- security related error conditionjavax.resource.spi.CommException- failed communication with EIS instancejavax.resource.spi.EISSystemException- internal error condition in EIS instance - used if EIS instance is involved in setting state ofManagedConnection
-
destroy
public void destroy() throws javax.resource.ResourceExceptionDestroys the physical connection to the underlying resource manager. To manage the size of the connection pool, an application server can explictly callManagedConnection.destroy()to destroy a physical connection. A resource adapter should destroy all allocated system resources for thisManagedConnectioninstance when the method destroy is called.- Specified by:
destroyin interfacejavax.resource.spi.ManagedConnection- Throws:
javax.resource.ResourceException- generic exception if operation failedjavax.resource.spi.IllegalStateException- illegal state for destroying connection
-
destroy
public void destroy(javax.resource.spi.ConnectionEvent connectionEvent) throws javax.resource.ResourceException- Throws:
javax.resource.ResourceException
-
getXAResource
public javax.transaction.xa.XAResource getXAResource()
Return an XA resource to the caller.In both
javax.sql.XAConnectionandjavax.resource.spi.MangagedConnection.- Specified by:
getXAResourcein interfacejavax.resource.spi.ManagedConnection- Returns:
- the XAResource
-
commit
public void commit(javax.transaction.xa.Xid id, boolean onePhase) throws javax.transaction.xa.XAExceptionCommits a transaction.- Specified by:
commitin interfacejavax.transaction.xa.XAResource- Throws:
javax.transaction.xa.XAException- Occurs when the state was not correct (end never called), the transaction ID is wrong, the connection was set to Auto-Commit, or the commit on the underlying connection fails. The error code differs depending on the exact situation.
-
end
public void end(javax.transaction.xa.Xid id, int flags) throws javax.transaction.xa.XAExceptionDissociates a resource from a global transaction.- Specified by:
endin interfacejavax.transaction.xa.XAResource- Throws:
javax.transaction.xa.XAException- Occurs when the state was not correct (end called twice), or the transaction ID is wrong.
-
forget
public void forget(javax.transaction.xa.Xid id) throws javax.transaction.xa.XAExceptionIndicates 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.- Specified by:
forgetin interfacejavax.transaction.xa.XAResource- Throws:
javax.transaction.xa.XAException- Occurs when the state was not correct (end never called), or the transaction ID is wrong.
-
getTransactionTimeout
public int getTransactionTimeout() throws javax.transaction.xa.XAExceptionGets the transaction timeout.- Specified by:
getTransactionTimeoutin interfacejavax.transaction.xa.XAResource- Throws:
javax.transaction.xa.XAException
-
isSameRM
public boolean isSameRM(javax.transaction.xa.XAResource res) throws javax.transaction.xa.XAExceptionRetrieve whether thisFBManagedConnectionuses the same ResourceManager asres. This method relies onresbeing a Firebird implementation ofXAResource.- Specified by:
isSameRMin interfacejavax.transaction.xa.XAResource- Parameters:
res- The otherXAResourceto compare to- Returns:
trueifresuses the same ResourceManager,falseotherwise- Throws:
javax.transaction.xa.XAException
-
prepare
public int prepare(javax.transaction.xa.Xid xid) throws javax.transaction.xa.XAExceptionPrepares a transaction to commit.- Specified by:
preparein interfacejavax.transaction.xa.XAResource- Throws:
javax.transaction.xa.XAException- Occurs when the state was not correct (end never called), the transaction ID is wrong, or the connection was set to Auto-Commit.
-
recover
public javax.transaction.xa.Xid[] recover(int flags) throws javax.transaction.xa.XAExceptionObtain 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:
recoverin interfacejavax.transaction.xa.XAResource- Parameters:
flags- 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.
-
findSingleXid
protected javax.transaction.xa.Xid findSingleXid(javax.transaction.xa.Xid externalXid) throws javax.transaction.xa.XAExceptionObtain a single prepared transaction branch from a resource manager, based on a Xid- Parameters:
externalXid- The Xid to find- Returns:
- The Xid if found, otherwise null.
- Throws:
javax.transaction.xa.XAException- An error has occurred. Possible values are XAER_RMERR, XAER_RMFAIL, XAER_INVAL, and XAER_PROTO.
-
getSynchronizationObject
public final java.lang.Object getSynchronizationObject()
Description copied from interface:SynchronizableGet synchronization object.- Specified by:
getSynchronizationObjectin interfaceSynchronizable- Returns:
- object, cannot be
null.
-
rollback
public void rollback(javax.transaction.xa.Xid xid) throws javax.transaction.xa.XAExceptionRolls back the work, assuming it was done on behalf of the specified transaction.- Specified by:
rollbackin interfacejavax.transaction.xa.XAResource- Throws:
javax.transaction.xa.XAException- Occurs when the state was not correct (end never called), the transaction ID is wrong, the connection was set to Auto-Commit, or the rollback on the underlying connection fails. The error code differs depending on the exact situation.
-
setTransactionTimeout
public boolean setTransactionTimeout(int timeout) throws javax.transaction.xa.XAExceptionSets the transaction timeout. This is saved, but the value is not used by the current implementation.- Specified by:
setTransactionTimeoutin interfacejavax.transaction.xa.XAResource- Parameters:
timeout- The timeout to be set in seconds- Throws:
javax.transaction.xa.XAException
-
inDistributedTransaction
public boolean inDistributedTransaction()
-
start
public void start(javax.transaction.xa.Xid id, int flags) throws javax.transaction.xa.XAExceptionAssociates 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).- Specified by:
startin interfacejavax.transaction.xa.XAResource- Parameters:
id- A global transaction identifier to be associated with the resourceflags- One of TMNOFLAGS, TMJOIN, or TMRESUME- Throws:
javax.transaction.xa.XAException- Occurs when the state was not correct (start called twice), the transaction ID is wrong, or the instance has already been closed.
-
internalStart
public void internalStart(javax.transaction.xa.Xid id, int flags) throws javax.transaction.xa.XAException, java.sql.SQLExceptionPerform the internal processing to start associate a JDBC connection with a global transaction.- Parameters:
id- A global transaction identifier to be associated with the resourceflags- One of TMNOFLAGS, TMJOIN, or TMRESUME- Throws:
javax.transaction.xa.XAException- If the transaction is already started, or this connection cannot participate in the distributed transactionjava.sql.SQLException- See Also:
start(Xid, int)
-
close
public void close(FBConnection c)
Close this connection with regards to a wrappingAbstractConnection.- Parameters:
c- TheAbstractConnectionthat is being closed
-
getConnectionRequestInfo
public FBConnectionRequestInfo getConnectionRequestInfo()
Get information about the current connection parameters.- Returns:
- instance of
FBConnectionRequestInfo.
-
getTransactionParameters
public TransactionParameterBuffer getTransactionParameters()
-
setTransactionParameters
public void setTransactionParameters(TransactionParameterBuffer transactionParameters)
-
getTransactionParameters
public TransactionParameterBuffer getTransactionParameters(int isolation)
-
setTransactionParameters
public void setTransactionParameters(int isolation, TransactionParameterBuffer transactionParams) throws javax.resource.ResourceException- Throws:
javax.resource.ResourceException
-
getTransactionIsolation
public int getTransactionIsolation() throws javax.resource.ResourceExceptionGet the transaction isolation level of this connection. The level is one of the static final fields ofjava.sql.Connection(i.e.TRANSACTION_READ_COMMITTED,TRANSACTION_READ_UNCOMMITTED,TRANSACTION_REPEATABLE_READ,TRANSACTION_SERIALIZABLE.- Returns:
- Value representing a transaction isolation level defined in
Connection. - Throws:
javax.resource.ResourceException- If the transaction level cannot be retrieved- See Also:
Connection,setTransactionIsolation(int)
-
setTransactionIsolation
public void setTransactionIsolation(int isolation) throws javax.resource.ResourceExceptionSet the transaction level for this connection. The level is one of the static final fields ofjava.sql.Connection(i.e.TRANSACTION_READ_COMMITTED,TRANSACTION_READ_UNCOMMITTED,TRANSACTION_REPEATABLE_READ,TRANSACTION_SERIALIZABLE.- Parameters:
isolation- Value representing a transaction isolation level defined inConnection.- Throws:
javax.resource.ResourceException- If the transaction level cannot be retrieved- See Also:
Connection,getTransactionIsolation()
-
getManagedConnectionFactory
public javax.resource.spi.ManagedConnectionFactory getManagedConnectionFactory()
Get the managed connection factory that created this managed connection.- Returns:
- instance of
ManagedConnectionFactory.
-
setReadOnly
public void setReadOnly(boolean readOnly)
Set whether this connection is to be readonly- Parameters:
readOnly- Iftrue, the connection will be set read-only, otherwise it will be writable
-
isReadOnly
public boolean isReadOnly()
Retrieve whether this connection is readonly.- Returns:
trueif this connection is readonly,falseotherwise
-
-