activemq-artemis/docs/user-manual/zh/appserver-integration.xml

<?xml version="1.0" encoding="UTF-8"?>
<!-- ============================================================================= -->
<!-- Copyright © 2009 Red Hat, Inc. and others.                                    -->
<!--                                                                               -->
<!-- The text of and illustrations in this document are licensed by Red Hat under  -->
<!-- a Creative Commons Attribution–Share Alike 3.0 Unported license ("CC-BY-SA"). -->
<!--                                                                               -->
<!-- An explanation of CC-BY-SA is available at                                    -->
<!--                                                                               -->
<!--            http://creativecommons.org/licenses/by-sa/3.0/.                    -->
<!--                                                                               -->
<!-- In accordance with CC-BY-SA, if you distribute this document or an adaptation -->
<!-- of it, you must provide the URL for the original version.                     -->
<!--                                                                               -->
<!-- Red Hat, as the licensor of this document, waives the right to enforce,       -->
<!-- and agrees not to assert, Section 4d of CC-BY-SA to the fullest extent        -->
<!-- permitted by applicable law.                                                  -->
<!-- ============================================================================= -->
<chapter id="appserver-integration">
    <title>Java EE和应用服务器的集成</title>
    <para>ActiveMQ可以容易地安装到JBoss 4应用服务器及其以上版本。有关安装的详细说明请参阅快速指南。</para>
    <para>ActiveMQ提供了一个JCA适配器，使得它还可以与其它JEE兼容的应用服务器集成。请参阅其它应用服务器的
          有关JCA适配器集成的说明来操作。</para>
    <para>JCA适配器的作用是控制消息流入到消息Bean（MDB），并控制消息从各种JEE模块中发出（如EJB和Servlet）。</para>
    <para>本章讲述这些JEE模块配置ActiveMQ的基本信息。</para>
    <section>
        <title>配置消息Bean</title>
        <para>使用ActiveMQ向MDB传递消息，需要在文件<literal>ra.xml</literal>中配置JCA适配器。该文件在
            <literal>jms-ra.rar</literal>文件中。默认配置下ActiveMQ服务使用InVm连接器接收消息。在本章
            后面列出了可配置的选项。</para>
        <para>所有MDB都需要有目标类型和目标的相关配置。下面就是一个使用annotation配置MDB的例子：</para>
        <programlisting>@MessageDriven(name = "MDBExample",
               activationConfig =
                     {
                        @ActivationConfigProperty(propertyName = "destinationType", propertyValue = "javax.jms.Queue"),
                        @ActivationConfigProperty(propertyName = "destination", propertyValue = "queue/testQueue")
                     })
@ResourceAdapter("activemq-ra.rar")
public class MDBExample implements MessageListener
{
   public void onMessage(Message message)...
}</programlisting>
        <para>上例中配置了MDB从一个队列中接收消息，它的JNDI绑定名为<literal>queue/testQueue</literal>。
            这个队列必须事先在ActiveMQ服务器配置文件中配置并部署好的。</para>
        <para><literal>ResourceAdapter</literal> annotation用来指出使用哪个适配器。要使用它必须要引入
            <literal>org.jboss.ejb3.annotation.ResourceAdapter</literal> （JBoss AS 5.x或以上）。
            这个类在
            <literal>jboss-ejb3-ext-api.jar</literal>文件中。该文件可以在JBoss的repository中找到。
            另外一个方法是使用部署描述文件（deployment descriptor），即在文件<literal
            >jboss.xml</literal>中加入类似以下的内容：
<programlisting>&lt;message-driven>
   &lt;ejb-name>ExampleMDB&lt;/ejb-name>
   &lt;resource-adapter-name>activemq-ra.rar&lt;/resource-adapter-name>
&lt;/message-driven>
</programlisting>你还可以将activemq-ra.rar改名为jms-ra.rar而不需要任何annotation或额外的部署描述信息。但是你需要
            编辑<literal>jms-ds.xml</literal>文件，将其中的<literal>rar-name</literal>项改成相应的值。</para>
        <note>
           <para>ActiveMQ是JBoss AS 6默认的JMS提供者。从这个版本开始ActiveMQ的资源适配器名字是
               <literal>jms-ra.rar</literal>，并且你不需要在MDB的annotation中指定它。</para>
        </note>
        <para>ActiveMQ发布包中的所有例子都使用annotation方法。</para>
        <section>
            <title>使用容器管理事务（CMT）</title>
            <para>当MDB使用容器管理事务时，消息的传递被包含在一个JTA事务中。事务的提交与回滚是由容器来控制的。如果事务
                被回滚，消息传递会进行相应的处理（默认是重新传递消息，如果重新传递次数超过10次，消息就被发往DLQ）。使用
                annotation配置如下：</para>
            <programlisting>@MessageDriven(name = "MDB_CMP_TxRequiredExample",
               activationConfig =
                     {
                        @ActivationConfigProperty(propertyName = "destinationType", propertyValue = "javax.jms.Queue"),
                        @ActivationConfigProperty(propertyName = "destination", propertyValue = "queue/testQueue")
                     })
@TransactionManagement(value= TransactionManagementType.CONTAINER)
@TransactionAttribute(value= TransactionAttributeType.REQUIRED)
@ResourceAdapter("activemq-ra.rar")
public class MDB_CMP_TxRequiredExample implements MessageListener
{
   public void onMessage(Message message)...
}</programlisting>
            <para><literal>TransactionManagement</literal> 表示这个MDB使用容器管理持久性。
                <literal>TransactionAttribute</literal> 表示这个MDB要求JTA事务。注意这个annotation的
                另外唯一的合法值是<literal>TransactionAttributeType.NOT_SUPPORTED</literal>，它表示
                MDB不需要JTA事务支持。</para>
            <para>如果要回滚事务，可以调用<literal>MessageDrivenContext</literal>的
                <literal>setRollbackOnly</literal>方法。如下面的代码所示：</para>
            <programlisting>   @Resource
   MessageDrivenContextContext ctx;

   public void onMessage(Message message)
   {
      try
      {
         //something here fails
      }
      catch (Exception e)
      {
         ctx.setRollbackOnly();
      }
   }</programlisting>
            <para>如果你不需要使用XA事务，你可以用一相本地的事务来代替（比如你只有一个JMS资源）。
                如下所示：</para>
            <programlisting>@MessageDriven(name = "MDB_CMP_TxLocalExample",
               activationConfig =
                     {
                           @ActivationConfigProperty(propertyName = "destinationType", propertyValue = "javax.jms.Queue"),
                           @ActivationConfigProperty(propertyName = "destination", propertyValue = "queue/testQueue"),
                           @ActivationConfigProperty(propertyName = "useLocalTx", propertyValue = "true")
                     })
