Package org.firebirdsql.jca

Class 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 class FBManagedConnection implements 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.String ERROR_NO_CHARSET  
      static java.lang.String WARNING_NO_CHARSET  

      • Fields inherited from interface javax.transaction.xa.XAResource

        TMENDRSCAN, TMFAIL, TMJOIN, TMNOFLAGS, TMONEPHASE, TMRESUME, TMSTARTRSCAN, TMSUCCESS, TMSUSPEND, XA_OK, XA_RDONLY

    • Method Summary

      All Methods Instance Methods Concrete Methods 
      Modifier and Type Method Description
      void addConnectionEventListener​(javax.resource.spi.ConnectionEventListener listener)
      Add an ConnectionEventListener listener.
      void associateConnection​(java.lang.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​(FBConnection c)
      Close this connection with regards to a wrapping AbstractConnection.
      void commit​(javax.transaction.xa.Xid id, boolean onePhase)
      Commits a transaction.
      void destroy()
      Destroys the physical connection to the underlying resource manager.
      void destroy​(javax.resource.spi.ConnectionEvent connectionEvent)  
      void end​(javax.transaction.xa.Xid id, int flags)
      Dissociates a resource from a global transaction.
      void errorOccurred​(java.lang.Object source, java.sql.SQLException ex)
      Notify about a SQLException
      protected javax.transaction.xa.Xid findSingleXid​(javax.transaction.xa.Xid externalXid)
      Obtain a single prepared transaction branch from a resource manager, based on a Xid
      void forget​(javax.transaction.xa.Xid id)
      Indicates that no further action will be taken on behalf of this transaction (after a heuristic failure).
      java.lang.Object getConnection​(javax.security.auth.Subject subject, javax.resource.spi.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.
      java.lang.String getDatabase()  
      GDSHelper getGDSHelper()
      Get instance of GDSHelper connected with this managed connection.
      javax.resource.spi.LocalTransaction getLocalTransaction()
      Returns a javax.resource.spi.LocalTransaction instance.
      java.io.PrintWriter getLogWriter()
      Gets the log writer for this ManagedConnection instance.
      javax.resource.spi.ManagedConnectionFactory getManagedConnectionFactory()
      Get the managed connection factory that created this managed connection.
      javax.resource.spi.ManagedConnectionMetaData getMetaData()
      Gets the metadata information for this connection's underlying EIS resource manager instance.
      java.lang.Object getSynchronizationObject()
      Get synchronization object.
      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 inDistributedTransaction()  
      void internalStart​(javax.transaction.xa.Xid id, int flags)
      Perform the internal processing to start associate a JDBC connection with a global transaction.
      boolean inTransaction()  
      boolean isConnectionSharing()
      Check if connection sharing is enabled.
      boolean isManagedEnvironment()  
      boolean isReadOnly()
      Retrieve whether this connection is readonly.
      boolean isSameRM​(javax.transaction.xa.XAResource res)
      Retrieve whether this FBManagedConnection uses the same ResourceManager as res.
      int prepare​(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.
      void removeConnectionEventListener​(javax.resource.spi.ConnectionEventListener listener)
      Remove a ConnectionEventListner from the listing of listeners that will be notified for a ConnectionEvent.
      void rollback​(javax.transaction.xa.Xid xid)
      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​(java.io.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​(javax.transaction.xa.Xid id, int flags)
      Associates a JDBC connection with a global transaction.

      • Methods inherited from class java.lang.Object

        clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

    • 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: 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 java.sql.SQLException
        Get instance of GDSHelper connected 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 (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​(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:
        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 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. 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​(java.lang.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 java.lang.Object getConnection​(javax.security.auth.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 javax.transaction.xa.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​(javax.transaction.xa.Xid id,
                   boolean onePhase)
            throws javax.transaction.xa.XAException
        Commits a transaction.
        Specified by:
        commit in 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.

      • end

        public void end​(javax.transaction.xa.Xid id,
                int flags)
         throws javax.transaction.xa.XAException
        Dissociates a resource from a global transaction.
        Specified by:
        end in 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.

      • forget

        public void forget​(javax.transaction.xa.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.
        Specified by:
        forget in 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.

      • getTransactionTimeout

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

      • isSameRM

        public boolean isSameRM​(javax.transaction.xa.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.
        Specified by:
        isSameRM in interface javax.transaction.xa.XAResource
        Parameters:
        res - The other XAResource to compare to
        Returns:
        true if res uses the same ResourceManager, false otherwise
        Throws:
        javax.transaction.xa.XAException

      • prepare

        public int prepare​(javax.transaction.xa.Xid xid)
            throws javax.transaction.xa.XAException
        Prepares a transaction to commit.
        Specified by:
        prepare in 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.

      • recover

        public javax.transaction.xa.Xid[] recover​(int flags)
                                   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.
        Specified by:
        recover in 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.

      • findSingleXid

        protected javax.transaction.xa.Xid findSingleXid​(javax.transaction.xa.Xid externalXid)
                                          throws javax.transaction.xa.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:
        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: Synchronizable
        Get synchronization object.
        Specified by:
        getSynchronizationObject in interface Synchronizable
        Returns:
        object, cannot be null.

      • rollback

        public void rollback​(javax.transaction.xa.Xid xid)
              throws javax.transaction.xa.XAException
        Rolls back the work, assuming it was done on behalf of the specified transaction.
        Specified by:
        rollback in 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.

      • 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.
        Specified by:
        setTransactionTimeout in interface javax.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.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 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.

      • internalStart

        public void internalStart​(javax.transaction.xa.Xid id,
                          int flags)
                   throws javax.transaction.xa.XAException,
                          java.sql.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:
        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)

      • close

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

      • 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:
        Connection, setTransactionIsolation(int)

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