Atomikos 中文说明文档【转】

Atomikos 翻译文档（英文文档来源：下载安装包中START_HERE.html）

                                 ----译者：周枫

请尊重劳动成果，转载请标明，英语水平有限，如有不准确地方请在评论中指出，谢谢

官网地址：http://www.atomikos.com/Main/WebHome

使用版本：AtomikosTransactionsEssentials-3.7.2

感谢您使用Atomikos，下面的说明文档可以让您正确使用，如果您有任何问题或者反馈，请访问我们的帮助网页http://www.atomikos.com/Main/SupportOverview，或者给我们发送邮件sales@atomikos.com。

什么是Atomikos TransactionsEssentials

Atomikos TransactionsEssentials 是一个为Java平台提供增值服务的并且开源类事务管理器，以下是包括在这个开源版本中的一些功能：

l  全面崩溃 / 重启恢复

l  兼容标准的SUN公司JTA API

l  嵌套事务

l  为XA和非XA提供内置的JDBC适配器

注释：XA：XA协议由Tuxedo首先提出的，并交给X/Open组织，作为资源管理器（数据库）与事务管理器的接口标准。目前，Oracle、Informix、DB2和Sybase等各大数据库厂家都提供对XA的支持。XA协议采用两阶段提交方式来管理分布式事务。XA接口提供资源管理器与事务管理器之间进行通信的标准接口。XA协议包括两套函数，以xa_开头的及以ax_开头的。

以下的函数使事务管理器可以对资源管理器进行的操作：

　　1）xa_open,xa_close：建立和关闭与资源管理器的连接。

　　2）xa_start,xa_end：开始和结束一个本地事务。

　　3）xa_prepare,xa_commit,xa_rollback：预提交、提交和回滚一个本地事务。

　　4）xa_recover：回滚一个已进行预提交的事务。

　　5）ax_开头的函数使资源管理器可以动态地在事务管理器中进行注册，并可以对XID(TRANSACTION IDS)进行操作。

　　6）ax_reg,ax_unreg；允许一个资源管理器在一个TMS(TRANSACTION MANAGER SERVER)中动态注册或撤消注册。

l  内置的JMS适配器XA-capable JMS队列连接器

注释：JMS:jms即Java消息服务（Java Message Service）应用程序接口是一个Java平台中关于面向消息中间件（MOM）的API，用于在两个应用程序之间，或分布式系统中发送消息，进行异步通信。Java消息服务是一个与具体平台无关的API，绝大多数MOM提供商都对JMS提供支持。

l  通过XA API兼容第三方适配器

l  更好的整合您的项目

l  集成Hibernate

如何使用Atomikos TransactionsEssentials

Atomikos TransactionsEssentials 是一个可靠的库，可以加入到您的Java应用程序，也就是说为了使用这个产品，您必须添加一些jar文件（包括在dist和lib文件夹下）到您的应用程序或者应用程序服务器。

请注意：Atomikos TransactionsEssentials是一个非常快速的嵌入式事务管理器，这就意味着，您不需要另外启动一个单独的事务管理器进程（不要查找任何的bin文件夹）。相反，您的应用服务器将有它自己的intra-VM事务管理器。

配置需求：至少Java1.5 jdk，并且最少128M的内存

性能优化：尽管这个软件有着很大的优势，但是想要更好的发挥其作用，可以按以下的方法优化：

l  更高的内存，意味着更高的吞吐量（每秒的事务数目）

l  使连接池尽可能的大

l  一旦你不需要的连接请马上关闭它们。不要把你的应用程序放在缓存里，让内部连接池为你做这些，这将促使更高效的连接使用

l  不要让活动的事务闲置：终止所有情况下的事务，尤其是在异常报错情况下的事务。这将减少数据库的锁定时间，并且最大效率的处理启用的使用。

如果想获取这些细节的更多信息，也要参阅文档说明部分。

值得注意的是，在我们所有的压力测试中，Atomikos TransactionsEssentials比J2EE的web容器更高效的吞吐量。这些测量值包括日志记录的高效的事务状态，同样，在我们所有的测量中，包括XA和non-XA，高效的效率是一样的。

在J2SE中使用Atomikos Transactions Essentials,只需要按以下步骤