@TransactionManagement(value = TransactionManagementType.CONTAINER)
@TransactionAttribute(value = TransactionAttributeType.NOT_SUPPORTED)
@ResourceAdapter("activemq-ra.rar")
public class MDB_CMP_TxLocalExample implements MessageListener
{
   public void onMessage(Message message)...
}</programlisting>
        </section>
        <section>
            <title>使用Bean管理事务（BMT）</title>
            <para>消息Bean可以通过配置使用Bean管理的事务（BMT）。在种情况下会创建一个用户事务
                （User Transaction）。如下所示：</para>
            <programlisting>@MessageDriven(name = "MDB_BMPExample",
               activationConfig =
                     {
                        @ActivationConfigProperty(propertyName = "destinationType", propertyValue = "javax.jms.Queue"),
                        @ActivationConfigProperty(propertyName = "destination", propertyValue = "queue/testQueue"),
                        @ActivationConfigProperty(propertyName = "acknowledgeMode", propertyValue = "Dups-ok-acknowledge")
                     })
@TransactionManagement(value= TransactionManagementType.BEAN)
@ResourceAdapter("activemq-ra.rar")
public class MDB_BMPExample implements MessageListener
{
   public void onMessage(Message message)
}</programlisting>
            <para>使用BMT时，消息的传递在用户事务的范围之外，它的通知模式由<literal>acknowledgeMode</literal>参数决定。
                该参数有两个合法的值，即<literal>Auto-acknowledge</literal>和<literal
                    >Dups-ok-acknowledge</literal>。请注意，由于消息的传递在事务之外，在MDB中如果发生错误消息
                是不会重新传递的。</para>
            <para>用户可以像如下所示控制事务的生命周期：</para>
            <programlisting>   @Resource
   MessageDrivenContext ctx;

   public void onMessage(Message message)
   {
      UserTransaction tx;
      try
      {
         TextMessage textMessage = (TextMessage)message;

         String text = textMessage.getText();

         UserTransaction tx = ctx.getUserTransaction();

         tx.begin();
         
         //do some stuff within the transaction

         tx.commit();

      }
      catch (Exception e)
      {
         tx.rollback();
      }
   }</programlisting>
        </section>
        <section>
            <title>在MDB中使用选择器</title>
            <para>MDB可以配置消息选择器。如下所示：</para>
            <programlisting>@MessageDriven(name = "MDBMessageSelectorExample",
               activationConfig =
                     {
                        @ActivationConfigProperty(propertyName = "destinationType", propertyValue = "javax.jms.Queue"),
                        @ActivationConfigProperty(propertyName = "destination", propertyValue = "queue/testQueue"),
                        @ActivationConfigProperty(propertyName = "messageSelector", propertyValue = "color = 'RED'")
                     })
@TransactionManagement(value= TransactionManagementType.CONTAINER)
@TransactionAttribute(value= TransactionAttributeType.REQUIRED)
@ResourceAdapter("activemq-ra.rar")
public class MDBMessageSelectorExample implements MessageListener
{
   public void onMessage(Message message)....
}</programlisting>
        </section>
    </section>
    <section>
        <title>在JEE模块内发送消息</title>
        <para>JCA适配器支持发送消息。连接工厂的默认配置在<literal>jms-ds.xml</literal>文件中，对应的JNDI名字是
            <literal>java:/JmsXA</literal>。在JEE中使用它发送消息将作为JTA事务的一部分来对待。</para>
        <para>如果消息发送失败，整个事务将回滚，消息会被重新发送。下面是一个MDB发送消息的例子：</para>
        <programlisting>@MessageDriven(name = "MDBMessageSendTxExample",
               activationConfig =
                     {
                        @ActivationConfigProperty(propertyName = "destinationType", propertyValue = "javax.jms.Queue"),
                        @ActivationConfigProperty(propertyName = "destination", propertyValue = "queue/testQueue")
                     })
@TransactionManagement(value= TransactionManagementType.CONTAINER)
@TransactionAttribute(value= TransactionAttributeType.REQUIRED)
@ResourceAdapter("activemq-ra.rar")
public class MDBMessageSendTxExample implements MessageListener
{
   @Resource(mappedName = "java:/JmsXA")
   ConnectionFactory connectionFactory;

   @Resource(mappedName = "queue/replyQueue")
   Queue replyQueue;

   public void onMessage(Message message)
   {
      Connection conn = null;
      try
      {
         //Step 9. We know the client is sending a text message so we cast
         TextMessage textMessage = (TextMessage)message;

         //Step 10. get the text from the message.
         String text = textMessage.getText();

         System.out.println("message " + text);

         conn = connectionFactory.createConnection();

         Session sess = conn.createSession(false, Session.AUTO_ACKNOWLEDGE);

         MessageProducer producer = sess.createProducer(replyQueue);

         producer.send(sess.createTextMessage("this is a reply"));

      }
      catch (Exception e)
      {
         e.printStackTrace();
      }
      finally
      {
         if(conn != null)
         {
            try
            {
               conn.close();
            }
            catch (JMSException e)
            { 
            }
         }
      }
   }
   }</programlisting>
        <para>在JBoss应用服务器的EJB（包括会话Bean, 实体Bean和消息Bean）、Servlet（包括jsp）我定制的MBean中
            都可以使用JMS的JCA适配器来发送消息。</para>
    </section>
    <section>
      <title>MDB与接收池的大小</title>
      <para>包括JBoss在内的绝大多数应用服务器允许用户定义一个池中的MDB数量。在JBoss中这个参数名是<literal>MaxPoolSize</literal>，它在文件
         ejb3-interceptors-aop.xml中配置。这个参数不影响实际创建的会话／接收者的数量。资源适配器不知道MDB的具体实现。所以即使你设置MDB池在大小
         为1，仍然会有15个会话／接收者被创建（默认值）。如果你想改变会话／接收者创建的数量，你可以通过设置资源适配器的参数
         <literal>maxSession</literal>实现。也可以通过设置MDB的激活配置参数来完成：</para>
        <programlisting>@MessageDriven(name = "MDBMessageSendTxExample",
               activationConfig =
                     {
                        @ActivationConfigProperty(propertyName = "destinationType", propertyValue = "javax.jms.Queue"),
                        @ActivationConfigProperty(propertyName = "destination", propertyValue = "queue/testQueue"),
                        @ActivationConfigProperty(propertyName = "maxSession", propertyValue = "1")
                     })
