using-jms.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="using-jms">
    <title>使用JMS</title>
    <para>很多用户喜欢使JMS，因此HornetQ提供了JMS服务。</para>
    <para>JMS是一个普遍使用API标准，绝大多数的消息系统都提供JMS接口。如果你对JMS还不熟悉，建议你先参考一下
          Sun的<ulink url="http://java.sun.com/products/jms/tutorial/1_3_1-fcs/doc/jms_tutorialTOC.html">
            JMS 教程</ulink>。</para>
    <para>HornetQ还提供了许多的JMS的示例程序（examples）。比如简单的JMS Queue和Topic的示例，就很适合初学者做为了
          解HornetQ JMS的起点。<xref linkend="examples"/>对这些示例作了详细的说明。</para>
    <para>下面我们将带领读者一步步地配置HornetQ的JMS服务，并创建一个简单的JMS程序。我们还将展示如何在没有JNDI的情况下
          来使用HornetQ中的JMS。</para>
    <section>
        <title>一个简单的订购系统</title>
        <para>本章我们将用一个简单的订购系统做为一个例子。尽管它十分简单，但是它能够很好地向大家展示JMS的设置和使用。</para>
        <para>本例中有一个名为 <literal>OrderQueue</literal>JMS队列，还将有一个 <literal>MessageProducer</literal> 
              用来向队列发送订购消息。发送到队列的消息由一个 <literal>MessageConsumer</literal> 来接收。</para>
        <para>我们所用的队列是<literal>持久（durable）</literal>的队列，也就是说这个队列不受服务器故障的影响。当服务器
              发生故障重新启动后，这个队列仍然存在。我们需要把这个队列事先部署好。办法就是将队列写到JMS的配置文件中。当服务启动
              时将配置文件中的队列自动部署好。</para>
    </section>
    <section id="using-jms.server.configuration">
        <title>JMS服务的配置</title>
        <para><literal>hornetq-jms.xml</literal>文件包含了需要创建与部署的JMS Queue，Topic和ConnectionFactory
            的实例。该文件必须要指定在classpath中。从这个文件中部署好的对象都可以用JNDI来找到。</para>
        <para>JMS客户端可以利用JMS ConnectionFactory对象来创建与服务器的连接。ConnectionFactory中有关于服务器地址的
              信息以及各种参数。通常使用这些参数的默认值即可。</para>
        <para>这里我们将要在服务器端部署一个JMS队列和一个JMS ConnectionFactory （连接工厂）。当然完全可以部署多个JMS对象。
              下面给出了具体的配置内容：</para>
        <programlisting>
&lt;configuration xmlns="urn:hornetq" 
    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
    xsi:schemaLocation="urn:hornetq ../schemas/hornetq-jms.xsd "&gt;
    
    &lt;connection-factory name="ConnectionFactory"&gt;
        &lt;connectors>
           &lt;connector-ref connector-name="netty"/&gt;
        &lt;/connectors>
        &lt;entries&gt;
            &lt;entry name="ConnectionFactory"/&gt;           
        &lt;/entries&gt;
    &lt;/connection-factory&gt;
    
    &lt;queue name="OrderQueue"&gt;
        &lt;entry name="queues/OrderQueue"/&gt;
    &lt;/queue&gt;
    
