Package org.firebirdsql.jaybird.xca

## Class FBManagedConnectionFactory

- java.lang.Object
- - org.firebirdsql.jaybird.xca.FBManagedConnectionFactory

- All Implemented Interfaces:
    `java.io.Serializable`, `AttachmentProperties`, `BaseProperties`, `DatabaseConnectionProperties`, `FirebirdConnectionProperties`

      public final class FBManagedConnectionFactory
      extends java.lang.Object
      implements FirebirdConnectionProperties, java.io.Serializable

  FBManagedConnectionFactory is a factory for `FBManagedConnection`, and implements many of the internal functions of FBManagedConnection. This behavior is required due to firebird requiring all work done in a transaction to be done over one connection.

  To support xa semantics, the correct db handle must be located whenever a managed connection is associated with a xid.

  Author:
    David Jencks , Mark Rotteveel
  See Also:
    Serialized Form

- - ### Constructor Summary

    Constructors
    Constructor | Description
    --- | ---
    `FBManagedConnectionFactory()` | Create a new pure-Java FBManagedConnectionFactory.
    `FBManagedConnectionFactory​(boolean shared)` | Create a new pure-Java FBManagedConnectionFactory.
    `FBManagedConnectionFactory​(boolean shared, GDSType gdsType)` | Create a new FBManagedConnectionFactory based on the given GDSType.
    `FBManagedConnectionFactory​(boolean shared, GDSType gdsType, FBConnectionProperties connectionProperties)` | Create a new FBManagedConnectionFactory based on the given GDSType and connection properties.
    `FBManagedConnectionFactory​(GDSType gdsType)` | Create a new FBManagedConnectionFactory based on the given GDSType.
    `FBManagedConnectionFactory​(GDSType gdsType, FBConnectionProperties connectionProperties)` | Create a new FBManagedConnectionFactory based on the given GDSType and connection properties.

  - ### Method Summary

    All Methods Instance Methods Concrete Methods
    Modifier and Type | Method | Description
    --- | --- | ---
    `FBManagedConnectionFactory` | `canonicalize()` | The `canonicalize` method is used in FBDriver to reuse previous fbmcf instances if they have been created.
    `java.util.Map<ConnectionProperty,​java.lang.Object>` | `connectionPropertyValues()` | An unmodifiable view on the connection properties held by this BaseProperties implementation.
    `javax.sql.DataSource` | `createConnectionFactory()` | Creates a `javax.sql.DataSource` instance.
    `javax.sql.DataSource` | `createConnectionFactory​(XcaConnectionManager connectionManager)` | Creates a `javax.sql.DataSource` instance.
    `FBManagedConnection` | `createManagedConnection()` | Creates a new physical connection to the Firebird database using the default configuration.
    `FBManagedConnection` | `createManagedConnection​(FBConnectionRequestInfo connectionRequestInfo)` | Creates a new physical connection to the Firebird database.
    `boolean` | `equals​(java.lang.Object other)` |
    `void` | `forget​(FBManagedConnection mc, javax.transaction.xa.Xid xid)` |
    `java.lang.Boolean` | `getBooleanProperty​(java.lang.String name)` | Retrieves a `boolean` property value by name.
    `FBConnectionProperties` | `getCacheKey()` |
    `FbDatabaseFactory` | `getDatabaseFactory()` |
    `FBConnectionRequestInfo` | `getDefaultConnectionRequestInfo()` |
    `FBTpb` | `getDefaultTpb()` |
    `GDSType` | `getGDSType()` | Get the GDS implementation type around which this factory is based.
    `java.lang.Integer` | `getIntProperty​(java.lang.String name)` | Retrieves an `int` property value by name.
    `java.lang.String` | `getProperty​(java.lang.String name)` | Retrieves a string property value by name.
    `boolean` | `getShared()` |
    `FBTpb` | `getTpb​(int isolation)` |
    `TransactionParameterBuffer` | `getTransactionParameters​(int isolation)` | Get the transaction parameter buffer corresponding to the current connection request information.
    `int` | `hashCode()` |
    `void` | `recover​(FBManagedConnection mc, javax.transaction.xa.Xid xid)` |
    `void` | `setBooleanProperty​(java.lang.String name, java.lang.Boolean value)` | Sets a `boolean` property by name.
    `void` | `setDefaultConnectionManager​(XcaConnectionManager defaultCm)` |
    `void` | `setIntProperty​(java.lang.String name, java.lang.Integer value)` | Sets an `int` property by name.
    `void` | `setNonStandardProperty​(java.lang.String propertyMapping)` | Set the property that does not have corresponding setter method.
    `void` | `setProperty​(java.lang.String name, java.lang.String value)` | Sets a property by name.
    `void` | `setTransactionParameters​(int isolation, TransactionParameterBuffer tpb)` | Set transaction parameters for the specified transaction isolation level.

    - ### Methods inherited from class java.lang.Object

      `clone, finalize, getClass, notify, notifyAll, toString, wait, wait, wait`

    - ### Methods inherited from interface org.firebirdsql.jaybird.props.AttachmentProperties

      `getAuthPlugins, getCharSet, getConnectTimeout, getDbCryptConfig, getEncoding, getPassword, getPortNumber, getProcessId, getProcessName, getRoleName, getServerName, getSocketBufferSize, getSoTimeout, getType, getUser, getWireCrypt, isWireCompression, setAuthPlugins, setCharSet, setConnectTimeout, setDbCryptConfig, setEncoding, setPassword, setPortNumber, setProcessId, setProcessName, setRoleName, setServerName, setSocketBufferSize, setSoTimeout, setType, setUser, setWireCompression, setWireCrypt`

    - ### Methods inherited from interface org.firebirdsql.jaybird.props.BaseProperties

      `getBooleanProperty, getIntProperty, getProperty`

    - ### Methods inherited from interface org.firebirdsql.jaybird.props.DatabaseConnectionProperties

      `getBlobBufferSize, getDatabaseName, getDataTypeBind, getDecfloatRound, getDecfloatTraps, getDefaultIsolation, getDefaultTransactionIsolation, getGeneratedKeysEnabled, getPageCacheSize, getScrollableCursor, getServerBatchBufferSize, getSessionTimeZone, getSqlDialect, getTpbMapping, isColumnLabelForName, isDefaultResultSetHoldable, isIgnoreProcedureType, isTimestampUsesLocalTimezone, isUseFirebirdAutocommit, isUseServerBatch, isUseStreamBlobs, setBlobBufferSize, setColumnLabelForName, setDatabaseName, setDataTypeBind, setDecfloatRound, setDecfloatTraps, setDefaultIsolation, setDefaultResultSetHoldable, setDefaultTransactionIsolation, setGeneratedKeysEnabled, setIgnoreProcedureType, setPageCacheSize, setScrollableCursor, setServerBatchBufferSize, setSessionTimeZone, setSqlDialect, setTimestampUsesLocalTimezone, setTpbMapping, setUseFirebirdAutocommit, setUseServerBatch, setUseStreamBlobs`

    - ### Methods inherited from interface org.firebirdsql.jdbc.FirebirdConnectionProperties

      `getBuffersNumber, getDatabase, getNonStandardProperty, getUserName, setBuffersNumber, setDatabase, setNonStandardProperty, setUserName`