@TransactionManagement(value= TransactionManagementType.CONTAINER)
@TransactionAttribute(value= TransactionAttributeType.REQUIRED)
@ResourceAdapter("activemq-ra.rar")
public class MyMDB implements MessageListener
{ ....}
      </programlisting>
   </section>
    <section>
        <title>配置JCA适配器</title>
        <para>通过JCA适配器可以将ActiveMQ集成到JEE兼容的模块中，如MDB和EJB。它的配置决定了这些模块如何接收和发送消息。</para>
        <para>ActiveMQ的JCA适配器是通过<literal>jms-ra.rar</literal>部署的。它的配置文件中其中的
              <literal>META-INF/ra.xml</literal>。</para>
        <para>下面是它的具体配置内容：</para>
        <programlisting>&lt;resourceadapter>
      &lt;resourceadapter-class>org.apache.activemq.ra.ActiveMQResourceAdapter&lt;/resourceadapter-class>
      &lt;config-property>
         &lt;description>The transport type&lt;/description>
         &lt;config-property-name>ConnectorClassName&lt;/config-property-name>
         &lt;config-property-type>java.lang.String&lt;/config-property-type>
         &lt;config-property-value>org.apache.activemq.core.remoting.impl.invm.InVMConnectorF
         actory&lt;/config-property-value>
      &lt;/config-property>
      &lt;config-property>
         &lt;description>The transport configuration. These values must be in the form of key=val;key=val;&lt;/description>
         &lt;config-property-name>ConnectionParameters&lt;/config-property-name>
         &lt;config-property-type>java.lang.String&lt;/config-property-type>
         &lt;config-property-value>server-id=0&lt;/config-property-value>
      &lt;/config-property>

      &lt;outbound-resourceadapter>
         &lt;connection-definition>
            &lt;managedconnectionfactory-class>org.apache.activemq.ra.ActiveMQRAManagedConnection
            Factory&lt;/managedconnectionfactory-class>

            &lt;config-property>
               &lt;description>The default session type&lt;/description>
               &lt;config-property-name>SessionDefaultType&lt;/config-property-name>
               &lt;config-property-type>java.lang.String&lt;/config-property-type>
               &lt;config-property-value>javax.jms.Queue&lt;/config-property-value>
            &lt;/config-property>
            &lt;config-property>
               &lt;description>Try to obtain a lock within specified number of seconds; less
               than or equal to 0 disable this functionality&lt;/description>
               &lt;config-property-name>UseTryLock&lt;/config-property-name>
               &lt;config-property-type>java.lang.Integer&lt;/config-property-type>
               &lt;config-property-value>0&lt;/config-property-value>
            &lt;/config-property>

            &lt;connectionfactory-interface>org.apache.activemq.ra.ActiveMQRAConnectionFactory
            &lt;/connectionfactory-interface>
            &lt;connectionfactororg.apache.activemq.ra.ActiveMQConnectionFactoryImplonFactoryImpl
            &lt;/connectionfactory-impl-class>
            &lt;connection-interface>javax.jms.Session&lt;/connection-interface>
            &lt;connection-impl-class>org.apache.activemq.ra.ActiveMQRASession
            &lt;/connection-impl-class>
         &lt;/connection-definition>
         &lt;transaction-support>XATransaction&lt;/transaction-support>
         &lt;authentication-mechanism>
            &lt;authentication-mechanism-type>BasicPassword
            &lt;/authentication-mechanism-type>
            &lt;credential-interface>javax.resource.spi.security.PasswordCredential
            &lt;/credential-interface>
         &lt;/authentication-mechanism>
         &lt;reauthentication-support>false&lt;/reauthentication-support>
      &lt;/outbound-resourceadapter>

      &lt;inbound-resourceadapter>
         &lt;messageadapter>
            &lt;messagelistener>
               &lt;messagelistener-type>javax.jms.MessageListener&lt;/messagelistener-type>
               &lt;activationspec>
                  &lt;activationspec-class>org.apache.activemq.ra.inflow.ActiveMQActivationSpec
                  &lt;/activationspec-class>
                  &lt;required-config-property>
                      &lt;config-property-name>destination&lt;/config-property-name>
                  &lt;/required-config-property>
               &lt;/activationspec>
            &lt;/messagelistener>
         &lt;/messageadapter>
      &lt;/inbound-resourceadapter>

   &lt;/resourceadapter></programlisting>
        <para>整个配置可以分为三个主要部分</para>
        <orderedlist>
            <listitem>
                <para>适配器的全局参数</para>
            </listitem>
            <listitem>
                <para>适配器外部（outbound）配置。用于在JEE环境中创建JMS资源。</para>
            </listitem>
            <listitem>
                <para>适配器内部（inbound）配置。用于控制MDB的消息接收。 </para>
            </listitem>
        </orderedlist>
        <section>
            <title>适配器的全局参数</title>
            <para>首先看到的第一个参数是<literal>resourceadapter-class</literal>。这是ActiveMQ
                的适配器类。此参数不可更改。</para>
            <para>在此之后是可配置的参数。前两个配置适配器所使用的传输。其余的用来配置连接工厂。</para>
            <note><para>所有连接工厂的参数在没有定义时使用默认值。参数<literal>reconnectAttempts</literal>
                        的默认值取-1，表示如果连接失败，ActiveMQ会不停地尝试重新连接。这个参数只适用于创建远程
                        连接的情况。如果是InVm连接器，则永远不可能发生连接故障。</para></note>
            <para>下面给出了每个参数的说明：</para>
            <table frame="topbot" border="2">
                <title>全局配置参数</title>
                <tgroup cols="3">
                    <colspec colname="c1" colnum="1"/>
                    <colspec colname="c2" colnum="2"/>
                    <colspec colname="c3" colnum="3"/>
                    <thead>
                        <row>
                            <entry>参数名</entry>
                            <entry>参数类型</entry>
                            <entry>参数说明</entry>
                        </row>
                    </thead>
                    <tbody>
                        <row>
                            <entry>ConnectorClassName</entry>
                            <entry>String</entry>
                            <entry>连接器的类名，参见 <xref
                                    linkend="configuring-transports"/></entry>
                        </row>
                        <row>
                            <entry>ConnectionParameters</entry>
                            <entry>String</entry>
                            <entry>传输配置参数。它的值必须是采用
                                <literal>key1=val1;key2=val2;</literal>的形式。不同连接器有不同的参数。</entry>
                        </row>
                        <row>
                            <entry>useLocalTx</entry>
                            <entry>boolean</entry>
                            <entry>设为True，则进行本地事务优化。</entry>
                        </row>
                        <row>
                            <entry>UserName</entry>
                            <entry>String</entry>
                            <entry>用于创建连接时使用的用户名</entry>
                        </row>
                        <row>
                            <entry>Password</entry>
                            <entry>String</entry>
                            <entry>用于创建连接时使用的用户密码</entry>
                        </row>
                        <row>
                            <entry>BackupConnectorClassName</entry>
                            <entry>String</entry>
                            <entry>发生故障是使用的备份传输</entry>
                        </row>
                        <row>
                            <entry>BackupConnectionParameters</entry>
                            <entry>String</entry>
                            <entry>备份传输的配置参数</entry>
                        </row>
                        <row>
                            <entry><link linkend="configuration.discovery-group.group-address">DiscoveryAddress</link></entry>
                            <entry>String</entry>
                            <entry>服务器自动检测所使用的发现组（discovery group）地址</entry>
                        </row>
                        <row>
                            <entry><link linkend="configuration.discovery-group.group-port">DiscoveryPort</link></entry>
                            <entry>Integer</entry>
                            <entry>检测所使用的端口号</entry>
                        </row>
                        <row>
                            <entry><link linkend="configuration.discovery-group.refresh-timeout">DiscoveryRefreshTimeout</link></entry>
                            <entry>Long</entry>
                            <entry>刷新的时间（timeout）。单位为毫秒</entry>
                        </row>
                        <row>
                            <entry>
                               <link linkend="configuration.connection-factory.discovery-initial-wait-timeout">
                                  DiscoveryInitialWaitTimeout
                               </link>
                            </entry>
                            <entry>Long</entry>
                            <entry>检测之前所需等待的时间</entry>
                        </row>
                        <row>
                            <entry>
                               <link linkend="configuration.connection-factory.connection-load-balancing-policy-class-name">
                                  ConnectionLoadBalancingPolicyClassName</link>
                            </entry>
                                   <entry>String</entry>
                            <entry>负载均衡策略使用的类</entry>
                        </row>
                        <row>
                            <entry>
                               <link linkend="configuration.connection-factory.discovery-initial-wait-timeout">
                                  DiscoveryInitialWaitTimeout
                               </link>
                            </entry>
                            <entry>Long</entry>
                            <entry>向服务器发送ping的周期，单位毫秒</entry>
                        </row>
                        <row>
                            <entry>
                               <link linkend="configuration.connection-factory.connection-ttl">ConnectionTTL</link>
                            </entry>
                            <entry>Long</entry>
                            <entry>连接的存活时间（TTL）</entry>
                        </row>
                        <row>
                            <entry>
                               <link linkend="configuration.connection-factory.call-timeout">CallTimeout</link>
                            </entry>
                            <entry>Long</entry>
                            <entry>每个数据包的调用超时。单位毫秒</entry>
                        </row>
                        <row>
                            <entry>
                               <link linkend="configuration.connection-factory.dups-ok-batch-size">DupsOKBatchSize</link>
                            </entry>
                            <entry>Integer</entry>
                            <entry>Dups OK的情况下消息批量的大小。</entry>
                        </row>
                        <row>
                            <entry>
                               <link linkend="configuration.connection-factory.transaction-batch-size">TransactionBatchSize</link>
                            </entry>
                            <entry>Integer</entry>
                            <entry>在事务中发送消息的批量大小</entry>
                        </row>
                        <row>
                            <entry>
                               <link linkend="configuration.connection-factory.consumer-window-size">ConsumerWindowSize</link>
                            </entry>
                            <entry>Integer</entry>
                            <entry>接收者内部缓存的窗口大小</entry>
                        </row>
                    </tbody>
                </tgroup>
            </table>
            <para>接上页..</para>
            <informaltable frame="topbot">
                <tgroup cols="3">
                    <colspec colname="c1" colnum="1"/>
                    <colspec colname="c2" colnum="2"/>
                    <colspec colname="c3" colnum="3"/>
                    <tbody>
                        <row>
                            <entry>
                               <link linkend="configuration.connection-factory.consumer-max-rate">ConsumerMaxRate</link>
                            </entry>
                            <entry>Integer</entry>
                            <entry>接收者接收消息的最大速度</entry>
                        </row>
                        <row>
                            <entry>
                               <link linkend="configuration.connection-factory.confirmation-window-size">ConfirmationWindowSize</link>
                            </entry>
                            <entry>Integer</entry>
                            <entry>用于确认的窗口大小</entry>
                        </row>
                        <row>
                            <entry>
                               <link linkend="configuration.connection-factory.producer-max-rate">ProducerMaxRate</link>
                            </entry>
                            <entry>Integer</entry>
                            <entry>发送者发送消息的最大速度</entry>
                        </row>
                        <row>
                            <entry>
                               <link linkend="configuration.connection-factory.min-large-message-size">MinLargeMessageSize</link>
                            </entry>
                            <entry>Integer</entry>
                            <entry>大消息的最小数值，单位字节。</entry>
                        </row>
                        <row>
                            <entry>
                               <link linkend="configuration.connection-factory.block-on-acknowledge">BlockOnAcknowledge</link>
                            </entry>
                            <entry>Boolean</entry>
                            <entry>如果为true，表示以阻塞方法发送消息通知。</entry>
                        </row>
                        <row>
                            <entry>
                               <link linkend="configuration.connection-factory.block-on-non-durable-send">BlockOnNonDurableSend</link>
                            </entry>
                            <entry>Boolean</entry>
                            <entry>如果为true，表示以阻塞方式发送非持久消息</entry>
                        </row>
                        <row>
                            <entry>
                               <link linkend="configuration.connection-factory.block-on-durable-send">BlockOnDurableSend</link>
                            </entry>
                            <entry>Boolean</entry>
                            <entry>如果为true，表示以阻塞方式发送持久消息</entry>
                        </row>
                        <row>
                            <entry>
                               <link linkend="configuration.connection-factory.auto-group">AutoGroup</link>
                            </entry>
                            <entry>Boolean</entry>
                            <entry>如果为true，表示自动消息分组</entry>
                        </row>
                        <row>
                            <entry>
                               <link linkend="configuration.connection-factory.pre-acknowledge">PreAcknowledge</link>
                            </entry>
                            <entry>Boolean</entry>
                            <entry>决定是否进行消息的预先通知（pre-acknowledge）。</entry>
                        </row>
                        <row>
                            <entry>
                               <link linkend="configuration.connection-factory.reconnect-attempts">ReconnectAttempts</link>
                            </entry>
                            <entry>Integer</entry>
                            <entry>连接重试的次数，默认为 -1</entry>
                        </row>
                        <row>
                            <entry>
                               <link linkend="configuration.connection-factory.retry-interval">RetryInterval</link>
                            </entry>
                            <entry>Long</entry>
                            <entry>每次连接重试前等待的时间，单位毫秒。</entry>
                        </row>
                        <row>
                            <entry>
                               <link linkend="configuration.connection-factory.retry-interval-multiplier">RetryIntervalMultiplier</link>
                            </entry>
                            <entry>Double</entry>
                            <entry>用于计算重试间隔</entry>
                        </row>
                        <row>
                            <entry>
                               <link linkend="configuration.connection-factory.failover-on-server-shutdown">FailoverOnServerShutdown</link>
                            </entry>
                            <entry>Boolean</entry>
                            <entry>如果设为true表示尝试连接其它的服务器</entry>
                        </row>
                        <row>
                            <entry>
                               <link linkend="configuration.connection-factory.client-id">ClientID</link>
                            </entry>
                            <entry>String</entry>
                            <entry>连接的客户端ID</entry>
                        </row>
                        <row>
                            <entry>
                               <link linkend="configuration.connection-factory.client-failure-check-period">ClientFailureCheckPeriod</link>
                            </entry>
                            <entry>Long</entry>
                            <entry>客户端如果在这个时间内没有收到服务器数据包，将认为连接出现故障。</entry>
                        </row>
                        <row>
                            <entry>
                               <link linkend="configuration.connection-factory.use-global-pools">UseGlobalPools</link>
                            </entry>
                            <entry>Boolean</entry>
                            <entry>是否使用全局线程池</entry>
                        </row>
                        <row>
                            <entry>
                               <link linkend="configuration.connection-factory.scheduled-thread-pool-max-size">ScheduledThreadPoolMaxSize</link>
                            </entry>
                            <entry>Integer</entry>
                            <entry><emphasis>可计划线程池</emphasis>的最大线程数</entry>
                        </row>
                        <row>
                            <entry>
                               <link linkend="configuration.connection-factory.thread-pool-max-size">ThreadPoolMaxSize</link>
                            </entry>
                            <entry>Integer</entry>
                            <entry>线程池的大小</entry>
                        </row>
                        <row>
                            <entry>SetupAttempts</entry>
                            <entry>Integer</entry>
                            <entry>尝试建立JMS连接的次数（默认值是10。-1表示无限次进行尝试）。有时MDB在部署时相关的JMS资源还没有准备好，这时通过多次的
