org.firebirdsql.jca

Class FBManagedConnectionFactory

Implemented Interfaces:
ManagedConnectionFactory, Serializable, FirebirdConnectionProperties

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

FBManagedConnectionFactory implements the jca ManagedConnectionFactory interface and also many of the internal functions of ManagedConnection. This nonstandard 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 ManagedConnection is associated with an xid. WARNING: this adapter will probably not work properly in an environment where ManagedConnectionFactory is serialized and deserialized, and the deserialized copy is expected to function as anything other than a key.
Author:
David Jencks

Constructor Summary

FBManagedConnectionFactory()
Create a new pure-Java FBManagedConnectionFactory.
FBManagedConnectionFactory(org.firebirdsql.gds.impl.GDSType gdsType)
Create a new FBManagedConnectionFactory based around the given GDSType.
FBManagedConnectionFactory(org.firebirdsql.gds.impl.GDSType gdsType, FBConnectionProperties connectionProperties)

Method Summary

FBManagedConnectionFactory
canonicalize()
The canonicalize method is used in FBDriver to reuse previous fbmcf instances if they have been create.
Object
createConnectionFactory()
The createConnectionFactory method creates a DataSource with a default stand alone ConnectionManager.
Object
createConnectionFactory(ConnectionManager cxManager)
The createConnectionFactory method creates a DataSource using the supplied ConnectionManager.
ManagedConnection
createManagedConnection(Subject subject, ConnectionRequestInfo cri)
Creates a new physical connection to the underlying EIS resource manager, ManagedConnectionFactory uses the security information (passed as Subject) and additional ConnectionRequestInfo (which is specific to ResourceAdapter and opaque to application server) to create this new connection.
boolean
equals(Object other)
void
forget(FBManagedConnection mc, Xid xid)
int
getBlobBufferLength()
Deprecated. use getBlobBufferSize()
int
getBlobBufferSize()
int
getBuffersNumber()
String
getCharSet()
String
getDatabase()
DatabaseParameterBuffer
getDatabaseParameterBuffer()
Get the database parameter buffer corresponding to the current connection request information.
FBConnectionRequestInfo
getDefaultConnectionRequestInfo()
String
getDefaultIsolation()
Get the default transaction isolation level as string.
FBTpb
getDefaultTpb()
int
getDefaultTransactionIsolation()
Get the default transaction isolation level.
String
getEncoding()
GDS
getGDS()
org.firebirdsql.gds.impl.GDSType
getGDSType()
Get the GDS implementation type around which this factory is based.
String
getLocalEncoding()
Deprecated. use getCharSet() instead.
PrintWriter
getLogWriter()
Get the log writer for this ManagedConnectionFactory instance.
String
getNonStandardProperty(String key)
Get the property that does not have corresponding getter method by its name.
String
getPassword()
String
getRoleName()
int
getSocketBufferSize()
String
getSqlDialect()
FBTpb
getTpb(int defaultTransactionIsolation)
String
getTpbMapping()
Get the used TPB mapping.
Integer
getTransactionIsolation()
Deprecated. use getDefaultTransactionIsolation()
String
getTransactionIsolationName()
Deprecated. use getDefaultIsolation()
TransactionParameterBuffer
getTransactionParameters(int isolation)
Get the transaction parameter buffer corresponding to the current connection request information.
String
getType()
String
getUseTranslation()
String
getUserName()
int
hashCode()
boolean
isDefaultResultSetHoldable()
boolean
isTimestampUsesLocalTimezone()
boolean
isUseStandardUdf()
boolean
isUseStreamBlobs()
ManagedConnection
matchManagedConnections(Set connectionSet, Subject subject, ConnectionRequestInfo cxRequestInfo)
Returns a matched connection from the candidate set of connections.
void
recover(FBManagedConnection mc, Xid xid)
void
setBlobBufferLength(int value)
Deprecated. use setBlobBufferSize(int)
void
setBlobBufferSize(int bufferSize)
void
setBuffersNumber(int buffersNumber)
void
setCharSet(String charSet)
void
setDatabase(String database)
void
setDefaultConnectionManager(ConnectionManager defaultCm)
void
setDefaultIsolation(String isolation)
Set the default transaction isolation level as string.
void
setDefaultResultSetHoldable(boolean isHoldable)
void
setDefaultTransactionIsolation(int defaultIsolationLevel)
Set the default transaction isolation level.
void
setEncoding(String encoding)
void
setLocalEncoding(String localEncoding)
Deprecated. use setCharSet(String) instead.
void
setLogWriter(PrintWriter out)
Set the log writer for this ManagedConnectionFactory instance.
void
setNonStandardProperty(String propertyMapping)
Set the property that does not have corresponding setter method.
void
setNonStandardProperty(String key, String value)
Set the property that does not have corresponding setter method.
void
setPassword(String password)
void
setRoleName(String roleName)
void
setSocketBufferSize(int socketBufferSize)
void
setSqlDialect(String sqlDialect)
void
setTimestampUsesLocalTimezone(boolean timestampUsesLocalTimezone)
void
setTpbMapping(String tpbMapping)
Set path to the properties file with the TPB mapping.
void
setTransactionIsolation(Integer value)
Deprecated. use setDefaultTransactionIsolation(int)
void
setTransactionIsolationName(String name)
Deprecated. use setDefaultIsolation(String)
void
setTransactionParameters(int isolation, TransactionParameterBuffer tpb)
Set transaction parameters for the specified transaction isolation level.
void
setType(String type)
void
setUseStandardUdf(boolean useStandardUdf)
void
setUseStreamBlobs(boolean useStreamBlobs)
void
setUseTranslation(String translationPath)
void
setUserName(String userName)

