Overview | Package | Class | Use | Tree | Deprecated | Index | Help
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

## 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()` Gets the default isolation level preference.
`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.
`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`
  Returns:

### 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()

  Description copied from interface: `ConnectionPoolProperties`
  Gets the default isolation level preference.

  Specified by:
    `getDefaultIsolationLevel` in interface `ConnectionPoolProperties`
  Returns:
    The level, or -1 if not set.

### 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`

Overview | Package | Class | Use | Tree | Deprecated | Index | Help
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

Copyright © 2012. All Rights Reserved.