　　　　　　　　　　　　　　　　　　　尝试直到JMS资源连接上为止。只适用于内部（Inbound）连接的情况。</entry>
                        </row>
                        <row>
                            <entry>SetupInterval</entry>
                            <entry>Long</entry>
                            <entry>每两次相邻尝试之间的时间间隔，以毫秒为单位（默认值为2000毫秒）。只适用于内部（Inbound）连接的情况。</entry>
                        </row>
                    </tbody>
                </tgroup>
            </informaltable>
        </section>
        <section>
            <title>适配器外部（outbound）配置</title>
            <para>外部配置参数应该保持不变。这是因为它所定义的连接工厂要被Java EE的模块所使用。这些连接工厂
                可以定义在名字样式为<literal>*-ds.xml</literal>的配置文件中。在JBoss的部署目录
                <literal>activemq.sar</literal>下有一个默认的配置文件<literal>jms-ds.xml</literal>。
                在这个文件中的连接工厂的配置从主要的配置文件<literal>ra.xml</literal>中继承，
                但是可以在这里重新定义。下面的例子中给出了重新定义的方法。</para>
            <note>
            <para>请注意这里的配置只适用于在JBoss应用服务器中安装的ActiveMQ。如果要在其它JEE应用服务器中
                使用并配置ActiveMQ，请参照相应的应用服务器手册。</para>
            </note>
            <programlisting>&lt;tx-connection-factory>
      &lt;jndi-name>RemoteJmsXA&lt;/jndi-name>
      &lt;xa-transaction/>
      &lt;rar-name>jms-ra.rar&lt;/rar-name>
      &lt;connection-definition>org.apache.activemq.ra.ActiveMQRAConnectionFactory
