Package org.firebirdsql.jca

Class FBManagedConnection

java.lang.Object
org.firebirdsql.jca.FBManagedConnection
All Implemented Interfaces:
javax.resource.spi.ManagedConnection, XAResource, ExceptionListener, Synchronizable
public class FBManagedConnection extends Object implements javax.resource.spi.ManagedConnection, XAResource, ExceptionListener, Synchronizable
The class FBManagedConnection implements both the ManagedConnection and XAResource interfaces.
Version:
1.0
Author:
David Jencks, Mark Rotteveel

  • Field Details

  • Method Details

    • errorOccurred

      public void errorOccurred(Object source, SQLException ex)
      Description copied from interface: ExceptionListener
      Notify about a SQLException
      Specified by:
      errorOccurred in 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.

    • getGDSHelper

      public GDSHelper getGDSHelper() throws SQLException
      Get instance of GDSHelper connected with this managed connection.
      Returns:
      instance of GDSHelper.
      Throws:
      SQLException - If this connection has no GDSHelper

    • getDatabase

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

    • setConnectionSharing

      public void setConnectionSharing(boolean connectionSharing) throws javax.resource.ResourceException
      Enable or disable connection sharing. See isConnectionSharing() method for details.
      Parameters:
      connectionSharing - true if connection sharing must be enabled.
      Throws:
      javax.resource.ResourceException - If connection sharing state cannot be changed

    • getLocalTransaction

      public javax.resource.spi.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.
      Specified by:
      getLocalTransaction in 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

    • getMetaData

      public javax.resource.spi.ManagedConnectionMetaData getMetaData() throws javax.resource.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.
      Specified by:
      getMetaData in 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

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

      Specified by:
      setLogWriter in 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

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

      Specified by:
      getLogWriter in interface javax.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 an ConnectionEventListener listener. The listener will be notified when a ConnectionEvent occurs.
      Specified by:
      addConnectionEventListener in interface javax.resource.spi.ManagedConnection
      Parameters:
      listener - The ConnectionEventListener to be added

    • removeConnectionEventListener

      public void removeConnectionEventListener(javax.resource.spi.ConnectionEventListener listener)
      Remove a ConnectionEventListner from the listing of listeners that will be notified for a ConnectionEvent.
      Specified by:
      removeConnectionEventListener in interface javax.resource.spi.ManagedConnection
      Parameters:
      listener - The ConnectionEventListener to be removed

    • associateConnection

      public void associateConnection(Object connection) throws javax.resource.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.

      Specified by:
      associateConnection in 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

    • cleanup

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

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

      Specified by:
      cleanup in 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

    • getConnection

      public Object getConnection(Subject subject, javax.resource.spi.ConnectionRequestInfo cri) throws javax.resource.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.

      Specified by:
      getConnection in interface javax.resource.spi.ManagedConnection
      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.
      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

    • destroy

      public void destroy() throws javax.resource.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.destroy()to destroy a physical connection. A resource adapter should destroy all allocated system resources for this ManagedConnection instance when the method destroy is called.
      Specified by:
      destroy in interface javax.resource.spi.ManagedConnection
      Throws:
      javax.resource.ResourceException - generic exception if operation failed
      javax.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 XAResource getXAResource()
      Return an XA resource to the caller.

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

      Specified by:
      getXAResource in interface javax.resource.spi.ManagedConnection
      Returns:
      the XAResource

    • commit

      public void commit(Xid id, boolean onePhase) throws XAException
      Commits a transaction.
      Specified by:
      commit in interface XAResource
      Throws:
      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(Xid id, int flags) throws XAException
      Dissociates a resource from a global transaction.
      Specified by:
      end in interface XAResource
      Throws:
      XAException - Occurs when the state was not correct (end called twice), or the transaction ID is wrong.

    • forget

      public void forget(Xid id) throws 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.
      Specified by:
      forget in interface XAResource
      Throws:
      XAException - Occurs when the state was not correct (end never called), or the transaction ID is wrong.

    • getTransactionTimeout

      public int getTransactionTimeout() throws XAException
      Gets the transaction timeout.
      Specified by:
      getTransactionTimeout in interface XAResource
      Throws:
      XAException

    • isSameRM

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

    • prepare

      public int prepare(Xid xid) throws XAException
      Prepares a transaction to commit.
      Specified by:
      prepare in interface XAResource
      Throws:
      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 Xid[] recover(int flags) throws 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 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:
      XAException - An error has occurred. Possible values are XAER_RMERR, XAER_RMFAIL, XAER_INVAL, and XAER_PROTO.

    • findSingleXid

      protected Xid findSingleXid(Xid externalXid) throws XAException
      Obtain 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:
      XAException - An error has occurred. Possible values are XAER_RMERR, XAER_RMFAIL, XAER_INVAL, and XAER_PROTO.

    • getSynchronizationObject

      public final Object getSynchronizationObject()
      Description copied from interface: Synchronizable
      Get synchronization object.
      Specified by:
      getSynchronizationObject in interface Synchronizable
      Returns:
      object, cannot be null.

    • rollback

      public void rollback(Xid xid) throws XAException
      Rolls back the work, assuming it was done on behalf of the specified transaction.
      Specified by:
      rollback in interface XAResource
      Throws:
      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 XAException
      Sets the transaction timeout. This is saved, but the value is not used by the current implementation.
      Specified by:
      setTransactionTimeout in interface XAResource
      Parameters:
      timeout - The timeout to be set in seconds
      Throws:
      XAException

    • inDistributedTransaction

      public boolean inDistributedTransaction()

    • 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).
      Specified by:
      start in interface XAResource
      Parameters:
      id - A global transaction identifier to be associated with the resource
      flags - One of TMNOFLAGS, TMJOIN, or TMRESUME
      Throws:
      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(Xid id, int flags) throws XAException, SQLException
      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
      Throws:
      XAException - If the transaction is already started, or this connection cannot participate in the distributed transaction
      SQLException
      See Also:

    • close

      public void close(FBConnection c)
      Close this connection with regards to a wrapping AbstractConnection.
      Parameters:
      c - The AbstractConnection that 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.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 Connection.
      Throws:
      javax.resource.ResourceException - If the transaction level cannot be retrieved
      See Also:

    • setTransactionIsolation

      public void setTransactionIsolation(int isolation) throws javax.resource.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 Connection.
      Throws:
      javax.resource.ResourceException - If the transaction level cannot be retrieved
      See Also:

    • 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 - If true, the connection will be set read-only, otherwise it will be writable

    • isReadOnly

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