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

AtomikosConnectionFactoryBean()

Method Summary

void	close() Closes the instance.
javax.jms.Connection	createConnection()
javax.jms.Connection	createConnection(String user, String password)
protected ConnectionFactory	doInit()
int	getBorrowConnectionTimeout() Gets the timeout for borrowing connections from the pool.
int	getDefaultIsolationLevel()
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	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.
protected String	printXaProperties()
void	setBorrowConnectionTimeout(int timeout) Sets the max timeout that connection requests should wait when no connection is available in the pool.
void	setLocalTransactionMode(boolean mode) Sets whether or not local transactions are desired.
void	setMaintenanceInterval(int interval) Sets the pool maintenance interval, i.e. the time (in seconds) between consecutive runs of the maintenance thread.
void	setMaxIdleTime(int time) Sets the max idle time after which connections are cleaned up from the pool.
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.
protected void	throwAtomikosJMSException(String msg)
protected void	throwAtomikosJMSException(String msg, Throwable cause)
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

throwAtomikosJMSException

protected void throwAtomikosJMSException(String msg)
                                  throws AtomikosJMSException

Throws:

AtomikosJMSException

throwAtomikosJMSException

protected void throwAtomikosJMSException(String msg,
                                         Throwable cause)
                                  throws AtomikosJMSException

Throws:

AtomikosJMSException

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 -

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

printXaProperties

protected String printXaProperties()

doInit

protected ConnectionFactory doInit()
                            throws Exception

Throws:

Exception

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