[hornetq-commits] JBoss hornetq SVN: r8949 - branches/HnetQ_323_cn/docs/user-manual/zh.

Author: gaohoward Date: 2010-03-23 11:20:55 -0400 (Tue, 23 Mar 2010) New Revision: 8949 Modified: branches/HnetQ_323_cn/docs/user-manual/zh/using-jms.xml Log: one more chapter done. Modified: branches/HnetQ_323_cn/docs/user-manual/zh/using-jms.xml =================================================================== --- branches/HnetQ_323_cn/docs/user-manual/zh/using-jms.xml 2010-03-23 15:18:38 UTC (rev 8948) +++ branches/HnetQ_323_cn/docs/user-manual/zh/using-jms.xml 2010-03-23 15:20:55 UTC (rev 8949) @@ -17,46 +17,32 @@ <!-- permitted by applicable law. --> <!-- ============================================================================= --> <chapter id="using-jms"> - <title>Using JMS</title> - <para>Although HornetQ provides a JMS agnostic messaging API, many users will be more - comfortable using JMS.</para> - <para>JMS is a very popular API standard for messaging, and most messaging systems provide a JMS - API. If you are completely new to JMS we suggest you follow the<ulink - url="http://java.sun.com/products/jms/tutorial/1_3_1-fcs/doc/jms_tut... Sun - JMS tutorial</ulink> - a full JMS tutorial is out of scope for this guide.</para> - <para>HornetQ also ships with a wide range of examples, many of which demonstrate JMS API usage. - A good place to start would be to play around with the simple JMS Queue and Topic example, - but we also provide examples for many other parts of the JMS API. A full description of the - examples is available in <xref linkend="examples"/>.</para> - <para>In this section we'll go through the main steps in configuring the server for JMS and - creating a simple JMS program. We'll also show how to configure and use JNDI, and also how - to use JMS with HornetQ without using any JNDI.</para> + <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_tut... + 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>A simple ordering system</title> - <para>For this chapter we're going to use a very simple ordering system as our example. It's - a somewhat contrived example because of its extreme simplicity, but it serves to - demonstrate the very basics of setting up and using JMS.</para> - <para>We will have a single JMS Queue called <literal>OrderQueue</literal>, and we will have - a single <literal>MessageProducer</literal> sending an order message to the queue and a - single <literal>MessageConsumer</literal> consuming the order message from the - queue.</para> - <para>The queue will be a <literal>durable</literal> queue, i.e. it will survive a server - restart or crash. We also want to predeploy the queue, i.e. specify the queue in the - server JMS configuration so it's created automatically without us having to explicitly - create it from the client.</para> + <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 Server Configuration</title> - <para>The file <literal>hornetq-jms.xml</literal> on the server classpath contains any JMS - Queue, Topic and ConnectionFactory instances that we wish to create and make available - to lookup via the JNDI.</para> - <para>A JMS ConnectionFactory object is used by the client to make connections to the - server. It knows the location of the server it is connecting to, as well as many other - configuration parameters. In most cases the defaults will be acceptable.</para> - <para>We'll deploy a single JMS Queue and a single JMS Connection Factory instance on the - server for this example but there are no limits to the number of Queues, Topics and - Connection Factory instances you can deploy from the file. Here's our - configuration:</para> + <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" @@ -77,38 +63,32 @@ &lt;/configuration&gt; </programlisting> - <para>We deploy one ConnectionFactory called <literal>ConnectionFactory</literal> and bind - it in just one place in JNDI as given by the <literal>entry</literal> element. - ConnectionFactory instances can be bound in many places in JNDI if you require. </para> + <para>在本文件中我们部署了一个名为 <literal>ConnectionFactory</literal> 的一个连接工厂，并且将其绑定到 + JNDI中。如果需要可以将一个连接工厂绑定为多个名称。只需要将绑定的名字加入到 <literal>entry</literal> + 中即可。</para> <note> - <para>The JMS connection factory references a <literal>connector</literal> called - <literal>netty</literal>. This is a reference to a connector object deployed in - the main core configuration file <literal>hornetq-configuration.xml</literal> which - defines the transport and parameters used to actually connect to the server.</para> + <para>在JMS ConnectionFactory的配置中引用了一个名为 <literal>netty</literal>的<literal>connector</literal>。 + 它实际上指向的是HornetQ核心中部署的一个连接器（connector）。它的配置在HornetQ的核心配置文件 + <literal>hornetq-configuration.xml</literal> 中。它定义了采用何种传输与服务器连接。</para> </note> </section> <section> - <title>JNDI configuration</title> - <para>When using JNDI from the client side you need to specify a set of JNDI properties - which tell the JNDI client where to locate the JNDI server, amongst other things. These - are often specified in a file called <literal>jndi.properties</literal> on the client - classpath, or you can specify them directly when creating the JNDI initial context. A - full JNDI tutorial is outside the scope of this document, please see the <ulink - url="http://java.sun.com/products/jndi/tutorial/TOC.html">Sun JNDI tutorial</ulink> - for more information on how to use JNDI.</para> - <para>For talking to the JBoss JNDI Server, the jndi properties will look something like - this:</para> + <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>Where <literal>myhost</literal> is the hostname or IP address of the JNDI server. 1099 - is the port used by the JNDI server and may vary depending on how you have configured - your JNDI server.</para> - <para>In the default standalone configuration, JNDI server ports are configured in the file - <literal>hornetq-beans.xml</literal> by setting properties on the <literal - >JNDIServer</literal> bean:</para> + <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; @@ -121,119 +101,102 @@ &lt;/bean&gt; </programlisting> <note> - <para>If you want your JNDI server to be available to non local clients make sure you - change it's bind address to something other than <literal - >localhost</literal>!</para> + <para>如果你的JNDI服务器与客户端不在同一台机器上，一定不要忘记将bindAddress改成相应的地址， + 千万不能用<literal>localhost</literal>！</para> </note> <note> - <para>The JNDIServer bean must be defined <emphasis>only when HornetQ is running in - stand-alone mode</emphasis>. When HornetQ is integrated to JBoss Application - Server, JBoss AS will provide a ready-to-use JNDI server without any additional - configuration.</para> + <para><emphasis>只有当HornetQ作为独立服务器运行时</emphasis> + 才可以配置JNDIServer bean。当HornetQ运行于JBoss应用服务器中时，由于JBOSS服务器已经提供了 + JNDI服务，所以就不需要再进行配置了。</para> </note> </section> <section> - <title>The code</title> - <para>Here's the code for the example:</para> - <para>First we'll create a JNDI initial context from which to lookup our JMS objects:</para> + <title>程序代码</title> + <para>下面给出的例子中的代码：</para> + <para>首先我们创建一个JNDI的Initial Context：</para> <programlisting>InitialContect ic = new InitialContext();</programlisting> - <para>Now we'll look up the connection factory:</para> + <para>下面我们查找 connection factory：</para> <programlisting>ConnectionFactory cf = (ConnectionFactory)ic.lookup("/ConnectionFactory");</programlisting> - <para>And look up the Queue:</para> + <para>然后查找 Queue：</para> <programlisting>Queue orderQueue = (Queue)ic.lookup("/queues/OrderQueue");</programlisting> - <para>Next we create a JMS connection using the connection factory:</para> + <para>接下来用拿到的ConnectionFactory建立JMS连接：</para> <programlisting>Connection connection = cf.createConnection();</programlisting> - <para>And we create a non transacted JMS Session, with AUTO_ACKNOWLEDGE acknowledge - mode:</para> + <para>再创建一个非事务的、AUTO_ACKNOWLEDGE方式的JMS Session：</para> <programlisting>Session session = connection.createSession(false, Session.AUTO_ACKNOWLEDGE);</programlisting> - <para>We create a MessageProducer that will send orders to the queue:</para> + <para>创建一个 MessageProducer 以向队列发送订单消息：</para> <programlisting>MessageProducer producer = session.createProducer(orderQueue);</programlisting> - <para>And we create a MessageConsumer which will consume orders from the queue:</para> + <para>创建一个 MessageConsumer 以从队列中接收订单消息：</para> <programlisting>MessageConsumer consumer = session.createConsumer(orderQueue);</programlisting> - <para>We make sure we start the connection, or delivery won't occur on it:</para> + <para>要启动连接，以使消息能传递给接收者：</para> <programlisting>connection.start();</programlisting> - <para>We create a simple TextMessage and send it:</para> + <para>发送一个简单的TextMessage：</para> <programlisting>TextMessage message = session.createTextMessage("This is an order"); producer.send(message);</programlisting> - <para>And we consume the message:</para> + <para>之后接收这个消息：</para> <programlisting>TextMessage receivedMessage = (TextMessage)consumer.receive(); System.out.println("Got order: " + receivedMessage.getText()); </programlisting> - <para>It's as simple as that. For a wide range of working JMS examples please see the - examples directory in the distribution.</para> + <para>看起来就是这么简单。 在HornetQ有发布包中有很多各种各样的JMS例子供用户参考。</para> <warning> - <para>Please note that JMS connections, sessions, producers and consumers are - <emphasis>designed to be re-used</emphasis>.</para> - <para>It's an anti-pattern to create new connections, sessions, producers and consumers - for each message you produce or consume. If you do this, your application will - perform very poorly. This is discussed further in the section on performance tuning - <xref linkend="perf-tuning"/>.</para> + <para>请注意，JMS的连接（connection）、会话（session）、生产者（producer）和消费者（consumer） + 对象是可以<emphasis>重用</emphasis>的。</para> + <para>如果每发送或接收一个消息都要重新创建这些JMS对象，是不符合设计模式的要求的。这样做会造成应用程序 + 的性能很差。这方面的内容在<xref linkend="perf-tuning"/>中将会进一步的讨论。</para> </warning> </section> <section> - <title>Directly instantiating JMS Resources without using JNDI</title> - <para>Although it's a very common JMS usage pattern to lookup JMS <emphasis>Administered - Objects</emphasis> (that's JMS Queue, Topic and ConnectionFactory instances) from - JNDI, in some cases a JNDI server is not available and you still want to use JMS, or you - just think "Why do I need JNDI? Why can't I just instantiate these objects - directly?"</para> - <para>With HornetQ you can do exactly that. HornetQ supports the direct instantiation of JMS - Queue, Topic and ConnectionFactory instances, so you don't have to use JNDI at - all.</para> - <para>For a full working example of direct instantiation please see the JMS examples in - <xref linkend="examples"/>.</para> - <para>Here's our simple example, rewritten to not use JNDI at all:</para> - <para>We create the JMS ConnectionFactory object via the HornetQJMSClient Utility class, - note we need to provide connection parameters and specify which transport we are using, - for more information on connectors please see <xref linkend="configuring-transports" - />.</para> + <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>We also create the JMS Queue object via the HornetQJMSClient Utility class:</para> + <para>同样利用HornetQJMSClient类创建JMS Queue对象：</para> <programlisting>Queue orderQueue = HornetQJMSClient.createQueue("OrderQueue");</programlisting> - <para>Next we create a JMS connection using the connection factory:</para> + <para>然后用连接工厂创建 JMS 连接：</para> <programlisting>Connection connection = cf.createConnection();</programlisting> - <para>And we create a non transacted JMS Session, with AUTO_ACKNOWLEDGE acknowledge - mode:</para> + <para>还有非事务的\AUTO_ACKNOWLEDGE方式的 JMS 会话（session）：</para> <programlisting>Session session = connection.createSession(false, Session.AUTO_ACKNOWLEDGE);</programlisting> - <para>We create a MessageProducer that will send orders to the queue:</para> + <para>以及用于发送消息的MessageProducer：</para> <programlisting>MessageProducer producer = session.createProducer(orderQueue);</programlisting> - <para>And we create a MessageConsumer which will consume orders from the queue:</para> + <para>和接收消息的 MessageConsumer：</para> <programlisting>MessageConsumer consumer = session.createConsumer(orderQueue);</programlisting> - <para>We make sure we start the connection, or delivery won't occur on it:</para> + <para>启动连接：</para> <programlisting>connection.start();</programlisting> - <para>We create a simple TextMessage and send it:</para> + <para>创建一个简单的 TextMessage 并将其发送到队列：</para> <programlisting>TextMessage message = session.createTextMessage("This is an order"); producer.send(message);</programlisting> - <para>And we consume the message:</para> + <para>接收消息：</para> <programlisting>TextMessage receivedMessage = (TextMessage)consumer.receive(); System.out.println("Got order: " + receivedMessage.getText()); </programlisting> </section> <section id="using-jms.clientid"> - <title>Setting The Client ID</title> - <para>This represents the client id for a JMS client and is needed for creating durable - subscriptions. It is possible to configure this on the connection factory and can be set - via the <literal>client-id</literal> element. Any connection created by this connection - factory will have this set as its client id.</para> + <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>Setting The Batch Size for DUPS_OK </title> - <para>When the JMS acknowledge mode is set to <literal>DUPS_OK</literal> it is possible to - configure the consumer so that it sends acknowledgements in batches rather that one at a - time, saving valuable bandwidth. This can be configured via the connection factory via - the <literal>dups-ok-batch-size</literal> element and is set in bytes. The default is - 1024 * 1024 bytes = 1 MiB.</para> + <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>Setting The Transaction Batch Size</title> - <para>When receiving messages in a transaction it is possible to configure the consumer to - send acknowledgements in batches rather than individually saving valuable bandwidth. - This can be configured on the connection factory via the <literal - >transaction-batch-size</literal> element and is set in bytes. The default is 1024 * - 1024.</para> + <title>设置事务（Transaction）的Batch Size</title> + <para>当在一个事务内接收消息时，可能通过配置使接收者采用批量的方式发送通知，而不是一个一个的发送。这样也可以节省带宽。 + 配置方法是设置connection factory下的<literal + >transaction-batch-size</literal>项。 单位是字节（byte）。默认值是1024 * + 1024。</para> </section> </chapter>