&lt;/connection-definition>
      &lt;config-property name="SessionDefaultType" type="String">javax.jms.Topic
      &lt;/config-property>
      &lt;config-property name="ConnectorClassName" type="String">
        org.apache.activemq.core.remoting.impl.netty.NettyConnectorFactory
      &lt;/config-property>
      &lt;config-property name="ConnectionParameters" type="String">
          port=5445&lt;/config-property>
      &lt;max-pool-size>20&lt;/max-pool-size>
&lt;/tx-connection-factory></programlisting>
            <para>上面的例子中的连接工厂绑定到JNDI名字<literal>RemoteJmsXA</literal>。EJB和MDB可以用
                下面的方法来得到它：</para>
            <programlisting>@Resource(mappedName="java:RemoteJmsXA")
private ConnectionFactory connectionFactory;</programlisting>
            <para><literal>config-property</literal>覆盖了<literal>ra.xml</literal>文件中的配置。
                以此类推，其它有关连接工厂的参数也可以在此覆盖。</para>
            <para>除了全局的配置参数外，外部的配置还定义了其它一些参数。</para>

            <table frame="topbot" border="2">
                <title>外部配置参数</title>
                <tgroup cols="3">
                    <colspec colname="c1" colnum="1"/>
                    <colspec colname="c2" colnum="2"/>
                    <colspec colname="c3" colnum="3"/>
                    <thead>
                        <row>
                            <entry>参数名</entry>
                            <entry>参数类型</entry>
                            <entry>说明</entry>
                        </row>
                    </thead>
                    <tbody>
                        <row>
                            <entry>SessionDefaultType</entry>
                            <entry>String</entry>
                            <entry>默认的会话类型</entry>
                        </row>
                        <row>
                            <entry>UseTryLock</entry>
                            <entry>Integer</entry>
                            <entry>在规定的秒数内获得锁。如果不想使用这个功能，将它设为0或负数</entry>
                        </row>
                     </tbody>
                  </tgroup>
               </table>
        </section>
        <section>
            <title>适配器内部（inbound）配置</title>
            <para>内部配置参数也应该保持不变。它们控制向MDB转发消息的各种属性。通过在MDB上添加相应的激活配置
                （activation configuration）可以覆盖这些参数的值。它可以用来配置一个MDB从另外一个服务器
                接收消息。</para>
                <para>除了全局的配置参数外，内部的配置还定义了其它一些参数。</para>

                <table frame="topbot" border="2">
                    <title>Inbound Configuration Properties</title>
                    <tgroup cols="3">
                        <colspec colname="c1" colnum="1"/>
                        <colspec colname="c2" colnum="2"/>
                        <colspec colname="c3" colnum="3"/>
                        <thead>
                            <row>
                            <entry>参数名</entry>
                            <entry>参数类型</entry>
                            <entry>说明</entry>
                            </row>
                        </thead>
                        <tbody>
                            <row>
                                <entry>Destination</entry>
                                <entry>String</entry>
                                <entry>目标的JNDI名字</entry>
                            </row>
                            <row>
                                <entry>DestinationType</entry>
                                <entry>String</entry>
                                <entry>目标的类型，<literal>javax.jms.Queue</literal>或者<literal>javax.jms.Topic</literal>
                                 (默认是javax.jms.Queue)</entry>
                            </row>
                            <row>
                                <entry>AcknowledgeMode</entry>
                                <entry>String</entry>
                                <entry>通知模式，<literal>Auto-acknowledge</literal> 或 <literal>Dups-ok-acknowledge</literal>
                                (默认值是Auto-acknowledge). <literal>AUTO_ACKNOWLEDGE</literal>和<literal>DUPS_OK_ACKNOWLEDGE</literal>也是有效值</entry>
                            </row>
                            <row>
                                <entry>MaxSession</entry>
                                <entry>Integer</entry>
                                <entry>内部配置创建的最大会话数（默认是5）</entry>
                            </row>
                            <row>
                                <entry>MessageSelector</entry>
                                <entry>String</entry>
                                <entry>接收者的消息选择器</entry>
                            </row>
                            <row>
                                <entry>SubscriptionDurability</entry>
                                <entry>String</entry>
                                <entry>订阅的类型，<literal>Durable</literal>或者<literal>NonDurable</literal></entry>
                            </row>
                            <row>
                                <entry>SubscriptionName</entry>
                                <entry>String</entry>
                                <entry>订阅的名字</entry>
                            </row>
                            <row>
                                <entry>TransactionTimeout</entry>
                                <entry>Long</entry>
                                <entry>事务超时（毫秒，默认是0，表示事务不会超时）</entry>
                            </row>
                            <row>
                                <entry>UseJNDI</entry>
                                <entry>Boolean</entry>
                                <entry>是否使用JNDI来查找目标（默认是true）</entry>
                            </row>
                         </tbody>
                      </tgroup>
                   </table>
        </section>
       <section>
          <title>配置适配器访问单独的ActiveMQ服务器</title>
          <para>在有的情况下，消息服务器与应用服务器运行在不同的机器上。这时客户端只需要安装ActiveMQ的客户端的库文件。本节给出了具体的配置和所需要的jar文件。</para>
          <section>
          <para>你需要配置两个配置文件。一个是MDB所用的内部适配器，另一个是可以创建外部连接的外部适配器。</para>
          <section>
                <title>配置内部适配器</title>
                <para>首先在<literal>deploy</literal>目录下创建一个以.rar为结尾的文件夹。
                      在这里我们将其命名为<literal>activemq-ra.rar</literal>。主注意这一点很重要，因为MDB和外部配置都需要引用
                      该文件夹的名字。
                </para>
                <note>
                   <para>在JBoss中该文件夹的默认名为<literal>jms-ra.rar</literal>。你可以直接使用这个名字。但是你可能需要避免
                      与其它的通用适配器相冲突。
                   </para>
                </note>
                <para>在文件夹
                   <literal>activemq-ra.rar</literal>
                   下创建名为
                   <literal>META-INF</literal>
                   的文件夹，然后在些文件夹内创建一个
                   <literal>ra.xml</literal>配置文件。在ActiveMQ发布包中
                   有一个<literal>ra.xml</literal>模板文件供你使用。
                </para>
                <para>要配置MDB接收远程ActiveMQ服务器的消息，你需要修改<literal>deploy/hornet-ra.rar/META-INF</literal>下面的
                   <literal>ra.xml</literal>文件，将传输层改为netty连接器（不要使用invm连接器）及其相应的参数。下面
                   是一个配置的例子：
                </para>

          <programlisting>
            &lt;resourceadapter-class&gt;org.apache.activemq.ra.ActiveMQResourceAdapter&lt;/resourceadapter-class&gt;
              &lt;config-property&gt;
                 &lt;description&gt;The transport type&lt;/description&gt;
                 &lt;config-property-name&gt;ConnectorClassName&lt;/config-property-name&gt;
                 &lt;config-property-type&gt;java.lang.String&lt;/config-property-type&gt;
                 &lt;config-property-value&gt;org.apache.activemq.core.remoting.impl.netty.NettyConnectorFactory&lt;/config-property-value&gt;
              &lt;/config-property&gt;
              &lt;config-property&gt;
                 &lt;description&gt;The transport configuration. These values must be in the form of key=val;key=val;&lt;/description&gt;
                 &lt;config-property-name&gt;ConnectionParameters&lt;/config-property-name&gt;
                 &lt;config-property-type&gt;java.lang.String&lt;/config-property-type&gt;
                 &lt;config-property-value&gt;host=127.0.0.1;port=5446&lt;/config-property-value&gt;
              &lt;/config-property>
          </programlisting>
          <para>上面的配置中，适配器连接到一个运行在本机上端口为5446的服务器。</para>
          </section>

          <section>
             <title>配置外部适配器</title>
                <para>你还需要创建一个<literal>activemq-ds.xml</literal>文件来配置外部连接。该文件需要放置在<literal>deploy</literal>
                   下的任意一个文件夹中。在一相标准的安装中这个文件夹是<literal>horneq</literal> 或者 <literal>activemq.sar</literal>。
                   当然你可以选择其它文件夹。该文件的名字只要是以<literal>-ds.xml</literal>即可。在ActiveMQ的发布包中包含有一个模板文件，
                   它的名字是<literal>jms-ds.xml</literal>，位置就在config文件夹下。
                </para>
          <para>下面是一个配置的例子。</para>
          <programlisting>
             &lt;tx-connection-factory&gt;
              &lt;jndi-name&gt;RemoteJmsXA&lt;/jndi-name&gt;
              &lt;xa-transaction/&gt;
              &lt;rar-name&gt;activemq-ra.rar&lt;/rar-name&gt;
              &lt;connection-definition&gt;org.apache.activemq.ra.ActiveMQRAConnectionFactory&lt;/connection-definition&gt;
              &lt;config-property name="SessionDefaultType" type="java.lang.String"&gt;javax.jms.Topic&lt;/config-property&gt;
              &lt;config-property name="ConnectorClassName" type="java.lang.String"&gt;org.apache.activemq.core.remoting.impl.netty.NettyConnectorFactory&lt;/config-property&gt;
              &lt;config-property name="ConnectionParameters" type="java.lang.String"&gt;host=127.0.0.1;port=5446&lt;/config-property&gt;
              &lt;max-pool-size&gt;20&lt;/max-pool-size&gt;
           &lt;/tx-connection-factory&gt;
          </programlisting>
          <para>这个配置同样是连接到运行在本机上的端口为5446的ActiveMQ服务器。JEE模块可以通过JNDI查找
                <literal>java:/RemoteJmsXA</literal>（由<literal>jndi-name</literal>参数定义）。如上节所述，
                资源适配器根据文件夹下的配置来创建外部连接。</para>
             <section>
                <title>依赖的jar文件</title>
                <para>下面列出了ActiveMQ所需要的第三方jar文件</para>
                <table frame="topbot" border="2">
                    <title>Jar文件</title>
                    <tgroup cols="3">
                        <colspec colname="c1" colnum="1"/>
                        <colspec colname="c2" colnum="2"/>
                        <colspec colname="c3" colnum="3"/>
                        <thead>
                            <row>
                                <entry>Jar文件名</entry>
                                <entry>说明</entry>
                                <entry>位置</entry>
                            </row>
                        </thead>
                        <tbody>
                            <row>
                                <entry>activemq-ra.jar</entry>
                                <entry>ActiveMQ资源适配器文件</entry>
                                <entry>deploy/activemq-ra.rar或相应的位置</entry>
                            </row>
                            <row>
                                <entry>activemq-core-client.jar</entry>
                                <entry>ActiveMQ核心客户类库</entry>
                                <entry>在JBoss的default/lib下或者是$JBOSS_HOME/common/lib下。 </entry>
                            </row>
                            <row>
                                <entry>activemq-jms-client.jar</entry>
                                <entry>ActiveMQ的JMS类</entry>
                                <entry>同上</entry>
                            </row>
                            <row>
                                <entry>netty.jar</entry>
                                <entry>Netty类库</entry>
                                <entry>同上</entry>
                            </row>
                        </tbody>
                     </tgroup>
                </table>
             </section>
          </section>
       </section>
    </section>
    <section>
        <title>高可获得性JNDI (HA-JNDI)</title>
        <para>采用JNDI来查找JMS对象时（队列，话题及连接工厂），使用HA－JNDI可以增加容错的能力。即当你正在使用
            的JNDI服务器发生故障时，客户端可以使用集群中的其它JNDI服务器继续工作。</para>
        <para>HA-JNDI是JBoss应用服务器的一项服务，它为客户端提供JNDI服务，客户端无需知道JNDI具体服务器的连接
            细节。这个服务只有在集群的JBoss应用服务器上才可使用。</para>
        <para>要使用HA－JNDI，需要使用下面的JNDI参数。</para>
        <programlisting>Hashtable&lt;String, String> jndiParameters = new Hashtable&lt;String, String>();