Constructor Details

FBManagedConnectionFactory

public FBManagedConnectionFactory()
Create a new pure-Java FBManagedConnectionFactory.

FBManagedConnectionFactory

public FBManagedConnectionFactory(org.firebirdsql.gds.impl.GDSType gdsType)
Create a new FBManagedConnectionFactory based around the given GDSType.
Parameters:
gdsType - The GDS implementation to use

FBManagedConnectionFactory

public FBManagedConnectionFactory(org.firebirdsql.gds.impl.GDSType gdsType,
                                  FBConnectionProperties connectionProperties)

Method Details

canonicalize

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

createConnectionFactory

public Object createConnectionFactory()
            throws ResourceException
The createConnectionFactory method creates a DataSource with a default stand alone ConnectionManager. Ours can implement pooling.
Returns:
a new javax.sql.DataSource based around this connection factory

createConnectionFactory

public Object createConnectionFactory(ConnectionManager cxManager)
            throws ResourceException
The createConnectionFactory method creates a DataSource using the supplied ConnectionManager.
Parameters:
cxManager - a ConnectionManager value
Returns:
a java.lang.Object value

createManagedConnection

public ManagedConnection createManagedConnection(Subject subject,
                                                 ConnectionRequestInfo cri)
            throws ResourceException
Creates a new physical connection to the underlying EIS resource manager, ManagedConnectionFactory uses the security information (passed as Subject) and additional ConnectionRequestInfo (which is specific to ResourceAdapter and opaque to application server) to create this new connection.
Parameters:
subject - Caller's security information
cri - Additional resource adapter specific connection request information
Returns:
ManagedConnection instance

equals

public boolean equals(Object other)

forget

public void forget(FBManagedConnection mc,
                   Xid xid)
            throws GDSException

getBlobBufferLength

public int getBlobBufferLength()

Deprecated. use getBlobBufferSize()


getBlobBufferSize

public int getBlobBufferSize()
Specified by:
getBlobBufferSize in interface FirebirdConnectionProperties
Returns:
BLOB buffer size in bytes.

getBuffersNumber

public int getBuffersNumber()
Specified by:
getBuffersNumber in interface FirebirdConnectionProperties
Returns:
number of cache buffers that should be allocated for this connection, should be specified for ClassicServer instances, SuperServer has a server-wide configuration parameter.

getCharSet

public String getCharSet()
Specified by:
getCharSet in interface FirebirdConnectionProperties
Returns:
Character set for the connection.

getDatabase

public String getDatabase()
Specified by:
getDatabase in interface FirebirdConnectionProperties
Returns:
path to the database including the server name and the port, if needed.

getDatabaseParameterBuffer

public DatabaseParameterBuffer getDatabaseParameterBuffer()
            throws SQLException