- - ### Constructor Detail

    - #### FBManagedConnectionFactory

          public FBManagedConnectionFactory()

      Create a new pure-Java FBManagedConnectionFactory.

      This managed connection factory can be shared.

    - #### FBManagedConnectionFactory

          public FBManagedConnectionFactory​(boolean shared)

      Create a new pure-Java FBManagedConnectionFactory.
      Parameters:
        `shared` - Indicates that this Managed Connection Factory can be shared or not. When `true` configuration changes are not allowed after the first connection or datasource has been created to ensure all shared users have the same expectation of configuration.

    - #### FBManagedConnectionFactory

          public FBManagedConnectionFactory​(GDSType gdsType)

      Create a new FBManagedConnectionFactory based on the given GDSType.

      This managed connection factory can be shared.

      Parameters:
        `gdsType` - The GDS implementation to use

    - #### FBManagedConnectionFactory

          public FBManagedConnectionFactory​(boolean shared,
                                            GDSType gdsType)

      Create a new FBManagedConnectionFactory based on the given GDSType.
      Parameters:
        `shared` - Indicates that this Managed Connection Factory can be shared or not. When `true` configuration changes are not allowed after the first connection or datasource has been created to ensure all shared users have the same expectation of configuration.
        `gdsType` - The GDS implementation to use

    - #### FBManagedConnectionFactory

          public FBManagedConnectionFactory​(GDSType gdsType,
                                            FBConnectionProperties connectionProperties)

      Create a new FBManagedConnectionFactory based on the given GDSType and connection properties.

      This managed connection factory can be shared.

      Parameters:
        `gdsType` - The GDS implementation to use
        `connectionProperties` - Initial connection properties (will be copied), use of `null` is allowed

    - #### FBManagedConnectionFactory

          public FBManagedConnectionFactory​(boolean shared,
                                            GDSType gdsType,
                                            FBConnectionProperties connectionProperties)

      Create a new FBManagedConnectionFactory based on the given GDSType and connection properties.
      Parameters:
        `shared` - Indicates that this Managed Connection Factory can be shared or not. When `true` configuration changes are not allowed after the first connection or datasource has been created to ensure all shared users have the same expectation of configuration.
        `gdsType` - The GDS implementation to use
        `connectionProperties` - Initial connection properties (will be copied), use of `null` is allowed

  - ### Method Detail

    - #### getDatabaseFactory

          public FbDatabaseFactory getDatabaseFactory()

    - #### getGDSType

          public GDSType getGDSType()

      Get the GDS implementation type around which this factory is based.
      Returns:
        The GDS implementation type

    - #### getShared

          public boolean getShared()

      Returns:
        `true` if this instance can be safely shared (modification disallowed after creation of first connection/data source)

    - #### getTransactionParameters

          public TransactionParameterBuffer getTransactionParameters​(int isolation)

      Description copied from interface: `FirebirdConnectionProperties`
      Get the transaction parameter buffer corresponding to the current connection request information.
      Specified by:
        `getTransactionParameters` in interface `FirebirdConnectionProperties`
      Parameters:
        `isolation` - transaction isolation level for which TPB should be returned.
      Returns:
        instance of `TransactionParameterBuffer`.

    - #### setNonStandardProperty

          public void setNonStandardProperty​(java.lang.String propertyMapping)

      Description copied from interface: `FirebirdConnectionProperties`
      Set the property that does not have corresponding setter method.
      Specified by:
        `setNonStandardProperty` in interface `FirebirdConnectionProperties`
      Parameters:
        `propertyMapping` - parameter value in the `propertyName[=propertyValue]` form, this allows setting non-standard parameters using configuration files.

    - #### setTransactionParameters

          public void setTransactionParameters​(int isolation,
                                               TransactionParameterBuffer tpb)

      Description copied from interface: `FirebirdConnectionProperties`
      Set transaction parameters for the specified transaction isolation level. The specified TPB is used as a default mapping for the specified isolation level.
      Specified by:
        `setTransactionParameters` in interface `FirebirdConnectionProperties`
      Parameters:
        `isolation` - transaction isolation level.
        `tpb` - instance of `TransactionParameterBuffer` containing transaction parameters.

    - #### setDefaultConnectionManager

          public void setDefaultConnectionManager​(XcaConnectionManager defaultCm)

    - #### getProperty

          public java.lang.String getProperty​(java.lang.String name)

      Description copied from interface: `BaseProperties`
      Retrieves a string property value by name.

      For properties with an explicit default, this method should return the string presentation of that default, not `null`. For `int` or `boolean` the string equivalent is returned.

      Specified by:
        `getProperty` in interface `BaseProperties`
      Parameters:
        `name` - Property name (not `null` or empty)
      Returns:
        Value of the property, or `null` when not set or not a known property

    - #### setProperty

          public void setProperty​(java.lang.String name,
                                  java.lang.String value)

      Description copied from interface: `BaseProperties`
      Sets a property by name.

      This method can be used to set all defined properties, but also properties not known by Jaybird. When setting `int` or `boolean` properties, the appropriate conversions are applied. Using `null` will reset to the default value. For `boolean` properties, an empty string is taken to mean `true`.

      Specified by:
        `setProperty` in interface `BaseProperties`
      Parameters:
        `name` - Property name (not `null` or empty)
        `value` - Property value (use `null` to apply default)

    - #### getIntProperty

          public java.lang.Integer getIntProperty​(java.lang.String name)

      Description copied from interface: `BaseProperties`
      Retrieves an `int` property value by name.

      For properties with an explicit default, this method should return the integer presentation of that default. For implementation simplicity, it is allowed to convert any string property to `int` instead of checking if something is actually an `int` property

      Specified by:
        `getIntProperty` in interface `BaseProperties`
      Parameters:
        `name` - Property name (not `null` or empty)
      Returns:
        Integer with value of the property, or `null` when not set

    - #### setIntProperty

          public void setIntProperty​(java.lang.String name,
                                     java.lang.Integer value)

      Description copied from interface: `BaseProperties`
      Sets an `int` property by name.

      For implementation simplicity, it is allowed to also set string properties. The value set will be the string equivalent.

      Specified by:
        `setIntProperty` in interface `BaseProperties`
      Parameters:
        `name` - Property name (not `null` or empty)
        `value` - Property value (use `null` to apply default)

    - #### getBooleanProperty

          public java.lang.Boolean getBooleanProperty​(java.lang.String name)

      Description copied from interface: `BaseProperties`
      Retrieves a `boolean` property value by name.

      For properties with an explicit default, this method should return the boolean presentation of that default. For implementation simplicity, it is allowed to convert any string property to `boolean` instead of checking if something is actually an `int` property

      Specified by:
        `getBooleanProperty` in interface `BaseProperties`
      Parameters:
        `name` - Property name (not `null` or empty)
      Returns:
        Integer with value of the property, or `null` when not set

    - #### setBooleanProperty

          public void setBooleanProperty​(java.lang.String name,
                                         java.lang.Boolean value)

      Description copied from interface: `BaseProperties`
      Sets a `boolean` property by name.

      For implementation simplicity, it is allowed to also set string properties. The value set will be the string equivalent.

      Specified by:
        `setBooleanProperty` in interface `BaseProperties`
      Parameters:
        `name` - Property name (not `null` or empty)
        `value` - Property value (use `null` to apply default)

    - #### connectionPropertyValues

          public java.util.Map<ConnectionProperty,​java.lang.Object> connectionPropertyValues()

      Description copied from interface: `BaseProperties`
      An unmodifiable view on the connection properties held by this BaseProperties implementation.

      Be aware, implementations can have additional properties that are not mapped from `ConnectionProperty`. Such properties will need to be retrieved in an implementation-specific manner.

      Specified by:
        `connectionPropertyValues` in interface `BaseProperties`
      Returns:
        An unmodifiable view on the property values held in this properties instance

    - #### hashCode

          public int hashCode()

      Overrides:
        `hashCode` in class `java.lang.Object`

    - #### equals

          public boolean equals​(java.lang.Object other)

      Overrides:
        `equals` in class `java.lang.Object`

    - #### getDefaultConnectionRequestInfo

          public FBConnectionRequestInfo getDefaultConnectionRequestInfo()
                                                                  throws java.sql.SQLException

      Throws:
        `java.sql.SQLException`

    - #### getDefaultTpb

          public FBTpb getDefaultTpb()
                              throws java.sql.SQLException

      Throws:
        `java.sql.SQLException`

    - #### getTpb

          public FBTpb getTpb​(int isolation)
                       throws java.sql.SQLException

      Throws:
        `java.sql.SQLException`

    - #### createConnectionFactory

          public javax.sql.DataSource createConnectionFactory​(XcaConnectionManager connectionManager)

      Creates a `javax.sql.DataSource` instance. The data source instance gets initialized with the passed XcaConnectionManager.
      Parameters:
        `connectionManager` - Connection manager
      Returns:
        data source instance

    - #### createConnectionFactory

          public javax.sql.DataSource createConnectionFactory()

      Creates a `javax.sql.DataSource` instance. The data source instance gets initialized with a default XcaConnectionManager provided by the resource adapter.
      Returns:
        data source instance

    - #### createManagedConnection

          public FBManagedConnection createManagedConnection()
                                                      throws java.sql.SQLException

      Creates a new physical connection to the Firebird database using the default configuration.
      Returns:
        Managed connection instance
      Throws:
        `java.sql.SQLException` - generic exception
      See Also:
        `createManagedConnection(FBConnectionRequestInfo)`

    - #### createManagedConnection

          public FBManagedConnection createManagedConnection​(FBConnectionRequestInfo connectionRequestInfo)
                                                      throws java.sql.SQLException

      Creates a new physical connection to the Firebird database.

      ManagedConnectionFactory uses the additional ConnectionRequestInfo to create this new connection.

      Parameters:
        `connectionRequestInfo` - Additional resource adapter specific connection request information, can be `null` for default
      Returns:
        Managed connection instance
      Throws:
        `java.sql.SQLException` - generic exception
      See Also:
        `createManagedConnection()`

    - #### canonicalize

          public FBManagedConnectionFactory canonicalize()

      The `canonicalize` method is used in FBDriver to reuse previous fbmcf instances if they have been created. It should really be package access level
      Returns:
        a `FBManagedConnectionFactory` value

    - #### forget

          public void forget​(FBManagedConnection mc,
                             javax.transaction.xa.Xid xid)

    - #### recover

          public void recover​(FBManagedConnection mc,
                              javax.transaction.xa.Xid xid)

    - #### getCacheKey

          public FBConnectionProperties getCacheKey()