&lt;/configuration&gt; 
        </programlisting>
        <para>在本文件中我们部署了一个名为 <literal>ConnectionFactory</literal> 的一个连接工厂，并且将其绑定到
              JNDI中。如果需要可以将一个连接工厂绑定为多个名称。只需要将绑定的名字加入到 <literal>entry</literal> 
              中即可。</para>
        <note>
            <para>在JMS ConnectionFactory的配置中引用了一个名为 <literal>netty</literal>的<literal>connector</literal>。
                它实际上指向的是HornetQ核心中部署的一个连接器（connector）。它的配置在HornetQ的核心配置文件
                 <literal>hornetq-configuration.xml</literal> 中。它定义了采用何种传输与服务器连接。</para>
        </note>
    </section>
    <section id="using-jms.configure.factory.types">
        <title>连接工厂的类型</title>
        <para>在JMS API文档中有几种不同类型的连接工厂供用户使用。HornetQ为用户提供了配置连接工厂类型的参数。用户可以通过
              配置连接工厂的”signature"属性和"xa"参数来得到想要的类型。“singature"属性是字符串类型，它有三个可选值：
              <emphasis>generic</emphasis>、<emphasis>queue</emphasis>和<emphasis>topic</emphasis>; 
              <literal>xa</literal>是一个布尔型参数。下表给出了不同类型连接工厂对应的配置值：</para>
        <table frame="topbot" id="using-jms.table.configure.factory.types">
                <title>连接工厂类型的配置</title>
                <tgroup cols="3">
                    <colspec colname="signature" colnum="1"/>
                    <colspec colname="xa" colnum="2"/>
                    <colspec colname="cftype" colnum="3"/>
                    <thead>
                        <row>
                            <entry>signature</entry>
                            <entry>xa</entry>
                            <entry>连接工厂的类型</entry>
                        </row>
                    </thead>
                    <tbody>
                        <row>
                            <entry>generic (默认)</entry>
                            <entry>false (默认)</entry>
                            <entry>javax.jms.ConnectionFactory</entry>
                        </row>
                        <row>
                            <entry>generic</entry>
                            <entry>true</entry>
                            <entry>javax.jms.XAConnectionFactory</entry>
                        </row>
                        <row>
                            <entry>queue</entry>
                            <entry>false</entry>
                            <entry>javax.jms.QueueConnectionFactory</entry>
                        </row>
                        <row>
                            <entry>queue</entry>
                            <entry>true</entry>
                            <entry>javax.jms.XAQueueConnectionFactory</entry>
                        </row>
                        <row>
                            <entry>topic</entry>
                            <entry>false</entry>
                            <entry>javax.jms.TopicConnectionFactory</entry>
                        </row>
                        <row>
                            <entry>topic</entry>
                            <entry>true</entry>
                            <entry>javax.jms.XATopicConnectionFactory</entry>
                        </row>
                    </tbody>
                </tgroup>
            </table>
            <para>下面的例子配置了一个XAQueueConnectionFactory:</para>
        <programlisting>
&lt;configuration xmlns="urn:hornetq" 
    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
    xsi:schemaLocation="urn:hornetq ../schemas/hornetq-jms.xsd "&gt;
    
    &lt;connection-factory name="ConnectionFactory" signature="queue"&gt;
        &lt;xa>true&lt;/xa>
        &lt;connectors>
           &lt;connector-ref connector-name="netty"/&gt;
        &lt;/connectors>
        &lt;entries&gt;
            &lt;entry name="ConnectionFactory"/&gt;           
        &lt;/entries&gt;
    &lt;/connection-factory&gt;
&lt;/configuration&gt; 
        </programlisting>
    </section>
    <section>
        <title>JNDI的配置</title>
        <para>当客户端使用JNDI时需要定义一些JNDI的参数。这些参数主要用来确定JNDI服务的地址。这些参数通常保存在
            一个名为 <literal>jndi.properties</literal> 的文件中。这个文件需要在客户端的classpath中。或者你
            可以在创建JNDI的InitialContext时将这些参数传进去。想了解全面的JNDI知识，可以参见 <ulink
                url="http://java.sun.com/products/jndi/tutorial/TOC.html">Sun JNDI 教程</ulink>
            。</para>
        <para>要与JBoss的JNDI Server进行通迅，需要指定以下的JNDI参数：</para>
        <programlisting>
