com.atomikos.jms

Class AtomikosConnectionFactoryBean

java.lang.Object

com.atomikos.jms.AtomikosConnectionFactoryBean

All Implemented Interfaces:

ConnectionPoolProperties, Serializable, javax.jms.ConnectionFactory, Referenceable

public class AtomikosConnectionFactoryBean
extends Object
implements javax.jms.ConnectionFactory, ConnectionPoolProperties, Referenceable, Serializable

This class represents the Atomikos JMS 1.1 connection factory for JTA-enabled JMS. Use an instance of this class to make JMS participate in JTA transactions without having to issue the low-level XA calls yourself. The following use cases are supported:

JTA/XA-enabled JMS

This class can be used as a connection factory in JTA/XA use cases, in order to make the JTA transaction control the effects of JMS operations (as explained in http://www.atomikos.com/Publications/ReliableJmsWithTransactions). In order to use the JTA/XA mode, make sure that the following conditions hold:

1. The localTransactionMode is set to false (default), and
2. Sessions are created in transacted mode, i.e.:
   Transaction tx = ...; //start a JTA transaction
... AtomikosConnectionFactoryBean cf = ...; //create or retrieve a connection factory instance
...
Connection c = cf.createConnection();
Session s = c.createSession ( true , 0 ); //note the value of the transacted flag!
...//perform regular JMS sends or receives
...
tx.commit(); //commit JTA transaction to make all JMS operations take effect, or rollback to cancel everything


The advantage of this class over using a vendor-specific XAConnectionFactory is that this class takes care of all JTA/XA-related calls towards the driver underneath. In other words, it hides the complexities of JTA/XA at the driver level.

Local JMS transactions

This class can be used to demarcate transactions yourself, on the JMS session object (as opposed to using a JTA/XA transaction).
WARNING: as per JMS specification, this mode is only safe if you access no other back-end system like JDBC.
In order to enable this mode, make sure that the following conditions hold:

1. The localTransactionMode is set to true, and
2. Sessions are created in transacted mode, i.e.:
   AtomikosConnectionFactoryBean cf = ...; //create or retrieve a connection factory instance
...
Connection c = cf.createConnection();
Session s = c.createSession ( true , 0 ); //note the value of the transacted flag!
...//perform regular JMS sends or receives
...
s.commit();//commit on session to make all effects permanent, rollback to cancel

Note: this mode requires support from your JMS vendor's XAConnectionFactory implementation. Check your vendor documentation first!

Non-transacted JMS

This class can be used for sending and receiving in non-transacted mode, of localTransactionMode set to true.
WARNING: as per JMS specification, this mode gives hardly any guarantees in terms of consistency after failures.
To enable this mode, make sure to create the session as follows:
AtomikosConnectionFactoryBean cf = ...; //create or retrieve a connection factory instance
...
Connection c = cf.createConnection();
Session s = c.createSession ( false , ... ); //note the value of the transacted flag!
Note: this mode requires support from your JMS vendor's XAConnectionFactory implementation. Check your vendor documentation first!

See Also:

Serialized Form

Constructor Summary

Constructors

Constructor and Description
AtomikosConnectionFactoryBean()

Method Summary

Methods

Modifier and Type	Method and Description
void	close() Closes the instance.
javax.jms.Connection	createConnection()
javax.jms.Connection	createConnection(String user, String password)
int	getBorrowConnectionTimeout() Gets the timeout for borrowing connections from the pool.
int	getDefaultIsolationLevel()
boolean	getIgnoreSessionTransactedFlag()
boolean	getLocalTransactionMode() Gets the local transaction mode.
int	getMaintenanceInterval() Gets the pool maintenance interval.
int	getMaxIdleTime() Gets the max idle time for connections in the pool.
int	getMaxLifetime() Gets the maximum lifetime in seconds.
int	getMaxPoolSize() Gets the max size of the pool.
int	getMinPoolSize() Gets the min size of the pool.
int	getReapTimeout() Gets the reap timeout of the pool.
Reference	getReference()
String	getTestQuery() Gets a test query, currently defaults to null (not applicable to JMS).
String	getUniqueResourceName() Gets the unique name for this resource.
javax.jms.XAConnectionFactory	getXaConnectionFactory() Gets the configured XAConnectionFactory.
String	getXaConnectionFactoryClassName() Gets the name of the vendor-specific XAConnectionFactory class implementation.
Properties	getXaProperties() Gets the vendor-specific XA properties to set.
void	init() Initializes the instance.
int	poolAvailableSize()
int	poolTotalSize()
void	refreshPool()
void	setBorrowConnectionTimeout(int timeout) Sets the max timeout that connection requests should wait when no connection is available in the pool.
void	setIgnoreSessionTransactedFlag(boolean value) Sets whether or not to ignore the sessionTransacted flag when creating JMS Sessions.
void	setLocalTransactionMode(boolean mode) Sets whether or not local transactions are desired.
void	setMaintenanceInterval(int interval) Sets the pool maintenance interval, i.e.
void	setMaxIdleTime(int time) Sets the max idle time after which connections are cleaned up from the pool.
void	setMaxLifetime(int maxLifetime) Sets the maximum amount of seconds that a connection is kept in the pool before it is destroyed automatically.
void	setMaxPoolSize(int maxPoolSize) Sets the max size that the pool can reach.
void	setMinPoolSize(int minPoolSize) Sets the min size of the pool.
void	setPoolSize(int minAndMaxSize) Sets both the min and max size of the pool.
void	setReapTimeout(int timeout) Sets the reap timeout for connections.
void	setUniqueResourceName(String resourceName) Sets the unique resource name for this resource, needed for recovery of transactions after restart.
void	setXaConnectionFactory(javax.jms.XAConnectionFactory xaConnectionFactory) Sets the XAConnectionFactory directly, instead of calling setXaConnectionFactoryClassName and setXaProperties.
void	setXaConnectionFactoryClassName(String xaConnectionFactoryClassName) Sets the fully qualified name of a vendor-specific implementation of XAConnectionFatory.
void	setXaProperties(Properties xaProperties) Sets the vendor-specific XA properties.
String	toString()

Methods inherited from class java.lang.Object

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

Constructor Detail

AtomikosConnectionFactoryBean

public AtomikosConnectionFactoryBean()

Method Detail

getMaxPoolSize

public int getMaxPoolSize()

Gets the max size of the pool.

Specified by:

getMaxPoolSize in interface ConnectionPoolProperties

Returns:

int The max size of the pool.

setMaxPoolSize

public void setMaxPoolSize(int maxPoolSize)

Sets the max size that the pool can reach. Optional, defaults to 1.

Parameters:

maxPoolSize -

getMinPoolSize

public int getMinPoolSize()

Gets the min size of the pool.

Specified by:

getMinPoolSize in interface ConnectionPoolProperties

Returns:

The min size.

setMinPoolSize

public void setMinPoolSize(int minPoolSize)

Sets the min size of the pool. Optional, defaults to 1.

Parameters:

minPoolSize -

setPoolSize

public void setPoolSize(int minAndMaxSize)

Sets both the min and max size of the pool. Optional. Overrides any minPoolSize or maxPoolSize that you might have set before!

Parameters:

minAndMaxSize -

getUniqueResourceName

public String getUniqueResourceName()

Gets the unique name for this resource.

Specified by:

getUniqueResourceName in interface ConnectionPoolProperties

Returns:

The name.

setUniqueResourceName

public void setUniqueResourceName(String resourceName)

Sets the unique resource name for this resource, needed for recovery of transactions after restart. Required.

Parameters:

resourceName -

getXaConnectionFactoryClassName

public String getXaConnectionFactoryClassName()

Gets the name of the vendor-specific XAConnectionFactory class implementation.

Returns:

The name of the vendor class.

setXaConnectionFactoryClassName

public void setXaConnectionFactoryClassName(String xaConnectionFactoryClassName)

Sets the fully qualified name of a vendor-specific implementation of XAConnectionFatory. Required, unless you call setXaConnectionFactory.

Parameters:

xaConnectionFactoryClassName -

See Also:

XAConnectionFactory

getXaProperties

public Properties getXaProperties()

Gets the vendor-specific XA properties to set.

Returns:

The properties as key,value pairs.

setXaProperties

public void setXaProperties(Properties xaProperties)

Sets the vendor-specific XA properties. Required, unless you call setXaConnectionFactory.

Parameters:

xaProperties - The properties, to be set (during initialization) on the specified XAConnectionFactory implementation.

getXaConnectionFactory

public javax.jms.XAConnectionFactory getXaConnectionFactory()

Gets the configured XAConnectionFactory.

Returns:

The factory, or null if not yet configured.

setXaConnectionFactory

public void setXaConnectionFactory(javax.jms.XAConnectionFactory xaConnectionFactory)

Sets the XAConnectionFactory directly, instead of calling setXaConnectionFactoryClassName and setXaProperties.

Parameters:

xaConnectionFactory -

setMaxLifetime

public void setMaxLifetime(int maxLifetime)

Sets the maximum amount of seconds that a connection is kept in the pool before it is destroyed automatically. Optional, defaults to 0 (no limit).

Parameters:

maxLifetime -

getMaxLifetime

public int getMaxLifetime()

Gets the maximum lifetime in seconds.

Specified by:

getMaxLifetime in interface ConnectionPoolProperties

init

public void init()
          throws javax.jms.JMSException

Initializes the instance. It is highly recommended that this method be called early after VM startup, to ensure that recovery can start as soon as possible.

Throws:

javax.jms.JMSException

getBorrowConnectionTimeout

public int getBorrowConnectionTimeout()

Gets the timeout for borrowing connections from the pool.

Specified by:

getBorrowConnectionTimeout in interface ConnectionPoolProperties

Returns:

int The timeout in seconds, during which connection requests should wait when no connection is available.

getMaintenanceInterval

public int getMaintenanceInterval()

Gets the pool maintenance interval.

Specified by:

getMaintenanceInterval in interface ConnectionPoolProperties

Returns:

int The interval in seconds.

getMaxIdleTime

public int getMaxIdleTime()

Gets the max idle time for connections in the pool.

Specified by:

getMaxIdleTime in interface ConnectionPoolProperties

Returns:

int The max time in seconds.

getReapTimeout

public int getReapTimeout()

Gets the reap timeout of the pool.

Specified by:

getReapTimeout in interface ConnectionPoolProperties

Returns:

int The timeout in seconds.

getTestQuery

public String getTestQuery()

Gets a test query, currently defaults to null (not applicable to JMS).

Specified by:

getTestQuery in interface ConnectionPoolProperties

setBorrowConnectionTimeout

public void setBorrowConnectionTimeout(int timeout)

Sets the max timeout that connection requests should wait when no connection is available in the pool. Optional, defaults to 30 seconds.

Parameters:

timeout - The timeout in seconds.

setMaintenanceInterval

public void setMaintenanceInterval(int interval)

Sets the pool maintenance interval, i.e. the time (in seconds) between consecutive runs of the maintenance thread. Optional, defaults to 60 seconds.

Parameters:

interval -

setMaxIdleTime

public void setMaxIdleTime(int time)

Sets the max idle time after which connections are cleaned up from the pool. Optional, defaults to 60 seconds.

Parameters:

time -

setReapTimeout

public void setReapTimeout(int timeout)

Sets the reap timeout for connections. Borrowed connections that are not closed before this timeout will be closed by the pool and returned. Optional, defaults to 0 (no timeout).

Parameters:

timeout -

getLocalTransactionMode

public boolean getLocalTransactionMode()

Gets the local transaction mode.

Specified by:

getLocalTransactionMode in interface ConnectionPoolProperties

Returns:

boolean If true, then transactions are not done in XA mode but in local mode.

setLocalTransactionMode

public void setLocalTransactionMode(boolean mode)

Sets whether or not local transactions are desired. With local transactions, no XA enlist will be done - rather, the application should perform session-level JMS commit or rollback, or use explicit acknowledgement modes. Note that this feature also requires support from your JMS vendor. Optional, defaults to false.

Parameters:

mode -

getDefaultIsolationLevel

public int getDefaultIsolationLevel()

Specified by:

getDefaultIsolationLevel in interface ConnectionPoolProperties

close

public void close()

Closes the instance. This method should be called when you are done using the factory.

toString

public String toString()

Overrides:

toString in class Object

createConnection

public javax.jms.Connection createConnection()
                                      throws javax.jms.JMSException

Specified by:

createConnection in interface javax.jms.ConnectionFactory

Throws:

javax.jms.JMSException

See Also:

ConnectionFactory

createConnection

public javax.jms.Connection createConnection(String user,
                                    String password)
                                      throws javax.jms.JMSException

Specified by:

createConnection in interface javax.jms.ConnectionFactory

Throws:

javax.jms.JMSException

See Also:

ConnectionFactory

getReference

public Reference getReference()
                       throws NamingException

Specified by:

getReference in interface Referenceable

Throws:

NamingException

See Also:

Referenceable

poolAvailableSize

public int poolAvailableSize()

poolTotalSize

public int poolTotalSize()

refreshPool

public void refreshPool()

getIgnoreSessionTransactedFlag

public boolean getIgnoreSessionTransactedFlag()

setIgnoreSessionTransactedFlag

public void setIgnoreSessionTransactedFlag(boolean value)

Sets whether or not to ignore the sessionTransacted flag when creating JMS Sessions. If set, then by default all JMS Session objects will be XA-capable and enlist in the active JTA transaction. If not set, then you will only get XA-capable JMS Session objects if the sessionTransacted flag is set upon session creation. Set this to false to get the pre-3.9 behavior of Atomikos. This setting is ignored for localTransactionMode: in localTransactionMode you never get XA-capable Session objects.

Parameters:

value -