1. 将idst和lib中的jar包全部放入的项目中
2. 创建或者自定义你应用的transactions.properties（或者jta.properties）文件（事务管理器的配置），然后将它放入到classpath中，安装文件夹中包涵一个实例文件；在properties文件中注释(#)后面的是默认值，取消一行并且改变默认值。
   

   # SAMPLE PROPERTIES FILE FOR THE TRANSACTION SERVICE
   # THIS FILE ILLUSTRATES THE DIFFERENT SETTINGS FOR THE TRANSACTION MANAGER
   # UNCOMMENT THE ASSIGNMENTS TO OVERRIDE DEFAULT VALUES;
   
   # Required: factory implementation class of the transaction core.
   # NOTE: there is no default for this, so it MUST be specified!
   #
   com.atomikos.icatch.service=com.atomikos.icatch.standalone.UserTransactionServiceFactory
   
   # Set base name of file where messages are output
   # (also known as the 'console file').
   #
   # com.atomikos.icatch.console_file_name = tm.out
   
   # Size limit (in bytes) for the console file;
   # negative means unlimited.
   #
   # com.atomikos.icatch.console_file_limit=-1
   
   # For size-limited console files, this option
   # specifies a number of rotating files to
   # maintain.
   #
   # com.atomikos.icatch.console_file_count=1
   
   # Set the number of log writes between checkpoints
   #
   # com.atomikos.icatch.checkpoint_interval=500
   
   # Set output directory where console file and other files are to be put
   # make sure this directory exists!
   #
   # com.atomikos.icatch.output_dir = ./
   
   # Set directory of log files; make sure this directory exists!
   #
   # com.atomikos.icatch.log_base_dir = ./
   
   # Set base name of log file
   # this name will be  used as the first part of
   # the system-generated log file name
   #
   # com.atomikos.icatch.log_base_name = tmlog
   
   # Set the max number of active local transactions
   # or -1 for unlimited.
   #
   # com.atomikos.icatch.max_actives = 50
   
   # Set the default timeout (in milliseconds) for local transactions
   #
   # com.atomikos.icatch.default_jta_timeout = 10000
   
   # Set the max timeout (in milliseconds) for local transactions
   #
   # com.atomikos.icatch.max_timeout = 300000
   
   # The globally unique name of this transaction manager process
   # override this value with a globally unique name
   #
   # com.atomikos.icatch.tm_unique_name = tm
   
   # Do we want to use parallel subtransactions? JTA's default
   # is NO for J2EE compatibility
   #
   # com.atomikos.icatch.serial_jta_transactions=true
   
   # If you want to do explicit resource registration then
   # you need to set this value to false.
   #
   # com.atomikos.icatch.automatic_resource_registration=true  
   
   # Set this to WARN, INFO or DEBUG to control the granularity
   # of output to the console file.
   #
   # com.atomikos.icatch.console_log_level=WARN
   
   # Do you want transaction logging to be enabled or not?
   # If set to false, then no logging overhead will be done
   # at the risk of losing data after restart or crash.
   #
   # com.atomikos.icatch.enable_logging=true
   
   # Should two-phase commit be done in (multi-)threaded mode or not?
   # Set this to false if you want commits to be ordered according
   # to the order in which resources are added to the transaction.
   #
   # NOTE: threads are reused on JDK 1.5 or higher.
   # For JDK 1.4, thread reuse is enabled as soon as the
   # concurrent backport is in the classpath - see
   # http://mirrors.ibiblio.org/pub/mirrors/maven2/backport-util-concurrent/backport-util-concurrent/
   #
   # com.atomikos.icatch.threaded_2pc=false
   
   # Should shutdown of the VM trigger shutdown of the transaction core too?
   #
   # com.atomikos.icatch.force_shutdown_on_vm_exit=false

   
3. 在你的应用程序中，创建一个实例com.atomikos.icatch.jta.UserTransactionImp或者com.atomikos.icatch.jta.UserTransactionManager（使用默认的无参数构造函数）
   

   /**
    * Copyright (C) 2000-2010 Atomikos <info@atomikos.com>
    *
    * This code ("Atomikos TransactionsEssentials"), by itself,
    * is being distributed under the
    * Apache License, Version 2.0 ("License"), a copy of which may be found at
    * http://www.atomikos.com/licenses/apache-license-2.0.txt .
    * You may not use this file except in compliance with the License.
    *
    * While the License grants certain patent license rights,
    * those patent license rights only extend to the use of
    * Atomikos TransactionsEssentials by itself.
    *
    * This code (Atomikos TransactionsEssentials) contains certain interfaces
    * in package (namespace) com.atomikos.icatch
    * (including com.atomikos.icatch.Participant) which, if implemented, may
    * infringe one or more patents held by Atomikos.
    * It should be appreciated that you may NOT implement such interfaces;
    * licensing to implement these interfaces must be obtained separately from Atomikos.
    *
    * Unless required by applicable law or agreed to in writing, software
    * distributed under the License is distributed on an "AS IS" BASIS,
    * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
    */
   
   package com.atomikos.icatch.jta;
   
   import java.io.Serializable;
   
   import javax.naming.NamingException;
   import javax.naming.Reference;
   import javax.naming.Referenceable;
   import javax.transaction.NotSupportedException;
   import javax.transaction.SystemException;
   import javax.transaction.TransactionManager;
   import javax.transaction.UserTransaction;
   
   import com.atomikos.icatch.admin.imp.SimpleLogAdministrator;
   import com.atomikos.icatch.config.TSInitInfo;
   import com.atomikos.icatch.config.UserTransactionService;
   import com.atomikos.icatch.config.UserTransactionServiceImp;
   import com.atomikos.util.SerializableObjectFactory;
   
   /**
    *
    *
    * Our UserTransaction implementation for J2SE transactions. This class is
    * special in that it automatically starts up and recover the transaction
    * service on first use. <b>Note: don't use this class in J2EE applications in
    * order to avoid starting different transaction engines in the same application
    * server! J2EE applications should use J2eeUserTransaction instead.</b>
    */
   
   public class UserTransactionImp implements UserTransaction, Serializable,
           Referenceable
   {
       private transient TransactionManager txmgr_;
   
       /**
        * No-argument constructor.
        */
   
       public UserTransactionImp ()
       {
       }
   
       /**
        * Referenceable mechanism requires later setup of txmgr_, otherwise binding
        * into JNDI already requires that TM is running.
        */
   
       private void checkSetup ()
       {
   
           // REMOVED FOLLOWING IF CHECK: DON'T CACHE THE TXMGR TO MAKE INSTANCES
           // RESILIENT TO RESTART IN TOMCAT. OTHERWISE, CLIENT APPS SEE THEIR
           // USERTX REFERENCES INVALIDATED AND THIS IS INTOLERABLE
           // if ( txmgr_ == null ) {
           // txmgr_ = TransactionManagerImp.getTransactionManager();
   
           synchronized ( TransactionManagerImp.class ) {
   
               txmgr_ = TransactionManagerImp.getTransactionManager ();
   
               // FOLLOWING COMMENTED OUT: NEW RECOVERY IN 2.0 ALLOWS US TO START
               // THE TM
               // IF NOT ALREADY RUNNING!!!
               // if ( txmgr_ == null )
               // throw new RuntimeException ( "No transaction monitor installed?"
               // );
   
               // NEW FROM 2.0: if TM is not running, just start it. Any resources
               // can be registered later.
               if ( txmgr_ == null ) {
                   UserTransactionService uts = new UserTransactionServiceImp ();
                   TSInitInfo info = uts.createTSInitInfo ();
                   uts.registerLogAdministrator ( SimpleLogAdministrator
                           .getInstance () );
                   uts.init ( info );
                   txmgr_ = TransactionManagerImp.getTransactionManager ();
               }
   
           }
   
           // }
       }
   
       /**
        * @see javax.transaction.UserTransaction
        */
   
       public void begin () throws NotSupportedException, SystemException
       {
           checkSetup ();
           txmgr_.begin ();
       }
   
       /**
        * @see javax.transaction.UserTransaction
        */
   
       public void commit () throws javax.transaction.RollbackException,
               javax.transaction.HeuristicMixedException,
               javax.transaction.HeuristicRollbackException,
               javax.transaction.SystemException, java.lang.IllegalStateException,
               java.lang.SecurityException
       {
           checkSetup ();
           txmgr_.commit ();
       }
   
       /**
        * @see javax.transaction.UserTransaction
        */
   
       public void rollback () throws IllegalStateException, SystemException,
               SecurityException
       {
           checkSetup ();
           txmgr_.rollback ();
       }
   
       /**
        * @see javax.transaction.UserTransaction
        */
   
       public void setRollbackOnly () throws IllegalStateException,
               SystemException
       {
           checkSetup ();
           txmgr_.setRollbackOnly ();
       }
   
       /**
        * @see javax.transaction.UserTransaction
        */
   
       public int getStatus () throws SystemException
       {
           checkSetup ();
           return txmgr_.getStatus ();
       }
   
       /**
        * @see javax.transaction.UserTransaction
        */
   
       public void setTransactionTimeout ( int seconds ) throws SystemException
       {
           checkSetup ();
           txmgr_.setTransactionTimeout ( seconds );
       }
   
       //
       //
       // IMPLEMENTATION OF REFERENCEABLE
       //
       //
   
       public Reference getReference () throws NamingException
       {
           return SerializableObjectFactory.createReference ( this );
       }
   }

   
   

   /**
    * Copyright (C) 2000-2010 Atomikos <info@atomikos.com>
    *
    * This code ("Atomikos TransactionsEssentials"), by itself,
    * is being distributed under the
    * Apache License, Version 2.0 ("License"), a copy of which may be found at
    * http://www.atomikos.com/licenses/apache-license-2.0.txt .
    * You may not use this file except in compliance with the License.
    *
    * While the License grants certain patent license rights,
    * those patent license rights only extend to the use of
    * Atomikos TransactionsEssentials by itself.
    *
    * This code (Atomikos TransactionsEssentials) contains certain interfaces
    * in package (namespace) com.atomikos.icatch
    * (including com.atomikos.icatch.Participant) which, if implemented, may
    * infringe one or more patents held by Atomikos.
    * It should be appreciated that you may NOT implement such interfaces;
    * licensing to implement these interfaces must be obtained separately from Atomikos.
    *
    * Unless required by applicable law or agreed to in writing, software
    * distributed under the License is distributed on an "AS IS" BASIS,
    * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
    */
   
   package com.atomikos.icatch.jta;
   
   import java.io.Serializable;
   
   import javax.naming.NamingException;
   import javax.naming.Reference;
   import javax.naming.Referenceable;
   import javax.transaction.HeuristicMixedException;
   import javax.transaction.HeuristicRollbackException;
   import javax.transaction.InvalidTransactionException;
   import javax.transaction.NotSupportedException;
   import javax.transaction.RollbackException;
   import javax.transaction.SystemException;
   import javax.transaction.Transaction;
   import javax.transaction.TransactionManager;
   import javax.transaction.UserTransaction;
   
   import com.atomikos.icatch.config.TSInitInfo;
   import com.atomikos.icatch.config.UserTransactionService;
   import com.atomikos.icatch.config.UserTransactionServiceImp;
   import com.atomikos.util.SerializableObjectFactory;
   
   /**
    *
    *
    *
    *
    *
    * A straightforward, zero-setup implementation of a transaction manager. J2SE
    * applications can use an instance of this class to get a handle to the
    * transaction manager, and automatically startup or recover the transaction
    * service on first use. <b>J2EE applications should NOT use this class in order
    * to avoid the concurrent use of different transaction services. For J2EE
    * applications, we have the class J2eeTransactionManager instead.</b>
    */
   public class UserTransactionManager implements TransactionManager,
           Serializable, Referenceable, UserTransaction
   {
       private static final long serialVersionUID = -655789038710288096L;
   
       private transient TransactionManagerImp tm;
   
       private UserTransactionService uts;
   
       private boolean forceShutdown;
   
       private boolean startupTransactionService;
   
       private boolean closed;
   
       private void checkSetup () throws SystemException
       {
           if ( closed ) throw new SystemException ( "This UserTransactionManager instance was closed already. Call init() to reuse if desired." );
   
           synchronized ( TransactionManagerImp.class ) {
   
               tm = (TransactionManagerImp) TransactionManagerImp
                       .getTransactionManager ();
               if ( tm == null ) {
                   // not initialized -> startup TM
                   // System.out.println ( "STARTING UP TM!!!!!!");
                      if ( getStartupTransactionService() ) {
                       uts = new UserTransactionServiceImp ();
                       TSInitInfo info = uts.createTSInitInfo ();
                       uts.init ( info );
                       tm = (TransactionManagerImp) TransactionManagerImp
                               .getTransactionManager ();
                      }
                      else {
                          throw new SystemException ( "Transaction service not running" );
                      }
               }
           }
       }
   
       public UserTransactionManager()
       {
               //startup by default, to have backward compatibility
               this.startupTransactionService = true;
               this.closed = false;
       }
   
       /**
        * Sets whether the transaction service should be
        * started if not already running.
        * @param startup
        */
       public void setStartupTransactionService ( boolean startup )
       {
               this.startupTransactionService = startup;
       }
   
       /**
        * Returns true if the transaction service will
        * be started if not already running.
        * @return
        */
       public boolean getStartupTransactionService()
       {
               return this.startupTransactionService;
       }
   
       /**
        * Performs initialization if necessary.
        * This will startup the TM (if not running)
        * and perform recovery, unless <b>getStartupTransactionService</b>
        * returns false.
        *
        * @throws SystemException
        */
   
       public void init() throws SystemException
       {
               closed = false;
               checkSetup();
       }
   
       /**
        * @see javax.transaction.TransactionManager#begin()
        */
       public void begin () throws NotSupportedException, SystemException
       {
           checkSetup ();
           tm.begin ();
   
       }
   
       public boolean getForceShutdown()
       {
               return forceShutdown;
       }
   
       /**
        * Sets the force shutdown mode to use during close.
        * @param value
        */
       public void setForceShutdown ( boolean value )
       {
               this.forceShutdown = value;
       }
   
       /**
        * @see javax.transaction.TransactionManager#commit()
        */
       public void commit () throws RollbackException, HeuristicMixedException,
               HeuristicRollbackException, SecurityException,
               IllegalStateException, SystemException
       {
           checkSetup ();
           tm.commit ();
   
       }
   
       /**
        * @see javax.transaction.TransactionManager#getStatus()
        */
       public int getStatus () throws SystemException
       {
           checkSetup ();
           return tm.getStatus ();
       }
   
       /**
        * @see javax.transaction.TransactionManager#getTransaction()
        */
       public Transaction getTransaction () throws SystemException
       {
           checkSetup ();
           return tm.getTransaction ();
       }
   
       /**
        * @see javax.transaction.TransactionManager#resume(javax.transaction.Transaction)
        */
       public void resume ( Transaction tx ) throws InvalidTransactionException,
               IllegalStateException, SystemException
       {
           checkSetup ();
           tm.resume ( tx );
   
       }
   
       /**
        * @see javax.transaction.TransactionManager#rollback()
        */
       public void rollback () throws IllegalStateException, SecurityException,
               SystemException
       {
           checkSetup ();
           tm.rollback ();
   
       }
   
       /**
        * @see javax.transaction.TransactionManager#setRollbackOnly()
        */
       public void setRollbackOnly () throws IllegalStateException,
               SystemException
       {
           checkSetup ();
           tm.setRollbackOnly ();
   
       }
   
       /**
        * @see javax.transaction.TransactionManager#setTransactionTimeout(int)
        */
       public void setTransactionTimeout ( int secs ) throws SystemException
       {
           checkSetup ();
           tm.setTransactionTimeout ( secs );
   
       }
   
       /**
        * @see javax.transaction.TransactionManager#suspend()
        */
       public Transaction suspend () throws SystemException
       {
           checkSetup ();
           return tm.suspend ();
       }
   
       /**
        * @see javax.naming.Referenceable#getReference()
        */
       public Reference getReference () throws NamingException
       {
           return SerializableObjectFactory.createReference ( this );
       }
   
       /**
        * Closes the transaction service, but only if it was
        * implicitly started via this instance.
        * In other words, if the transaction service was started
        * in another way then this method will not do anything.
        *
        */
       public void close()
       {
               if ( uts != null ) {
                   uts.shutdown ( forceShutdown );
                   uts = null;
               }
               closed = true;
       }
   
   }

   
4. 对于JDBC，使用我们的一个实例com.atomikos.jdbc.AtomikosDataSourceBean或者，对于non-XA驱动，可以使用com.atomikos.jdbc.nonxa.AtomikosNonXADataSourceBean
   

   /**
    * Copyright (C) 2000-2010 Atomikos <info@atomikos.com>
    *
    * This code ("Atomikos TransactionsEssentials"), by itself,
    * is being distributed under the
    * Apache License, Version 2.0 ("License"), a copy of which may be found at
    * http://www.atomikos.com/licenses/apache-license-2.0.txt .
    * You may not use this file except in compliance with the License.
    *
    * While the License grants certain patent license rights,
    * those patent license rights only extend to the use of
    * Atomikos TransactionsEssentials by itself.
    *
    * This code (Atomikos TransactionsEssentials) contains certain interfaces
    * in package (namespace) com.atomikos.icatch
    * (including com.atomikos.icatch.Participant) which, if implemented, may
    * infringe one or more patents held by Atomikos.
    * It should be appreciated that you may NOT implement such interfaces;
    * licensing to implement these interfaces must be obtained separately from Atomikos.
    *
    * Unless required by applicable law or agreed to in writing, software
    * distributed under the License is distributed on an "AS IS" BASIS,
    * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
    */
   
   package com.atomikos.jdbc;
   import java.util.Enumeration;
   import java.util.Properties;
   
   import javax.sql.XADataSource;
   
   import com.atomikos.beans.PropertyUtils;
   import com.atomikos.datasource.RecoverableResource;
   import com.atomikos.datasource.xa.jdbc.JdbcTransactionalResource;
   import com.atomikos.icatch.system.Configuration;
   import com.atomikos.jdbc.AbstractDataSourceBean;
   import com.atomikos.util.ClassLoadingHelper;
   
    /**
    * The preferred class for using Atomikos connection pooling. Use an instance of
    * this class if you want to use Atomikos JTA-enabled connection pooling. All
    * you need to do is construct an instance and set the required properties as
    * outlined below. The resulting bean will automatically register with the
    * transaction service (for recovery) and take part in active transactions.
    * All SQL done over connections (gotten from this class) will participate in JTA transactions.
    */
   
   public class AtomikosDataSourceBean
   extends AbstractDataSourceBean
   {
   
       private static final long serialVersionUID = 1L;
   
       private Properties xaProperties = null;
       private String xaDataSourceClassName;
       private transient XADataSource xaDataSource;
       public AtomikosDataSourceBean()
       {
           this.xaProperties = new Properties();
       }
   
       protected String printXaProperties()
       {
           StringBuffer ret = new StringBuffer();
           if ( xaProperties != null ) {
               Enumeration it = xaProperties.propertyNames();
               ret.append ( "[" );
               boolean first = true;
               while ( it.hasMoreElements() ) {
                   if ( ! first ) ret.append ( "," );
                   String name = ( String ) it.nextElement();
                   String value = xaProperties.getProperty( name);
                   ret.append ( name ); ret.append ( "=" ); ret.append ( value );
                   first = false;
               }
               ret.append ( "]" );
           }
           return ret.toString();
       }
   
       /**
        * Gets the properties used to
        * configure the XADataSource.
        */
   
       public Properties getXaProperties()
       {
           return xaProperties;
       }
   
       /**
        * Sets the properties (name,value pairs) used to
        * configure the XADataSource. Required, unless you call setXaDataSource directly.
        *
        * @param xaProperties
        *
        *
        */
       public void setXaProperties ( Properties xaProperties )
       {
           this.xaProperties = xaProperties;
       }
   
       /**
        * Get the XADataSource class name.
        */
       public String getXaDataSourceClassName()
       {
           return xaDataSourceClassName;
       }
   
       /**
        * Sets the fully qualified underlying XADataSource class name. Required, unless you
        * call setXaDataSource directly.
        *
        * @param xaDataSourceClassName
        */
       public void setXaDataSourceClassName ( String xaDataSourceClassName )
       {
           this.xaDataSourceClassName = xaDataSourceClassName;
       }
   
       /**
        * Gets the configured XADataSource (if any).
        * @return The instance, or null if none.
        */
   
       public XADataSource getXaDataSource()
       {
           return xaDataSource;
       }
   
       /**
        * Sets the XADataSource directly - instead of providing the xaDataSourceClassName and xaProperties.
        * @param xaDataSource
        */
       public void setXaDataSource(XADataSource xaDataSource)
       {
           this.xaDataSource = xaDataSource;
       }
   
       protected com.atomikos.datasource.pool.ConnectionFactory doInit() throws Exception
       {
           if (xaDataSource == null)
           {
               if (xaDataSourceClassName == null)
                   throwAtomikosSQLException("Property 'xaDataSourceClassName' cannot be null");
               if (xaProperties == null)
                   throwAtomikosSQLException("Property 'xaProperties' cannot be null");
           }
   
           if ( Configuration.isInfoLoggingEnabled() ) Configuration.logInfo(
                   this + ": initializing with [" +
                   " xaDataSourceClassName=" + xaDataSourceClassName + "," +
                   " uniqueResourceName=" + getUniqueResourceName() + "," +
                   " maxPoolSize=" + getMaxPoolSize() + "," +
                   " minPoolSize=" + getMinPoolSize() + "," +
                   " borrowConnectionTimeout=" + getBorrowConnectionTimeout() + "," +
                   " maxIdleTime=" + getMaxIdleTime() + "," +
                   " reapTimeout=" + getReapTimeout() + "," +
                   " maintenanceInterval=" + getMaintenanceInterval() + "," +
                   " testQuery=" + getTestQuery() + "," +
                   " xaProperties=" + printXaProperties() +
                   " loginTimeout=" + getLoginTimeout() +
                   "]"
                   );
   
               if (xaDataSource == null)
               {
                   Class xadsClass = null;
                   try {
                       xadsClass = ClassLoadingHelper.loadClass ( getXaDataSourceClassName() );
                   } catch ( ClassNotFoundException nf ) {
                       AtomikosSQLException.throwAtomikosSQLException ( "The class '" + getXaDataSourceClassName() +
                               "' specified by property 'xaDataSourceClassName' could not be found in the classpath. Please make sure the spelling is correct, and that the required jar(s) are in the classpath." , nf );
   
                   }
                   Object driver =  xadsClass.newInstance();
                   if ( ! ( driver instanceof XADataSource ) ) {
                       AtomikosSQLException.throwAtomikosSQLException (
                                "The class '" + getXaDataSourceClassName() +
                                   "' specified by property 'xaDataSourceClassName' does not implement the required interface javax.jdbc.XADataSource. Please make sure the spelling is correct, and check your JDBC driver vendor's documentation."
                       );
                   }
                   xaDataSource = (XADataSource) driver;
                   xaDataSource.setLoginTimeout ( getLoginTimeout() );
                   xaDataSource.setLogWriter ( getLogWriter() );
                   PropertyUtils.setProperties(xaDataSource, xaProperties );
               }
   
               JdbcTransactionalResource tr = new JdbcTransactionalResource(getUniqueResourceName() , xaDataSource);
               com.atomikos.datasource.pool.ConnectionFactory cf = new com.atomikos.jdbc.AtomikosXAConnectionFactory(xaDataSource, tr, this);
               Configuration.addResource ( tr );
   
               return cf;
       }
   
       protected void doClose()
       {
           RecoverableResource res = Configuration.getResource ( getUniqueResourceName() );
           if ( res != null ) {
               Configuration.removeResource ( getUniqueResourceName() );
               //fix for case 26005
               res.close();
           }
       }    
   
       public String toString()
       {
           String ret = "AtomikosDataSoureBean";
           String name = getUniqueResourceName();
           if ( name != null ) {
               ret = ret + " '" + name + "'";
           }
           return ret;
       }
   
   }

   
   

   /**
    * Copyright (C) 2000-2010 Atomikos <info@atomikos.com>
    *
    * This code ("Atomikos TransactionsEssentials"), by itself,
    * is being distributed under the
    * Apache License, Version 2.0 ("License"), a copy of which may be found at
    * http://www.atomikos.com/licenses/apache-license-2.0.txt .
    * You may not use this file except in compliance with the License.
    *
    * While the License grants certain patent license rights,
    * those patent license rights only extend to the use of
    * Atomikos TransactionsEssentials by itself.
    *
    * This code (Atomikos TransactionsEssentials) contains certain interfaces
    * in package (namespace) com.atomikos.icatch
    * (including com.atomikos.icatch.Participant) which, if implemented, may
    * infringe one or more patents held by Atomikos.
    * It should be appreciated that you may NOT implement such interfaces;
    * licensing to implement these interfaces must be obtained separately from Atomikos.
    *
    * Unless required by applicable law or agreed to in writing, software
    * distributed under the License is distributed on an "AS IS" BASIS,
    * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
    */
   
   package com.atomikos.jdbc.nonxa;
   
   import java.sql.Connection;
   import java.sql.SQLException;
   
   import com.atomikos.datasource.pool.ConnectionFactory;
   import com.atomikos.icatch.HeuristicMessage;
   import com.atomikos.icatch.system.Configuration;
   import com.atomikos.jdbc.AbstractDataSourceBean;
   import com.atomikos.util.DynamicProxy;
   
    /**
     *
     * A Bean class for DataSource access to non-XA JDBC implementations.
     * Instances are JTA transaction-aware and can rollback the work done
     * over multiple connections (provided that all work was done in one and the same thread).
     *
     *
     */
   public class AtomikosNonXADataSourceBean extends AbstractDataSourceBean
   {
       private static final long serialVersionUID = 1L;
   
       private String url;
   
       private String user;
   
       private String password;
   
       private String driverClassName;
   
       private boolean readOnly;
   
       /**
        * Sets the URL to use for getting connections. Required.
        *
        * @param url
        */
   
       public void setUrl ( String url )
       {
           this.url = url;
       }
   
       /**
        * Gets the URL to connect.
        */
   
       public String getUrl()
       {
           return url;
       }
   
       /**
        * Marks this datasource as being used for read-only work. Optional.
        *
        * Setting this to true will avoid warnings/errors upon recovery. ReadOnly mode
        * is intended to avoid XA configuration of databases where no updates are
        * being done.
        *
        * @param readOnly Defaults to false.
        */
   
       public void setReadOnly ( boolean readOnly )
       {
           this.readOnly = readOnly;
       }
   
       /**
        * @return Whether or not this datasource is marked as readOnly.
        */
   
       public boolean getReadOnly()
       {
           return readOnly;
       }
   
       /**
        * @return The password.
        */
   
       public String getPassword ()
       {
           return password;
       }
   
       /**
        * Sets the password to use.
        *
        * @param string
        */
   
       public void setPassword ( String string )
       {
           password = string;
       }
   
       /**
        * Set the user name to get connections with.
        *
        * @param string
        */
   
       public void setUser ( String string )
       {
           user = string;
       }
   
       /**
        * @return The URL to connect with.
        */
   
       public String getUser ()
       {
           return user;
       }
   
       /**
        *
        * @return The DriverManager class name.
        */
   
       public String getDriverClassName ()
       {
           return driverClassName;
       }
   
       /**
        * Sets the driver class name to be used by the DriverManager. Required.
        *
        * @param string
        */
       public void setDriverClassName ( String string )
       {
           driverClassName = string;
       }
   
       protected void doClose()
       {
           //nothing to do
       }
   
       protected ConnectionFactory doInit() throws Exception
       {
           AtomikosNonXAConnectionFactory ret = null;
           if ( Configuration.isInfoLoggingEnabled() ) Configuration.logInfo(
                   this + ": initializing with [" +
                   " uniqueResourceName=" + getUniqueResourceName() + "," +
                   " maxPoolSize=" + getMaxPoolSize() + "," +
                   " minPoolSize=" + getMinPoolSize() + "," +
                   " borrowConnectionTimeout=" + getBorrowConnectionTimeout() + "," +
                   " maxIdleTime=" + getMaxIdleTime() + "," +
                   " reapTimeout=" + getReapTimeout() + "," +
                   " maintenanceInterval=" + getMaintenanceInterval() + "," +
                   " testQuery=" + getTestQuery() + "," +
                   " driverClassName=" + getDriverClassName() + "," +
                   " user=" + getUser() + "," +
                   " url=" + getUrl() +
                   " loginTimeout=" + getLoginTimeout() +
                   "]"
                   );
   
           ret = new com.atomikos.jdbc.nonxa.AtomikosNonXAConnectionFactory ( this , url , driverClassName , user , password , getLoginTimeout() , readOnly ) ;
           ret.init();
           return ret;
       }
   
       public synchronized Connection getConnection ( HeuristicMessage hmsg ) throws SQLException
       {
           if ( Configuration.isInfoLoggingEnabled() ) Configuration.logInfo ( this + ": getConnection ( " + hmsg + " )..." );
   
           init();
   
           //let pool take care of reusing an existing handle
           Connection proxy = super.getConnection ( hmsg );          
   
           // here we are certain that proxy is not null -> increase the use count
           DynamicProxy dproxy = ( DynamicProxy ) proxy;
           com.atomikos.jdbc.nonxa.AtomikosThreadLocalConnection previous = (AtomikosThreadLocalConnection) dproxy.getInvocationHandler();
   
           previous.incUseCount();
           previous.addHeuristicMessage ( hmsg );
           if ( Configuration.isDebugLoggingEnabled() ) Configuration.logDebug ( this + ": returning " + proxy );
           return proxy;
       }
   
       public String toString()
       {
           String ret = "AtomikosNonXADataSourceBean";
           String name = getUniqueResourceName();
           if ( name != null ) {
               ret = ret + " '" + name + "'";
           }
           return ret;
       }
   
   }

   
5. 对于JMS，可以使用我们的实例com.atomikos.jms.AtomikosConnectionFactoryBean,com.atomikos.jms.extra.AbstractJmsSenderTemplate（发送信息时使用）com.atomikos.jms.extra.MessageDrivenContainer（接收时使用）
   

   /**
    * Copyright (C) 2000-2010 Atomikos <info@atomikos.com>
    *
    * This code ("Atomikos TransactionsEssentials"), by itself,
    * is being distributed under the
    * Apache License, Version 2.0 ("License"), a copy of which may be found at
    * http://www.atomikos.com/licenses/apache-license-2.0.txt .
    * You may not use this file except in compliance with the License.
    *
    * While the License grants certain patent license rights,
    * those patent license rights only extend to the use of
    * Atomikos TransactionsEssentials by itself.
    *
    * This code (Atomikos TransactionsEssentials) contains certain interfaces
    * in package (namespace) com.atomikos.icatch
    * (including com.atomikos.icatch.Participant) which, if implemented, may
    * infringe one or more patents held by Atomikos.
    * It should be appreciated that you may NOT implement such interfaces;
    * licensing to implement these interfaces must be obtained separately from Atomikos.
    *
    * Unless required by applicable law or agreed to in writing, software
    * distributed under the License is distributed on an "AS IS" BASIS,
    * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
    */
   
   package com.atomikos.jms;
   
   import java.io.Serializable;
   
   import javax.jms.ConnectionFactory;
   import javax.jms.JMSException;
   import javax.naming.NamingException;
   import javax.naming.Reference;
   import javax.naming.Referenceable;
   
   import com.atomikos.util.SerializableObjectFactory;
   
   /**
    *
    *
    * Common logic for the connection factory beans.
    *
    */
   
   public abstract class AbstractConnectionFactoryBean
   implements Serializable, Referenceable, ConnectionFactory
   {
   
       protected String resourceName_;
       protected String xaFactoryJndiName_;
   
       protected AbstractConnectionFactoryBean ( )
       {
           this.xaFactoryJndiName_ = "";
           this.resourceName_ = "someUniqueName";
       }
   
       /**
        * Sets the JNDI name of the underlying XAConnectionFactory (optional). This is
        * optional and an alternative to directly supplying the required factory
        * through setXaConnectionFactory().
        *
        * @param name
        *            The JNDI name where the XAConnectionFactory can be found.
        *            It is up to the client to make sure that the name exists and
    *            points to an existing XAConnectionFactory.
        */
       public void setXaFactoryJndiName ( String name )
       {
           xaFactoryJndiName_ = name;
   
       }
   
       /**
        * Retrieve the JNDI name where the XAConnectionFactory is expected.
        *
        * @return String the name or an empty String if not set.
        */
       public String getXaFactoryJndiName()
       {
           return xaFactoryJndiName_;
       }
   
       /**
        * Set the unique resource name for this factory (required). A unique
        * resource name is needed by the transaction service in order to register
        * and recover the underlying XA transactions.
        * Note: the value you set here should not exceed 45 bytes in length.
        *
        * <p><b>MQSeries NOTE:</b> For
        * IBM MQSeries, the name should include MQSeries_XA_RMI or the XA routines
        * will not work properly!
        *
        * @param name
        *            The unique resource name.
        */
       public void setResourceName ( String name )
       {
           resourceName_ = name;
       }
   
       /**
        * Get the resource name.
        *
        * @return String the unique resource name as previously set.
        */
       public String getResourceName()
       {
           return resourceName_;
       }
   
       public Reference getReference() throws NamingException
       {
           return SerializableObjectFactory.createReference ( this );
       }
   
       /**
        * Initialization method to register the underlying resource for recovery
        * and other init code.
        *
        * @throws JMSException
        */
   
       public void init() throws JMSException
       {
               checkSetup();
       }
   
       protected abstract void checkSetup() throws JMSException;
   
   }

   
   

   /**
    * Copyright (C) 2000-2010 Atomikos <info@atomikos.com>
    *
    * This code ("Atomikos TransactionsEssentials"), by itself,
    * is being distributed under the
    * Apache License, Version 2.0 ("License"), a copy of which may be found at
    * http://www.atomikos.com/licenses/apache-license-2.0.txt .
    * You may not use this file except in compliance with the License.
    *
    * While the License grants certain patent license rights,
    * those patent license rights only extend to the use of
    * Atomikos TransactionsEssentials by itself.
    *
    * This code (Atomikos TransactionsEssentials) contains certain interfaces
    * in package (namespace) com.atomikos.icatch
    * (including com.atomikos.icatch.Participant) which, if implemented, may
    * infringe one or more patents held by Atomikos.
    * It should be appreciated that you may NOT implement such interfaces;
    * licensing to implement these interfaces must be obtained separately from Atomikos.
    *
    * Unless required by applicable law or agreed to in writing, software
    * distributed under the License is distributed on an "AS IS" BASIS,
    * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
    */
   
   package com.atomikos.jms.extra;
   
   import java.io.Serializable;
   import java.util.Map;
   
   import javax.jms.Connection;
   import javax.jms.Destination;
   import javax.jms.JMSException;
   import javax.jms.Queue;
   import javax.jms.Session;
   import javax.jms.Topic;
   import javax.transaction.Status;
   import javax.transaction.SystemException;
   
   import com.atomikos.icatch.jta.UserTransactionManager;
   import com.atomikos.icatch.system.Configuration;
   import com.atomikos.jms.AtomikosConnectionFactoryBean;
   import com.atomikos.jms.AtomikosJMSException;
   import com.atomikos.jms.AtomikosTransactionRequiredJMSException;
   
    /**
     * Common functionality for the sender templates.
     *
     */
   
   public abstract class AbstractJmsSenderTemplate
   {
   
       protected AtomikosConnectionFactoryBean connectionFactoryBean;
       private String user;
       protected String password;
       protected Destination destination;
       private String destinationName;
       private Destination replyToDestination;
       private String replyToDestinationName;
       private int deliveryMode;
       private int priority;
       private long timeToLive;
       protected boolean inited;
   
       protected AbstractJmsSenderTemplate()
       {
           // set default values according to Sun's JMS javadocs
           setTimeToLive ( 0 );
           setDeliveryMode ( javax.jms.DeliveryMode.PERSISTENT );
           setPriority ( 4 );
       }
   
       protected abstract Session getOrRefreshSession ( Connection c ) throws JMSException;
   
       protected abstract Connection getOrReuseConnection() throws JMSException;
   
       protected abstract void afterUseWithoutErrors ( Connection c , Session s ) throws JMSException;
   
       protected void destroy ( Connection c , Session s)
       throws JMSException {
   
           try {
               if ( s != null ) s.close();
           } catch ( JMSException warn ) {
               Configuration.logWarning ( this + ": error closing session" , warn);
           }
   
           try {
               if ( c != null ) c.close();
           } catch ( JMSException warn ) {
               Configuration.logWarning ( this + ": error closing connection" , warn);
           }
   
       }
       protected synchronized Connection refreshConnection() throws JMSException {
           Connection connection = null;
           if ( getDestinationName() == null )
               throw new JMSException ( "Please call setDestination or setDestinationName first!" );
   
           if ( user != null ) {
               connection = connectionFactoryBean.createConnection (
                       user, password );
   
           } else {
               connection = connectionFactoryBean.createConnection ();
           }
           connection.start ();
           return connection;
       }
   
       /**
        * Initializes the session for sending.
        * Call this method first.
        */
   
       public void init() throws JMSException
       {
           if ( ! inited ) {
               if ( connectionFactoryBean == null ) throw new IllegalStateException ( "Property 'atomikosConnectionFactoryBean' must be set first!" );
               if ( getDestinationName() == null ) {
                   throw new IllegalStateException ( "Property 'destination' or 'destinationName' must be set first!" );
               }
               StringBuffer msg = new StringBuffer();
               msg.append ( this + ":configured with [" );
               msg.append ( "user=" ).append ( getUser() ).append ( ", " );
               msg.append ( "password=" ).append ( password ).append ( ", " );
               msg.append ( "deliveryMode=" ).append ( getDeliveryMode() ).append ( ", " );
               msg.append ( "timeToLive=" ).append ( getTimeToLive() ).append ( ", " );
               msg.append ( "priority=" ).append ( getPriority() ).append ( ", " );
               msg.append ( "destination=" ).append( getDestinationName() ).append ( ", " );
               msg.append ( "replyToDestination=" ).append ( getReplyToDestinationName() );
               msg.append ( "]" );
               if ( Configuration.isDebugLoggingEnabled() ) Configuration.logDebug ( msg.toString() );
               inited = true;
           }
       }
   
       private void retrieveDestinationIfNecessary() throws JMSException
       {
           if ( getDestination() == null ) {
               String dName = getDestinationName();
               RetrieveDestinationCallback cb = new RetrieveDestinationCallback ( dName );
               executeCallbackInternal ( cb );
               setDestination ( cb.getDestination() );
           }
   
       }
   
       private void retrieveReplyToDestinationIfNecessary() throws JMSException
       {
           if ( getReplyToDestination() == null ) {
               String dName = getReplyToDestinationName();
               if ( dName != null ) {
                   RetrieveDestinationCallback cb = new RetrieveDestinationCallback ( dName );
                   executeCallbackInternal ( cb );
                   setReplyToDestination ( cb.getDestination() );
               }
   
           }
   
       }
   
       /**
        * Sets the connection factory to use. Required.
        * @param connectionFactory
        */
       public void setAtomikosConnectionFactoryBean(AtomikosConnectionFactoryBean connectionFactory) {
           this.connectionFactoryBean = connectionFactory;
       }
   
       public AtomikosConnectionFactoryBean getAtomikosConnectionFactoryBean() {
           return connectionFactoryBean;
       }
   
       public Destination getDestination() {
           return destination;
       }
   
       /**
        * Sets the (provider-specific) destination name in order
        * to lookup the destination (rather than providing one directly).
        *
        * Required, unless you set the destination directly.
        *
        * @param destinationName
        */
   
       public void setDestinationName ( String destinationName )
       {
           this.destinationName = destinationName;
       }
   
       /**
        * Sets the destination to send to. Required, unless
        * you set the destinationName instead.
        *
        * @param destination
        */
       public void setDestination(Destination destination) {
           this.destination = destination;
       }
   
       private String getName(Destination d, String destinationName ) {
           String ret = destinationName;
           if ( ret == null ) {
               if ( d instanceof Queue ) {
                   Queue q = ( Queue ) d;
                   try {
                       ret = q.getQueueName();
                   } catch ( JMSException e ) {
                       if ( Configuration.isDebugLoggingEnabled() ) Configuration.logDebug ( this + ": error retrieving queue name" , e );
                   }
               } else if ( d instanceof Topic ) {
                   Topic t = ( Topic ) d;
                   try {
                       ret = t.getTopicName();
                   } catch ( JMSException e ) {
                       if ( Configuration.isDebugLoggingEnabled() ) Configuration.logDebug ( this + ": error retrieving topic name" , e );
                   }
               }
           }
           return ret;
       }
   
       protected String getDestinationName() {
           return getName ( getDestination() , destinationName );
       }
   
       protected String getReplyToDestinationName() {
           return getName ( getReplyToDestination() , replyToDestinationName );
       }
   
       /**
        * @return The user to connect with, or null if no explicit authentication
        *         is to be used.
        */
       public String getUser() {
           return user;
       }
   
       /**
        * If this session is used for sending request/reply messages, then this
        * property indicates the destination where the replies are to be sent (optional). The
        * session uses this to set the JMSReplyTo header accordingly. This property
        * can be omitted if no reply is needed.
        *
        * <p>
        * The replyToDestination should be in the same JMS vendor domain as the send
        * queue. To cross domains, configure a bridge for both the request and the
        * reply channels.
        */
       public void setReplyToDestination(Destination destination)
       {
           this.replyToDestination = destination;
       }
   
       /**
        * Sets the provider-specific replyToDestinationName. Optional.
        *
        * @param replyToDestinationName
        */
   
       public void setReplyToDestinationName ( String replyToDestinationName )
       {
           this.replyToDestinationName = replyToDestinationName;
   
       }    
   
       /**
        * Gets the replyToDestination.
        *
        * @return
        */
       public Destination getReplyToDestination() {
           return replyToDestination;
       }
   
       /**
        * Set the password for explicit authentication (optional).
        * This is only required if
        * the user has also been set.
        *
        * @param password
        *            The password.
        */
       public void setPassword(String password) {
           this.password = password;
       }
   
       /**
        * Set the user to use for explicit authentication (optional). If no explicit
        * authentication is required then this method should not be called.
        *
        * @param user
        */
       public void setUser(String user) {
           this.user = user;
       }
   
       protected void executeCallbackInternal (
               JmsSenderTemplateCallback callback ) throws JMSException {
   
           init();
           Session  session = null;
           Connection conn = null;
           try {
               conn = getOrReuseConnection();
               session = getOrRefreshSession ( conn );
               if ( Configuration.isDebugLoggingEnabled() ) Configuration.logDebug ( "Calling callback..." );
               callback.doInJmsSession ( session );
               if ( Configuration.isDebugLoggingEnabled() ) Configuration.logDebug ( "Callback done!" );
               afterUseWithoutErrors ( conn , session );
   
           } catch ( AtomikosTransactionRequiredJMSException notx ) {
               destroy ( conn , session );
               String msg = "The JMS session you are using requires a JTA transaction context for the calling thread and none was found." + "\n" +
               "Please correct your code to do one of the following: " + "\n" +
               "1. start a JTA transaction before sending any message, or" + "\n" +
               "2. increase the maxPoolSize of the AtomikosConnectionFactoryBean to avoid transaction timeout while waiting for a connection.";
               Configuration.logWarning ( msg );
               AtomikosTransactionRequiredJMSException.throwAtomikosTransactionRequiredJMSException ( msg );
   
           } catch ( JMSException e ) {
               e.printStackTrace();
               destroy ( conn , session );
               String msg = this + ": error in sending JMS message";
               AtomikosJMSException.throwAtomikosJMSException( msg , e );
           }
       }
   
       /**
        * Executes an application-level call-back within the managed session.
        *
        * @param callback
        * @throws JMSException
        */
       public void executeCallback(JmsSenderTemplateCallback callback) throws JMSException {
   
           init();        
   
           retrieveDestinationIfNecessary();
           retrieveReplyToDestinationIfNecessary();
   
           UserTransactionManager tm = new UserTransactionManager ();
           try {
               if ( tm.getStatus () != Status.STATUS_ACTIVE )
                   throw new JMSException (
                           "This method requires an active transaction!" );
           } catch ( SystemException e ) {
               Configuration
                       .logWarning ( this +": error in getting transaction status", e );
               throw new RuntimeException ( e.getMessage () );
           }
   
           executeCallbackInternal ( callback );
   
       }
   
       /**
        * @return The deliverymode for messages sent in this session.
        */
       public int getDeliveryMode() {
           return deliveryMode;
       }
   
       /**
        * @return The priority for messages sent in this session.
        */
       public int getPriority() {
           return priority;
       }
   
       /**
        * @return The timeToLive for messages sent in this session.
        */
       public long getTimeToLive() {
           return timeToLive;
       }
   
       /**
        *
        * Set the deliverymode for messages sent in this session (optional). Defaults to
        * persistent.
        *
        * @param
        */
       public void setDeliveryMode(int i) {
           deliveryMode = i;
       }
   
       /**
        * Set the priority for messages sent in this session (optional). Defaults to 4.
        *
        * @param
        */
       public void setPriority(int i) {
           priority = i;
       }
   
       /**
        * Set the time to live for messages sent in this session (optional). Defaults to 0.
        *
        * @param
        */
       public void setTimeToLive(long l) {
           timeToLive = l;
       }
   
       /**
        * Sends a TextMessage.
        *
        * @param content The text as a string.
        * @throws JMSException
        */
       public void sendTextMessage(String content) throws JMSException {
           retrieveDestinationIfNecessary();
           retrieveReplyToDestinationIfNecessary();
           SendTextMessageCallback cb = new SendTextMessageCallback ( content , getDestination() , getReplyToDestination() , getDeliveryMode() , getPriority() , getTimeToLive() );
           executeCallback ( cb );
       }
   
       /**
        * Sends a MapMessage.
        *
        * @param content The Map to get the content from.
        *
        * @throws JMSException
        */
       public void sendMapMessage(Map content) throws JMSException {
           retrieveDestinationIfNecessary();
           retrieveReplyToDestinationIfNecessary();
           SendMapMessageCallback cb = new SendMapMessageCallback ( content , getDestination() , getReplyToDestination() , getDeliveryMode() , getPriority() , getTimeToLive() );
           executeCallback ( cb );
       }
   
       /**
        * Sends an ObjectMessage.
        *
        * @param content The serializable object content.
        * @throws JMSException
        */
       public void sendObjectMessage(Serializable content) throws JMSException {
           retrieveDestinationIfNecessary();
           retrieveReplyToDestinationIfNecessary();
           SendObjectMessageCallback cb = new SendObjectMessageCallback ( content , getDestination() , getReplyToDestination() , getDeliveryMode() , getPriority() , getTimeToLive() );
           executeCallback ( cb );
       }
   
       /**
        * Sends a ByteMessage.
        *
        * @param content The content as a byte array.
        * @throws JMSException
        */
       public void sendBytesMessage(byte[] content) throws JMSException {
           retrieveDestinationIfNecessary();
           retrieveReplyToDestinationIfNecessary();
           SendBytesMessageCallback cb = new SendBytesMessageCallback ( content , getDestination() , getReplyToDestination() , getDeliveryMode() , getPriority() , getTimeToLive() );
           executeCallback ( cb );
       }
   
       /**
        * Closes all resources.
        */
       public void close() {
           try {
               Connection c = getOrReuseConnection();
               Session s = getOrRefreshSession(c);
               destroy(c, s);
           } catch (JMSException e) {
               Configuration.logWarning ( this + ": error closing" , e );
           }
           connectionFactoryBean.close();
       }
   
   }

   
   

   /**
    * Copyright (C) 2000-2010 Atomikos <info@atomikos.com>
    *
    * This code ("Atomikos TransactionsEssentials"), by itself,
    * is being distributed under the
    * Apache License, Version 2.0 ("License"), a copy of which may be found at
    * http://www.atomikos.com/licenses/apache-license-2.0.txt .
    * You may not use this file except in compliance with the License.
    *
    * While the License grants certain patent license rights,
    * those patent license rights only extend to the use of
    * Atomikos TransactionsEssentials by itself.
    *
    * This code (Atomikos TransactionsEssentials) contains certain interfaces
    * in package (namespace) com.atomikos.icatch
    * (including com.atomikos.icatch.Participant) which, if implemented, may
    * infringe one or more patents held by Atomikos.
    * It should be appreciated that you may NOT implement such interfaces;
    * licensing to implement these interfaces must be obtained separately from Atomikos.
    *
    * Unless required by applicable law or agreed to in writing, software
    * distributed under the License is distributed on an "AS IS" BASIS,
    * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
    */
   
   package com.atomikos.jms.extra;
   
   import java.util.ArrayList;
   import java.util.Iterator;
   import java.util.List;
   
   import javax.jms.Destination;
   import javax.jms.ExceptionListener;
   import javax.jms.JMSException;
   import javax.jms.MessageListener;
   
   import com.atomikos.icatch.system.Configuration;
   import com.atomikos.jms.AtomikosConnectionFactoryBean;
   
    /**
     *
     * A message-driven container for asynchronously receiving JMS messages
     * from a topic or queue, within a managed JTA transaction context.
     *
     * Upon start, an instance of this class will create a number of
     * concurrent sessions that listen for incoming messages on the same destination.
     * MessageListener instances should be thread-safe if the pool size is larger
     * than one. Note: in general, after start() any changed properties are only
     * effective on the next start() event.
     *
     * <p>
     * <b>IMPORTANT:</b> the transactional behaviour guarantees redelivery after failures.
     * As a side-effect, this can lead to so-called <em>poison messages</em>: messages
     * whose processing repeatedly fails due to some recurring error (for instance, a primary
     * key violation in the database, a NullPointerException, ...). Poison messages are problematic
     * because they can prevent other messages from being processed, and block the system.
     *
     * To avoid poison messages, make sure that your MessageListener implementation
     * only throws a <b>RuntimeException</b> when the problem is <em>transient</em>. In that
     * case, the system will perform rollback and the message will be redelivered
     * facing a clean system state. All non-transient errors (i.e., those that happen
     * each time a message is delivered) indicate problems at the application level
     * and should be dealt with by writing better application code.
     */
   
   public class MessageDrivenContainer
   implements MessageConsumerSessionProperties
   {
       private static final int DEFAULT_TIMEOUT = 30;
   
       private AtomikosConnectionFactoryBean connectionFactoryBean;
       private MessageListener messageListener;
       private String user;
       private String password;
       private Destination destination;
       private String destinationName;
       private int transactionTimeout;
       private int poolSize;
       private List sessions;
       private boolean daemonThreads;
       private boolean notifyListenerOnClose;
       private String messageSelector;
       private ExceptionListener exceptionListener;
       private String subscriberName;
       private boolean noLocal;
       private boolean unsubscribeOnClose;
       private String clientID;
   
       private int receiveTimeout;
   
       public MessageDrivenContainer()
       {
           sessions = new ArrayList ();
           notifyListenerOnClose = false;
           setPoolSize ( 1 );
           setTransactionTimeout ( DEFAULT_TIMEOUT );
       }
   
       private MessageConsumerSession createSession()
       {
           return new MessageConsumerSession ( this );
       }
   
       /**
        * Sets the clientID for durable subscriptions. Optional.
        *
        * @param clientID
        */
       public void setClientID ( String clientID ) {
           this.clientID = clientID;
       }
   
       /**
        * Sets the connection factory to use. Required.
        * @param bean
        */
       public void setAtomikosConnectionFactoryBean ( AtomikosConnectionFactoryBean bean )
       {
           this.connectionFactoryBean = bean;
       }
   
       public AtomikosConnectionFactoryBean getAtomikosConnectionFactoryBean()
       {
           return connectionFactoryBean;
       }
   
       /**
        * Gets the destination.
        *
        * @return The destination, or null if not set.
        */
       public Destination getDestination()
       {
           return destination;
       }
   
       /**
        * Sets the JMS destination to listen on (required unless the destinationName is set instead).
        *
        * @param dest
        */
       public void setDestination ( Destination dest )
       {
           this.destination = dest;
       }
   
       /**
        * Gets the destination name.
        *
        * @return The name, or null if not set.
        */
       public String getDestinationName()
       {
           return destinationName;
       }
   
       /**
        * Sets the JMS provider-specific destination name
        * (required unless the destination is set directly).
        *
        * @param destinationName
        */
       public void setDestinationName ( String destinationName )
       {
           this.destinationName = destinationName;
       }
   
       /**
        * Sets whether threads should be daemon threads or not (optional).
        * Default is false.
        * @param value If true then threads will be daemon threads.
        */
       public void setDaemonThreads ( boolean value )
       {
               this.daemonThreads = value;
       }
   
       /**
        * Tests whether threads are daemon threads.
        * @return True if threads are deamons.
        */
       public boolean getDaemonThreads()
       {
               return daemonThreads;
       }
   
       /**
        *
        * Get the message listener if any.
        *
        * @return
        */
       public MessageListener getMessageListener()
       {
           return messageListener;
       }
   
       /**
        * Get the transaction timeout.
        *
        * @return
        */
       public int getTransactionTimeout()
       {
           return transactionTimeout;
       }
   
       /**
        * Get the user for connecting, or null if the default user should be used.
        *
        * @return
        */
       public String getUser()
       {
           return user;
       }
   
       /**
        * Set the message listener to use (required).
        * The same instance will be used for each
        * session in the pool, meaning that instances need to be thread-safe. Only
        * one listener is allowed at a time. Call this method with a null argument
        * to unset the listener.
        *
        * @param listener
        */
       public void setMessageListener ( MessageListener listener )
       {
   
           messageListener = listener;
           Iterator it = sessions.iterator ();
           while ( it.hasNext () ) {
               MessageConsumerSession s = (MessageConsumerSession) it.next ();
               s.setMessageListener ( listener );
           }
       }
   
       /**
        * Set the password if explicit authentication is needed (optional).
        * You need to set this if the user is also set.
        *
        * @param string
        */
       public void setPassword ( String string )
       {
           password = string;
       }
   
       /**
        * Set the transaction timeout in seconds (optional).
        *
        * @param seconds
        */
       public void setTransactionTimeout ( int seconds )
       {
           transactionTimeout = seconds;
       }
   
       /**
        * Set the user to use for explicit authentication (optional).
        * Don't set this property
        * if you want to use the default authentication.
        *
        * @param string
        */
       public void setUser ( String string )
       {
           user = string;
       }
   
       /**
        * Get the message selector (if any)
        *
        * @return The selector, or null if none.
        */
       public String getMessageSelector()
       {
           return this.messageSelector;
       }
   
       /**
        * Set the message selector to use (optional).
        *
        * @param selector
        */
       public void setMessageSelector ( String selector )
       {
           this.messageSelector = selector;
       }
   
       /**
        * Get the size of the pool.
        *
        * @return
        */
       public int getPoolSize()
       {
           return poolSize;
       }
   
       /**
        * Sets the size of the session pool (optional).
        * Default is 1.
        *
        * @param size
        */
       public void setPoolSize ( int size )
       {
           poolSize = size;
       }
   
       /**
        * Gets the exception listener (if any).
        * @return Null if no ExceptionListener was set.
        */
       public ExceptionListener getExceptionListener()
       {
           return exceptionListener;
       }
   
       /**
        * Sets the exception listener (optional). The listener will be
        * notified of connection-level JMS errors.
        *
        * @param exceptionListener
        */
       public void setExceptionListener ( ExceptionListener exceptionListener )
       {
           this.exceptionListener = exceptionListener;
       }
   
       /**
        * Test if this instance will receive sends from the same connection.
        *
        * @return
        */
       public boolean isNoLocal() {
           return noLocal;
       }
   
       /**
        * Sets whether or not this topic should receive sends from the
        * same connection (optional).
        *
        * @param noLocal
        */
   
       public void setNoLocal(boolean noLocal) {
           this.noLocal = noLocal;
       }
   
       /**
        * Gets the subscriber name (for durable subscribers).
        * @return The name, or null if not set (no durable subscriber).
        */
   
       public String getSubscriberName() {
           return subscriberName;
       }
   
       /**
        * Sets the name to use for durable subscriptions (optional).
        * <br>
        * <b>Note: this name will be appended with a suffix to ensure uniqueness
        * among instances in the pool. Otherwise, the JMS back-end would see
        * multiple instances subscribing with the same name - an error.</b>
        *
        * @param subscriberName
        */
   
       public void setSubscriberName(String subscriberName) {
           this.subscriberName = subscriberName;
       }
   
       protected boolean getNoLocal() {
   
           return isNoLocal();
       }
   
       /**
        * Start listening for messages.
        *
        * @throws JMSException
        */
       public void start() throws JMSException
       {
           if ( destination == null && destinationName == null )
               throw new JMSException (
                       "MessageDrivenContainer: destination not specified" );
           if ( connectionFactoryBean == null )
               throw new JMSException (
                       "MessageDrivenContainer: factory not set" );
           if ( messageListener == null )
               throw new JMSException (
                       "MessageDrivenContainer: messageListener not set" );
           for ( int i = 0; i < poolSize; i++ ) {
               MessageConsumerSession s = createSession();
               s.setMessageListener ( messageListener );
               s.setPassword ( password );
               s.setUser ( user );
               s.setDestination ( destination );
               s.setDestinationName ( destinationName );
               s.setAtomikosConnectionFactoryBean ( connectionFactoryBean );
               s.setDaemonThreads ( daemonThreads );
               s.setNotifyListenerOnClose ( notifyListenerOnClose );
               s.setMessageSelector ( getMessageSelector () );
               s.setExceptionListener ( exceptionListener );
               s.setNoLocal( noLocal );
               s.setSubscriberName( subscriberName );
               //set subscriber name with suffix to ensure unique names
               if ( getSubscriberName() != null ) s.setSubscriberName ( getSubscriberName() + "-" + i );
               s.setNoLocal ( getNoLocal() );
               s.setClientID(clientID);
               try {
                   s.startListening ();
                   // System.out.println ( "MessageDrivenContainer: started
                   // session");
               } catch ( Exception e ) {
                   Configuration.logWarning ( "Error starting pool", e );
               }
               sessions.add ( s );
           }
   
           // set listener again to trigger listening
           setMessageListener ( messageListener );
       }
   
       /**
        * Stop listening for messages. If <b>notifyListenerOnClose</b> is set then
        * calling this method will notify the listener by calling its onMessage
        * method with a null argument (and also without transaction context).
        *
        * This method will wait for all active receive operations to unblock, which may take
        * up to <b>receiveTimeout</b> seconds per active thread.
        */
       public void stop()
       {
           Iterator it = sessions.iterator ();
           while ( it.hasNext () ) {
               MessageConsumerSession s = (MessageConsumerSession) it.next ();
               s.stopListening ();
           }
       }
   
       /**
        * Getter to check whether the listener is notified on close.
        *
        * @return
        */
       public boolean getNotifyListenerOnClose()
       {
           return notifyListenerOnClose;
       }
   
       /**
        * Set whether the listener should be notified of close events on the pool
        * (optional). Default is false.
        *
        * @param b
        *            If true, then the listener will receive a null message if the
        *            pool is closed.
        */
       public void setNotifyListenerOnClose ( boolean b )
       {
           notifyListenerOnClose = b;
           Iterator it = sessions.iterator ();
           while ( it.hasNext () ) {
                 MessageConsumerSession s = (MessageConsumerSession) it.next ();
               s.setNotifyListenerOnClose ( b );
           }
       }
   
       /**
        * Sets whether unsubscribe should be done at closing time (optional). Default is false.
        *
        * @param b If true, then unsubscribe will be done at closing time. This only applies to
        * durable subscribers (i.e., cases where subscriberName is set).
        */
       public void setUnsubscribeOnClose ( boolean b )
       {
           this.unsubscribeOnClose = b;
       }
   
       /**
        * Getter to test if unsubscribe should be called on close.
        */
   
       public boolean getUnsubscribeOnClose()
       {
           return unsubscribeOnClose;
       }
   
       /**
        * Gets the receive timeout in seconds.
        *
        * @return
        */
       public int getReceiveTimeout() {
           int ret = receiveTimeout;
           if ( ret <=0 ) ret = getTransactionTimeout()/2;
           return ret;
       }
   
       /**
        * Sets the receive timeout in seconds,
        * i.e. the number of seconds to wait for incoming messages in the message listener thread's event loop.
        *
        * This property is optional and defaults to half the transactionTimeout, but typically this should be lower
        * because the time required to shutdown (stop) this container will be bound by this value multiplied by
        * the number of threads (as indicated by <b>poolSize</b>).
        *
        * @param seconds
        */
       public void setReceiveTimeout(int seconds) {
           this.receiveTimeout = seconds;
       }
   
   }

   
6. 请检查我们完整的用户指南

注意：虽然这个版本包含了特定的第三方产品，如RDBMS软件和JMS代理软件，请注意，AtomikosTransactionsEssentials绝不是仅限制在这些特定的产品，除了RDBMS软件和JMS代理软件大多数的其他软件依然兼容。

J2SE实例：examples/jse这个文件夹包含带有源代码的各种各样的例子。可以执行这个脚本来运行这个程序（示例程序只有文本输出，而没有图形化界面输出）

         运行示例前最好安装Ant，然后打开命令窗口在 examples/jse 文件夹并且输入“ant”。

Linux/Unix/Mac OSX Note：在这些系统，你必须在终端输入'chmod u+x *.sh'命令，否则，示例将无法运行。

解决问题：偶尔，一些示例可能不能再继续启动使用（尽管在开始阶段可以正常运行），这个通常是由于进程原因引起的（比如JMS代理后台环境），关闭这期间的所有进程便会解决这个问题，或者，重新启动计算机，也可以解决这个问题。

在Spring中使用：Atomikos TransactionEssentials可以很方便的于Spring相结合，运行您程序使用企业级的J2EE应用程序，而不需要EJB甚至EJB容器。另外，我们额外提供了一个强大的功能，JMS消息驱动添加到Spring的内置特性。

         查看examples/spring文件夹，将展示Atomikos TransactionEssentials如何配置基于Spring的应用程序。

在J2EE的web容器中使用：在您的J2EE应用程序环境中使用Atomikos TransactionsEssentials最简单的方法是通过Spring作为pico-container（组件容器），如果想获取更多信息，请到Spring处查看。

Javadoc：

http://www.atomikos.com/downloads/transactions-essentials/com/atomikos/AtomikosTransactionsEssentials/javadoc/3.7/index.html