java.naming.factory.initial=org.jnp.interfaces.NamingContextFactory
java.naming.provider.url=jnp://myhost:1099
java.naming.factory.url.pkgs=org.jboss.naming:org.jnp.interfaces                        
        </programlisting>
        <para>其中的 <literal>myhost</literal> 是 JNDI server的主机名或IP地址。 1099是端口号，根据不同的配置，
            端口号也可能不同。</para>
        <para>在默认的单独方式（standalone）配置中，JNDI服务端口等参数定义在<literal>hornetq-beans.xml</literal>
              文件中的 <literal>JNDIServer</literal> bean下，如：</para>
        <programlisting>
&lt;bean name="JNDIServer" class="org.jnp.server.Main"&gt;
    &lt;property name="namingInfo"&gt;
        &lt;inject bean="Naming"/&gt;
    &lt;/property&gt;
    &lt;property name="port"&gt;1099&lt;/property&gt;
    &lt;property name="bindAddress"&gt;localhost&lt;/property&gt;
    &lt;property name="rmiPort"&gt;1098&lt;/property&gt;
    &lt;property name="rmiBindAddress"&gt;localhost&lt;/property&gt;
&lt;/bean&gt;                        
        </programlisting>
        <note>
            <para>如果你的JNDI服务器与客户端不在同一台机器上，一定不要忘记将bindAddress改成相应的地址，
                  千万不能用<literal>localhost</literal>！</para>
        </note>
        <note>
            <para><emphasis>只有当HornetQ作为独立服务器运行时</emphasis>
                  才可以配置JNDIServer bean。当HornetQ运行于JBoss应用服务器中时，由于JBOSS服务器已经提供了
                  JNDI服务，所以就不需要再进行配置了。</para>
        </note>
    </section>
    <section>
        <title>程序代码</title>
        <para>下面给出的例子中的代码：</para>
        <para>首先我们创建一个JNDI的Initial Context：</para>
        <programlisting>InitialContext ic = new InitialContext();</programlisting>
        <para>下面我们查找 connection factory：</para>
        <programlisting>ConnectionFactory cf = (ConnectionFactory)ic.lookup("/ConnectionFactory");</programlisting>
        <para>然后查找 Queue：</para>
        <programlisting>Queue orderQueue = (Queue)ic.lookup("/queues/OrderQueue");</programlisting>
        <para>接下来用拿到的ConnectionFactory建立JMS连接：</para>
        <programlisting>Connection connection = cf.createConnection();</programlisting>
        <para>再创建一个非事务的、AUTO_ACKNOWLEDGE方式的JMS Session：</para>
        <programlisting>Session session = connection.createSession(false, Session.AUTO_ACKNOWLEDGE);</programlisting>
        <para>创建一个 MessageProducer 以向队列发送订单消息：</para>
        <programlisting>MessageProducer producer = session.createProducer(orderQueue);</programlisting>
        <para>创建一个 MessageConsumer 以从队列中接收订单消息：</para>
        <programlisting>MessageConsumer consumer = session.createConsumer(orderQueue);</programlisting>
        <para>要启动连接，以使消息能传递给接收者：</para>
        <programlisting>connection.start();</programlisting>
        <para>发送一个简单的TextMessage：</para>
        <programlisting>TextMessage message = session.createTextMessage("This is an order");
producer.send(message);</programlisting>
        <para>之后接收这个消息：</para>
        <programlisting>TextMessage receivedMessage = (TextMessage)consumer.receive();