Get the database parameter buffer corresponding to the current connection request information.
Specified by:
getDatabaseParameterBuffer in interface FirebirdConnectionProperties
Returns:
instance of DatabaseParameterBuffer.

getDefaultConnectionRequestInfo

public FBConnectionRequestInfo getDefaultConnectionRequestInfo()
            throws ResourceException

getDefaultIsolation

public String getDefaultIsolation()
Specified by:
getDefaultIsolation in interface FirebirdConnectionProperties
Returns:
default transaction isolation as string.

getDefaultTpb

public FBTpb getDefaultTpb()
            throws ResourceException

getDefaultTransactionIsolation

public int getDefaultTransactionIsolation()
Get the default transaction isolation level. This is the transaction isolation level for the newly created connections.
Specified by:
getDefaultTransactionIsolation in interface FirebirdConnectionProperties
Returns:
default transaction isolation level.

getEncoding

public String getEncoding()
Specified by:
getEncoding in interface FirebirdConnectionProperties
Returns:
Character encoding for the connection.

getGDS

public GDS getGDS()

getGDSType

public org.firebirdsql.gds.impl.GDSType getGDSType()
Get the GDS implementation type around which this factory is based.
Returns:
The GDS implementation type

getLocalEncoding

public String getLocalEncoding()

Deprecated. use getCharSet() instead.


getLogWriter

public PrintWriter getLogWriter()
Get the log writer for this ManagedConnectionFactory instance. The log writer is a character output stream to which all logging and tracing messages for this ManagedConnectionFactory instance will be printed. ApplicationServer manages the association of output stream with the ManagedConnectionFactory. When a ManagedConnectionFactory object is created the log writer is initially null, in other words, logging is disabled.
Returns:
PrintWriter instance

getNonStandardProperty

public String getNonStandardProperty(String key)
Get the property that does not have corresponding getter method by its name.
Specified by:
getNonStandardProperty in interface FirebirdConnectionProperties
Parameters:
key - name of the property to get.
Returns:
value of the property.

getPassword

public String getPassword()
Specified by:
getPassword in interface FirebirdConnectionProperties
Returns:
password corresponding to the specified user name.

getRoleName

public String getRoleName()
Specified by:
getRoleName in interface FirebirdConnectionProperties
Returns:
SQL role to use.

getSocketBufferSize

public int getSocketBufferSize()
Specified by:
getSocketBufferSize in interface FirebirdConnectionProperties
Returns:
socket buffer size in bytes, or -1 is not specified.

getSqlDialect

public String getSqlDialect()
Specified by:
getSqlDialect in interface FirebirdConnectionProperties
Returns:
SQL dialect of the client.

getTpb

public FBTpb getTpb(int defaultTransactionIsolation)
            throws FBResourceException

getTpbMapping

public String getTpbMapping()
Get the used TPB mapping.
Specified by:
getTpbMapping in interface FirebirdConnectionProperties
Returns:
path to the TPB mapping.

getTransactionIsolation

public Integer getTransactionIsolation()

Deprecated. use getDefaultTransactionIsolation()


getTransactionIsolationName

public String getTransactionIsolationName()

Deprecated. use getDefaultIsolation()


getTransactionParameters

public TransactionParameterBuffer getTransactionParameters(int isolation)
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.

getType

public String getType()
Specified by:
getType in interface FirebirdConnectionProperties
Returns:
type of the connection, for example, "PURE_JAVA", "LOCAL", "EMBEDDED", depends on the GDS implementations installed in the system.

getUseTranslation

public String getUseTranslation()
Specified by:
getUseTranslation in interface FirebirdConnectionProperties
Returns:
path to the character translation table.

getUserName

public String getUserName()
Specified by:
getUserName in interface FirebirdConnectionProperties
Returns:
name of the user that will be used when connecting to the database.

hashCode

public int hashCode()

isDefaultResultSetHoldable

public boolean isDefaultResultSetHoldable()
Specified by:
isDefaultResultSetHoldable in interface FirebirdConnectionProperties

isTimestampUsesLocalTimezone

public boolean isTimestampUsesLocalTimezone()
Specified by:
isTimestampUsesLocalTimezone in interface FirebirdConnectionProperties
Returns:
true if the Jaybird 1.0 handling of the calendar in corresponding setters. This is also compatible with MySQL calendar treatment.

