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 SummaryFields Modifier and Type Field Description static java.lang.StringERROR_NO_CHARSETstatic java.lang.StringWARNING_NO_CHARSET
 - 
Method SummaryAll 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_CHARSETpublic static final java.lang.String WARNING_NO_CHARSET - See Also:
- Constant Field Values
 
 - 
ERROR_NO_CHARSETpublic static final java.lang.String ERROR_NO_CHARSET - See Also:
- Constant Field Values
 
 
- 
 - 
Method Detail- 
errorOccurredpublic void errorOccurred(java.lang.Object source, java.sql.SQLException ex)Description copied from interface:ExceptionListenerNotify about a SQLException- Specified by:
- errorOccurredin interface- ExceptionListener
- Parameters:
- source- The source of the event; note for caller: this should be the object this listener is registered at.
- ex- error that occurred.
 
 - 
getGDSHelperpublic 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
 
 - 
getDatabasepublic java.lang.String getDatabase() 
 - 
isManagedEnvironmentpublic boolean isManagedEnvironment() 
 - 
inTransactionpublic boolean inTransaction() 
 - 
setManagedEnvironmentpublic void setManagedEnvironment(boolean managedEnvironment) throws javax.resource.ResourceException- Throws:
- javax.resource.ResourceException
 
 - 
isConnectionSharingpublic 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.
 
 - 
setConnectionSharingpublic 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
 
 - 
getLocalTransactionpublic 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 interface- javax.resource.spi.ManagedConnection
- Returns:
- LocalTransaction instance
- Throws:
- javax.resource.ResourceException- generic exception if operation fails
- javax.resource.NotSupportedException- if the operation is not supported
- javax.resource.spi.ResourceAdapterInternalException- resource adapter internal error condition
 
 - 
getMetaDatapublic 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 interface- javax.resource.spi.ManagedConnection
- Returns:
- ManagedConnectionMetaData instance
- Throws:
- javax.resource.ResourceException- generic exception if operation fails
- javax.resource.NotSupportedException- if the operation is not supported
 
 - 
setLogWriterpublic 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 interface- javax.resource.spi.ManagedConnection
- Parameters:
- out- Character Output stream to be associated
- Throws:
- javax.resource.ResourceException- generic exception if operation fails
- javax.resource.spi.ResourceAdapterInternalException- resource adapter related error condition
 
 - 
getLogWriterpublic 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 interface- javax.resource.spi.ManagedConnection
- Returns:
- Character ourput stream associated with this
         ManagedConnection
- Throws:
- javax.resource.ResourceException- generic exception if operation fails
 
 - 
addConnectionEventListenerpublic void addConnectionEventListener(javax.resource.spi.ConnectionEventListener listener) Add anConnectionEventListenerlistener. The listener will be notified when aConnectionEventoccurs.- Specified by:
- addConnectionEventListenerin interface- javax.resource.spi.ManagedConnection
- Parameters:
- listener- The- ConnectionEventListenerto be added
 
 - 
removeConnectionEventListenerpublic void removeConnectionEventListener(javax.resource.spi.ConnectionEventListener listener) Remove aConnectionEventListnerfrom the listing of listeners that will be notified for aConnectionEvent.- Specified by:
- removeConnectionEventListenerin interface- javax.resource.spi.ManagedConnection
- Parameters:
- listener- The- ConnectionEventListenerto be removed
 
 - 
associateConnectionpublic 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 interface- javax.resource.spi.ManagedConnection
- Parameters:
- connection- Application-level connection handle
- Throws:
- javax.resource.ResourceException- Failed to associate the connection handle with this ManagedConnection instance
- javax.resource.spi.IllegalStateException- Illegal state for invoking this method
- javax.resource.spi.ResourceAdapterInternalException- Resource adapter internal error condition
 
 - 
cleanuppublic 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 interface- javax.resource.spi.ManagedConnection
- Throws:
- javax.resource.ResourceException- generic exception if operation fails
- javax.resource.spi.ResourceAdapterInternalException- resource adapter internal error condition
- javax.resource.spi.IllegalStateException- Illegal state for calling connection cleanup. Example - if a local transaction is in progress that doesn't allow connection cleanup
 
 - 
getConnectionpublic 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 interface- javax.resource.spi.ManagedConnection
- Parameters:
- subject- security context as JAAS subject
- cri- 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 fails
- javax.resource.spi.ResourceAdapterInternalException- resource adapter internal error condition
- javax.resource.spi.SecurityException- security related error condition
- javax.resource.spi.CommException- failed communication with EIS instance
- javax.resource.spi.EISSystemException- internal error condition in EIS instance - used if EIS instance is involved in setting state of- ManagedConnection
 
 - 
destroypublic 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 interface- javax.resource.spi.ManagedConnection
- Throws:
- javax.resource.ResourceException- generic exception if operation failed
- javax.resource.spi.IllegalStateException- illegal state for destroying connection
 
 - 