System.out.println("Got order: " + receivedMessage.getText());
        </programlisting>
        <para>看起来就是这么简单。 在HornetQ有发布包中有很多各种各样的JMS例子供用户参考。</para>
        <warning>
            <para>请注意，JMS的连接（connection）、会话（session）、生产者（producer）和消费者（consumer）
                  对象是可以<emphasis>重用</emphasis>的。</para>
            <para>如果每发送或接收一个消息都要重新创建这些JMS对象，是不符合设计模式的要求的。这样做会造成应用程序
                  的性能很差。这方面的内容在<xref linkend="perf-tuning"/>中将会进一步的讨论。</para>
        </warning>
    </section>
    <section>
        <title>不使用JNDI而直接创建JMS的对象</title>
        <para>尽管采用JNDI对 JMS 的各种<emphasis>管理对象（Administered
                Objects）</emphasis> (即JMS Queue, Topic and ConnectionFactory)是很常用的方法，但在有些
            情况时JNDI不可用，或者你不需要用JNDI时，如何还能正常使用JMS呢？</para>
        <para>HornetQ允许你不通过JNDI也能使用JMS。HornetQ支持直接创建JMS的各种对象而无需JNDI的存在。</para>
        <para>在<xref linkend="examples"/>中包括有这样的例子供读者参考。</para>
        <para>下面我们就将上述那个简单的例子重写，以抛开对JNDI的依赖：</para>
        <para>我们通过HornetQJMSClient类来方便地创建JMS的ConnectionFactory。注意这里要提供各种连接参数和定义
              所用的传输方式。有关连接器（connector）的信息参见<xref linkend="configuring-transports"
            />。</para>
        <programlisting>              
TransportConfiguration transportConfiguration = 
                     new TransportConfiguration(NettyConnectorFactory.class.getName());                
ConnectionFactory cf = HornetQJMSClient.createConnectionFactory(transportConfiguration);
        </programlisting>
        <para>同样利用HornetQJMSClient类创建JMS Queue对象：</para>
        <programlisting>Queue orderQueue = HornetQJMSClient.createQueue("OrderQueue");</programlisting>
        <para>然后用连接工厂创建 JMS 连接：</para>
        <programlisting>Connection connection = cf.createConnection();</programlisting>
        <para>还有非事务的\AUTO_ACKNOWLEDGE方式的 JMS 会话（session）：</para>
        <programlisting>Session session = connection.createSession(false, Session.AUTO_ACKNOWLEDGE);</programlisting>
        <para>以及用于发送消息的MessageProducer：</para>
        <programlisting>MessageProducer producer = session.createProducer(orderQueue);</programlisting>
        <para>和接收消息的 MessageConsumer：</para>
        <programlisting>MessageConsumer consumer = session.createConsumer(orderQueue);</programlisting>
        <para>启动连接：</para>
        <programlisting>connection.start();</programlisting>
        <para>创建一个简单的 TextMessage 并将其发送到队列：</para>
        <programlisting>TextMessage message = session.createTextMessage("This is an order");
producer.send(message);</programlisting>
        <para>接收消息：</para>
        <programlisting>TextMessage receivedMessage = (TextMessage)consumer.receive();
System.out.println("Got order: " + receivedMessage.getText());
        </programlisting>
    </section>
    <section id="using-jms.clientid">
        <title>Client ID的设置</title>
        <para>在建立持久的订阅（subscription）时，JMS客户需要有一个客户ID （client id）。我们可以通过配置
            connection factory来定义它。（其中的 <literal>client-id</literal>项）。这样所有通过这个
            connection factory来创建的连接都具有这个客户ID。</para>
    </section>
    <section id="using-jms.dupsokbatchsize">
        <title>设置DUPS_OK的Batch Size </title>
        <para>如果JMS的通知模式为<literal>DUPS_OK</literal>，我们可以配置接收者（consumer）以使得它以批为单位
            发送通知，而不是一个一个地发通知。这样做可以节省很多带宽，效率高。配置的方法是设置connection factory下
            的<literal>dups-ok-batch-size</literal>项。单位是字节（byte）。默认值是1024 * 1024 bytes = 1 MiB。</para>
    </section>
    <section id="using-jms.txbatchsize">
        <title>设置事务（Transaction）的Batch Size</title>
        <para>当在一个事务内接收消息时，可能通过配置使接收者采用批量的方式发送通知，而不是一个一个的发送。这样也可以节省带宽。
            配置方法是设置connection factory下的<literal
                >transaction-batch-size</literal>项。 单位是字节（byte）。默认值是1024 *
            1024。</para>
    </section>
</chapter>