isUseStandardUdf

public boolean isUseStandardUdf()
Specified by:
isUseStandardUdf in interface FirebirdConnectionProperties
Returns:
true if driver should assume that standard UDF are installed.

isUseStreamBlobs

public boolean isUseStreamBlobs()
Specified by:
isUseStreamBlobs in interface FirebirdConnectionProperties
Returns:
true if stream blobs should be created, otherwise false.

matchManagedConnections

public ManagedConnection matchManagedConnections(Set connectionSet,
                                                 Subject subject,
                                                 ConnectionRequestInfo cxRequestInfo)
            throws ResourceException
Returns a matched connection from the candidate set of connections. ManagedConnectionFactory uses the security info (as in Subject) and information provided through ConnectionRequestInfo and additional Resource Adapter specific criteria to do matching. Note that criteria used for matching is specific to a resource adapter and is not prescribed by the Connector specification.

This method returns a ManagedConnection instance that is the best match for handling the connection allocation request.

Parameters:
connectionSet - candidate connection set
subject - caller's security information
cxRequestInfo - additional resource adapter specific connection request information
Returns:
ManagedConnection if resource adapter finds an acceptable match otherwise null

recover

public void recover(FBManagedConnection mc,
                    Xid xid)
            throws GDSException

setBlobBufferLength

public void setBlobBufferLength(int value)

Deprecated. use setBlobBufferSize(int)


setBlobBufferSize

public void setBlobBufferSize(int bufferSize)
Specified by:
setBlobBufferSize in interface FirebirdConnectionProperties
Parameters:
bufferSize - size of the BLOB buffer in bytes.

setBuffersNumber

public void setBuffersNumber(int buffersNumber)
Specified by:
setBuffersNumber in interface FirebirdConnectionProperties
Parameters:
buffersNumber - number of cache buffers that should be allocated for this connection, should be specified for ClassicServer instances, SuperServer has a server-wide configuration parameter.

setCharSet

public void setCharSet(String charSet)
Specified by:
setCharSet in interface FirebirdConnectionProperties
Parameters:
charSet - Character set for the connection. Similar to encoding property, but accepts Java names instead of Firebird ones.

setDatabase

public void setDatabase(String database)
Specified by:
setDatabase in interface FirebirdConnectionProperties
Parameters:
database - path to the database including the server name and the port, if needed.

setDefaultConnectionManager

public void setDefaultConnectionManager(ConnectionManager defaultCm)

setDefaultIsolation

public void setDefaultIsolation(String isolation)
Set the default transaction isolation level as string. This method is complementary to the FirebirdConnectionProperties.setDefaultTransactionIsolation(int), however it takes a string as parameter instead of a numeric constant.

Following strings are allowed:

  • "TRANSACTION_READ_COMMITTED" for a READ COMMITTED isolation level.
  • "TRANSACTION_REPEATABLE_READ" for a REPEATABLE READ isolation level.
  • "TRANSACTION_SERIALIZABLE" for a SERIALIZABLE isolation level.
Specified by:
setDefaultIsolation in interface FirebirdConnectionProperties
Parameters:
isolation - string constant representing a default isolation level.

setDefaultResultSetHoldable

public void setDefaultResultSetHoldable(boolean isHoldable)
Specified by:
setDefaultResultSetHoldable in interface FirebirdConnectionProperties

setDefaultTransactionIsolation

public void setDefaultTransactionIsolation(int defaultIsolationLevel)
Set the default transaction isolation level.
Specified by:
setDefaultTransactionIsolation in interface FirebirdConnectionProperties
Parameters:
defaultIsolationLevel - default transaction isolation level.

setEncoding

public void setEncoding(String encoding)
Specified by:
setEncoding in interface FirebirdConnectionProperties
Parameters:
encoding - Character encoding for the connection. See Firebird documentation for more information.

setLocalEncoding

public void setLocalEncoding(String localEncoding)

Deprecated. use setCharSet(String) instead.


setLogWriter

public void setLogWriter(PrintWriter out)
            throws ResourceException