destroypublic void destroy(javax.resource.spi.ConnectionEvent connectionEvent) throws javax.resource.ResourceException- Throws:
- javax.resource.ResourceException
 
 - 
getXAResourcepublic javax.transaction.xa.XAResource getXAResource() Return an XA resource to the caller.In both javax.sql.XAConnectionandjavax.resource.spi.MangagedConnection.- Specified by:
- getXAResourcein interface- javax.resource.spi.ManagedConnection
- Returns:
- the XAResource
 
 - 
commitpublic void commit(javax.transaction.xa.Xid id, boolean onePhase) throws javax.transaction.xa.XAExceptionCommits a transaction.- Specified by:
- commitin interface- javax.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.
 
 - 
endpublic void end(javax.transaction.xa.Xid id, int flags) throws javax.transaction.xa.XAExceptionDissociates a resource from a global transaction.- Specified by:
- endin interface- javax.transaction.xa.XAResource
- Throws:
- javax.transaction.xa.XAException- Occurs when the state was not correct (end called twice), or the transaction ID is wrong.
 
 - 
forgetpublic 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 interface- javax.transaction.xa.XAResource
- Throws:
- javax.transaction.xa.XAException- Occurs when the state was not correct (end never called), or the transaction ID is wrong.
 
 - 
getTransactionTimeoutpublic int getTransactionTimeout() throws javax.transaction.xa.XAExceptionGets the transaction timeout.- Specified by:
- getTransactionTimeoutin interface- javax.transaction.xa.XAResource
- Throws:
- javax.transaction.xa.XAException
 
 - 
isSameRMpublic 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 interface- javax.transaction.xa.XAResource
- Parameters:
- res- The other- XAResourceto compare to
- Returns:
- trueif- resuses the same ResourceManager,- falseotherwise
- Throws:
- javax.transaction.xa.XAException
 
 - 
preparepublic int prepare(javax.transaction.xa.Xid xid) throws javax.transaction.xa.XAExceptionPrepares a transaction to commit.- Specified by:
- preparein interface- javax.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.
 
 - 
recoverpublic 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 interface- javax.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.
 
 - 
findSingleXidprotected 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.
 
 - 
getSynchronizationObjectpublic final java.lang.Object getSynchronizationObject() Description copied from interface:SynchronizableGet synchronization object.- Specified by:
- getSynchronizationObjectin interface- Synchronizable
- Returns:
- object, cannot be null.
 
 - 
rollbackpublic 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 interface- javax.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.
 
 - 
setTransactionTimeoutpublic 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 interface- javax.transaction.xa.XAResource
- Parameters:
- timeout- The timeout to be set in seconds
- Throws:
- javax.transaction.xa.XAException
 
 - 
inDistributedTransactionpublic boolean inDistributedTransaction() 
 - 
startpublic 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 interface- javax.transaction.xa.XAResource
- Parameters:
- id- A global transaction identifier to be associated with the resource
- flags- 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.
 
 - 
internalStartpublic 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 resource
- flags- 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 transaction
- java.sql.SQLException
- See Also:
- start(Xid, int)
 
 - 
closepublic void close(FBConnection c) Close this connection with regards to a wrappingAbstractConnection.- Parameters:
- c- The- AbstractConnectionthat is being closed
 
 - 
getConnectionRequestInfopublic FBConnectionRequestInfo getConnectionRequestInfo() Get information about the current connection parameters.- Returns:
- instance of FBConnectionRequestInfo.
 
 - 
getTransactionParameterspublic TransactionParameterBuffer getTransactionParameters() 
 - 
setTransactionParameterspublic void setTransactionParameters(TransactionParameterBuffer transactionParameters) 
 - 
getTransactionParameterspublic TransactionParameterBuffer getTransactionParameters(int isolation) 
 - 
setTransactionParameterspublic void setTransactionParameters(int isolation, TransactionParameterBuffer transactionParams) throws javax.resource.ResourceException- Throws:
- javax.resource.ResourceException
 
 - 
getTransactionIsolationpublic 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)
 
 - 
setTransactionIsolationpublic 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 in- Connection.
- Throws:
- javax.resource.ResourceException- If the transaction level cannot be retrieved
- See Also:
- Connection,- getTransactionIsolation()
 
 - 
getManagedConnectionFactorypublic javax.resource.spi.ManagedConnectionFactory getManagedConnectionFactory() Get the managed connection factory that created this managed connection.- Returns:
- instance of ManagedConnectionFactory.
 
 - 
setReadOnlypublic 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
 
 - 
isReadOnlypublic boolean isReadOnly() Retrieve whether this connection is readonly.- Returns:
- trueif this connection is readonly,- falseotherwise
 
 
- 
 
-