jndiParameters.put("java.naming.factory.initial", 
    "org.jnp.interfaces.NamingContextFactory");
jndiParameters.put("java.naming.factory.url.pkgs=", 
    "org.jboss.naming:org.jnp.interfaces");

initialContext = new InitialContext(jndiParameters);</programlisting>
        <para>有关HA-JNDI更多的信息请参见<ulink
                url="http://www.jboss.org/file-access/default/members/jbossas/freezone/docs/Clustering_Guide/5/html/clustering-jndi.html"
                >JBoss应用服务器集群文档</ulink>。</para>
    </section>
    <section id="xa-recovery">
        <title>XA恢复</title>
        <para><emphasis>XA恢复</emphasis>解决的是事务在系统或应用出现故障时的处理。它可以保证在应用进程或主机出现故障
            或网络崩溃等情况下，事务内所有资源的状态的一致性。有关XA恢复的更多信息请见 <ulink
                url="http://www.jboss.org/community/wiki/JBossTransactions">JBoss
                事务</ulink>。</para>
        <para>当ActiveMQ与JBoss应用服务器集成时，它可以利用JBoss的事务处理来对消息资源进行恢复。如果消息处理包括
            在一个XA事务中，如果服务器出现故障并重启时，恢复管理器将负责恢复事务，这样其中的消息要么被提交，要么被回滚（取
            决于事务的处理决定）。</para>
        <section>
            <title>XA恢复的配置</title>
            <para>要想ActiveMQ具有XA恢复功能，则必须配置恢复管理器连接到ActiveMQ并恢复其资源。下面的参数必须要加到
                <literal>conf/jbossts-properties.xml</literal>文件中的<literal>jta</literal>部分:</para>
            <programlisting>
