[hornetq-commits] JBoss hornetq SVN: r8949 - branches/HnetQ_323_cn/docs/user-manual/zh.
do-not-reply at jboss.org
do-not-reply at jboss.org
Tue Mar 23 11:20:56 EDT 2010
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_tutorialTOC.html"> 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_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>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>
<configuration xmlns="urn:hornetq"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
@@ -77,38 +63,32 @@
</configuration>
</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>
<bean name="JNDIServer" class="org.jnp.server.Main">
<property name="namingInfo">
@@ -121,119 +101,102 @@
</bean>
</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>
More information about the hornetq-commits
mailing list