Set the log writer for this ManagedConnectionFactory instance. The log writer is a character output stream to which all logging and tracing messages for this ManagedConnectionFactory instance will be printed. ApplicationServer manages the association of output stream with the ManagedConnectionFactory. When a ManagedConnectionFactory object is created the log writer is initially null, in other words, logging is disabled. Once a log writer is associated with a ManagedConnectionFactory, logging and tracing for ManagedConnectionFactory instance is enabled.

The ManagedConnection instances created by ManagedConnectionFactory "inherits" the log writer, which can be overridden by ApplicationServer using ManagedConnection.setLogWriterto set ManagedConnection specific logging and tracing.

Parameters:
out - an out stream for error logging and tracing

setNonStandardProperty

public void setNonStandardProperty(String propertyMapping)
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.

setNonStandardProperty

public void setNonStandardProperty(String key,
                                   String value)
Set the property that does not have corresponding setter method.
Specified by:
setNonStandardProperty in interface FirebirdConnectionProperties
Parameters:
key - name of the property to set.
value - value of the property.

setPassword

public void setPassword(String password)
Specified by:
setPassword in interface FirebirdConnectionProperties
Parameters:
password - password corresponding to the specified user name.

setRoleName

public void setRoleName(String roleName)
Specified by:
setRoleName in interface FirebirdConnectionProperties
Parameters:
roleName - SQL role to use.

setSocketBufferSize

public void setSocketBufferSize(int socketBufferSize)
Specified by:
setSocketBufferSize in interface FirebirdConnectionProperties
Parameters:
socketBufferSize - socket buffer size in bytes.

setSqlDialect

public void setSqlDialect(String sqlDialect)
Specified by:
setSqlDialect in interface FirebirdConnectionProperties
Parameters:
sqlDialect - SQL dialect of the client.

setTimestampUsesLocalTimezone

public void setTimestampUsesLocalTimezone(boolean timestampUsesLocalTimezone)
Specified by:
setTimestampUsesLocalTimezone in interface FirebirdConnectionProperties
Parameters:
timestampUsesLocalTimezone - true if the Jaybird 1.0 handling of the calendar in corresponding setters. This is also compatible with MySQL calendar treatment.

setTpbMapping

public void setTpbMapping(String tpbMapping)
Set path to the properties file with the TPB mapping. The path begins with the protocol specification followed by the path to the resource. A special protocol "res:" should be used to specify resource in the classpath.

For the compatibility reasons, if no protocol is specified, classpath is used by default.

Properties file contains a mapping between the transaction isolation level (name of the constant in the java.sql.Connection interface and a comma-separated list of TPB parameters.

Specified by:
setTpbMapping in interface FirebirdConnectionProperties
Parameters:
tpbMapping - path to the properties file.

setTransactionIsolation

public void setTransactionIsolation(Integer value)

Deprecated. use setDefaultTransactionIsolation(int)


setTransactionIsolationName

public void setTransactionIsolationName(String name)

Deprecated. use setDefaultIsolation(String)


setTransactionParameters

public void setTransactionParameters(int isolation,
                                     TransactionParameterBuffer tpb)
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.

setType

public void setType(String type)
Specified by:
setType in interface FirebirdConnectionProperties
Parameters:
type - type of the connection, for example, "PURE_JAVA", "LOCAL", "EMBEDDED", depends on the GDS implementations installed in the system.

setUseStandardUdf

public void setUseStandardUdf(boolean useStandardUdf)
Specified by:
setUseStandardUdf in interface FirebirdConnectionProperties
Parameters:
useStandardUdf - true if driver should assume that standard UDF are installed.

setUseStreamBlobs

public void setUseStreamBlobs(boolean useStreamBlobs)
Specified by:
setUseStreamBlobs in interface FirebirdConnectionProperties
Parameters:
useStreamBlobs - true if stream blobs should be created, otherwise false.

setUseTranslation

public void setUseTranslation(String translationPath)
Specified by:
setUseTranslation in interface FirebirdConnectionProperties
Parameters:
translationPath - path to the character translation table.

setUserName

public void setUserName(String userName)
Specified by:
setUserName in interface FirebirdConnectionProperties
Parameters:
userName - name of the user that will be used when connecting to the database.

Copyright B) 2001 David Jencks and other authors. All rights reserved.