&lt;properties depends="arjuna" name="jta"&gt;
   ...
                     
   &lt;property name="com.arjuna.ats.jta.recovery.XAResourceRecovery.ActiveMQ1"
                value="org.apache.activemq.jms.server.recovery.ActiveMQXAResourceRecovery;[连接配置]"/&gt;
&lt;/properties&gt;
            </programlisting>
            <para>其中<literal>[连接配置]</literal>包括连接ActiveMQ节点所必需的信息。
                它的格式是<literal>[连接工厂类名],[用户名], [密码], [连接参数]</literal>。 </para>
            <itemizedlist>
                <listitem>
                    <para><literal>[连接工厂类名]</literal>指的是<literal>ConnectorFactory</literal>
                        的类名，用来连接ActiveMQ服务器。其值可以是<literal
                            >org.apache.activemq.core.remoting.impl.invm.InVMConnectorFactory</literal> 或
                            <literal
                            >org.apache.activemq.core.remoting.impl.netty.NettyConnectorFactory</literal></para>
                </listitem>
                <listitem>
                    <para><literal>[用户名]</literal>是用于创建客户会话的用户名。是可选项。</para>
                </listitem>
                <listitem>
                    <para><literal>[密码]</literal>是创建客户会话时所用的密码。只有在用户名存在时需要。</para>
                </listitem>
                <listitem>
                    <para><literal>[连接参数]</literal> 是用逗号分隔的一串键－值对。它们会传递给连接器工厂
                        （参见 <xref linkend="configuring-transports"/>）。</para>
                </listitem>
            </itemizedlist>
            <note>
                <para>ActiveMQ必须有一个与<literal>conf/jbossts-properties.xml</literal>中定义的连接器相对应的接受器（acceptor）。</para>
            </note>
            <section>
                <title>配置参数</title>
                <para>如果ActiveMQ配置了一个默认的in-vm接受器：</para>
                <programlisting>
&lt;acceptor name="in-vm">
    &lt;factory-class>org.apache.activemq.core.remoting.impl.invm.InVMAcceptorFactory&lt;/factory-class>
&lt;/acceptor>
                </programlisting>
                <para>相应地在 <literal
                        >conf/jbossts-properties.xml</literal>文件中：</para>
                <programlisting>
&lt;property name="com.arjuna.ats.jta.recovery.XAResourceRecovery.HORNETQ1"
   value="org.apache.activemq.jms.server.recovery.ActiveMQXAResourceRecovery;org.apache.activemq.core.remoting.impl.invm.InVMConnectorFactory"/>
                </programlisting>
                <para>如果配置了一个netty接受器，并且端口不是默认的：</para>
                <programlisting>
&lt;acceptor name="netty">
    &lt;factory-class>org.apache.activemq.core.remoting.impl.netty.NettyConnectorFactory&lt;/factory-class>
    &lt;param key="port" value="8888"/>
&lt;/acceptor>
                </programlisting>
                <para>相应的在 <literal
                        >conf/jbossts-properties.xml</literal>文件中：</para>
                <programlisting>
&lt;property name="com.arjuna.ats.jta.recovery.XAResourceRecovery.HORNETQ1"
       value="org.apache.activemq.jms.server.recovery.ActiveMQXAResourceRecovery;org.apache.activemq.core.remoting.impl.netty.NettyConnectorFactory, , , port=8888"/>
                </programlisting>
                <note>
                    <para>注意在没有用户名和密码时，逗号是不能省略的。</para>
                </note>
                <para>如果恢复必须要求是<literal>admin, adminpass</literal>，则其配置
                    应为如下所示：</para>
                <programlisting>
                    &lt;property name="com.arjuna.ats.jta.recovery.XAResourceRecovery.HORNETQ1"
                           value="org.apache.activemq.jms.server.recovery.ActiveMQXAResourceRecovery;org.apache.activemq.core.remoting.impl.netty.NettyConnectorFactory, admin, adminpass, port=8888"/>
                </programlisting>
                <para>推荐在XA恢复中，将ActiveMQ配置一个invm接受器，并配置恢复管理器使用invm连接器。</para>
            </section>
        </section>
        <section>
            <title>例子</title>
            <para>参见<xref linkend="xa-recovery-example"/>。这个例子展示了如何来配置XA恢复以便在服务器崩溃后恢复消息。</para>
        </section>
    </section>
  </section>
</chapter>