HornetQ快速开始文档

JBoss7.1 放弃了Messaging，转而支持HornetQ作为默认的JMS实现，在网上找到一篇关于HornetQ的快速开始文档的中文翻译，分享一下：

Chapter 1. 法律声明
Red Hat, Inc. 以及其他公司2010年版权所有。
Red Hat公司依照 CC-BY-SA 3.0 Unported(Creative Commons Attribution-Share Alike)条款之规定授权用戶是用本手册中的文字和插图。
有关 CC-BY-SA 的解释请访问http://creativecommons.org/licenses/by-sa/3.0/。根据CC－BY－SA的规定，如果要发布本文档或任何本文档的修改版本，都必须给出原始版本文档的URL。
Red Hat 作为本文档的授权方声明在相关法律允许的最大范围内放弃CC-BY-SA第4d节所规定的权利。
Chapter 2. 关于HornetQ
什么是HornetQ?
 HornetQ是一个开源项目。它的目标是一个多协议、可嵌入、高性能、可集群的异步的消息系统。
 有关HornetQ是什么及不是什么的更多的问题，请访问 FAQs wiki 页。
为什么要使用HornetQ？ 以下给出了几个理由：
 HornetQ是100%的开源软件。 HornetQ 采用 Apache v 2.0开源协议，对用户的限制最小。
 HornetQ的设计强调可用性。
 采用Java语言编写。可以在任何Java 6+ 的平台上运行。这几乎包括了从Windows到IBM mainframes的每个平台。
 性能出众。不但对非持久化消息的处理性能达到了非常高的性能。独特高效的日志（journal）使持久消息处理接近非持久消息的性能。
 功能全面。不仅拥有其它成熟消息产品所具有的全部功能，而且还有很多独特的功能。
 HornetQ的设计遵从了简约的原则。对第三方软件的依赖极少。根据不同的需要， HornetQ可以单独运行，也可以运行于JEE应用服务器中。它还可以嵌入到你自己的应用程序中。
 完美的可获得性。HornetQ提供自动客户端失效备援（automatic client failover）功能，能保证在服务器故障时没有消息丢失或消息重复。
 超级灵活的集群方案。可以控制集群进行消息负载均衡的方式。分布在不同地理位置的各个集群间可以通过非可靠的网络连接形成一个全球网络。 还可以非常灵活地配置消息路由。
 请访问 wiki来全面了解HornetQ的所有功能介绍。
Chapter 3. 快速入手
本简短的指南给出了如何下载、安装HornetQ，以及尽快开始使用HornetQ。
我们强烈建议当下载安装完成后，运行HornetQ的例子来了解HornetQ。我们有70多个例子来展示几乎 所有HornetQ的功能。
本指南不能代替用户手册。用户手册包括更加完整和深入的信息，供用户进一步全面掌握HornetQ。
Chapter 4. 下载
HornetQ项目的官方地址是 http://hornetq.org/。
4.1. 软件下载
HornetQ的下载地址是http://hornetq.org/downloads.html
4.2. 项目信息
 HornetQ的 wiki
 如果在使用HornetQ中发生任何问题，可以去我们的 用户论坛
 如果你有开发方面的问题与想法，请访问我们的 开发论坛
 请加入我们的IRC频道与我们的核心开发工程师交流。
 我们项目有自己的 博客
 还可以跟踪我们的twitter
 HornetQ的Subversion代码库地址 http://anonsvn.jboss.org/repos/hornetq/trunk
 每次发布的版本标签都在http://anonsvn.jboss.org/repos/hornetq/tags下能找到。
Chapter 5. 安装
本章讲述如何安装HornetQ。
5.1. 准备 Note HornetQ只能在Java 6或以上版本中运行
默认情况下HornetQ运行的内存是1GiB。如果你的电脑内存少于1GiB，或者你希望更多的内存给HornetQ，你 可以修改 bin/run.sh脚本文件。
HornetQ有自己的快速日志系统，它能够使用libaio（在Linux上它是默认的）或Java的NIO。 如果要使用libaio，你需要首先在你的Linux上安装它。
如果你不在使用Linux，则不需要考虑这个问题。
要安装libaio，你可以使用root用户完成以下步骤：
使用yum（例如在Fedora 或 Red Hat Enterprise Linux上）： yum install libaio
使用aptitude, (例如在Ubuntu或Debian系统上）： apt-get install libaio
5.2. 单独的HornetQ服务器
将软件包下载后，将其解压到你选定的目录下。这里你就可以直接运行了。 下面给出了它的目录结构： |___ bin | |___ config | |___ jboss-as-4 | |___ jboss-as-5 | |___ stand-alone | |___ docs | |___ api | |___ quickstart-guide | |___ user-manual | |___ examples | |___ core | |___ javaee | |___ jms | |___ lib | |___ licenses | |___ schemas
 bin -- 运行HornetQ的二进制文件和脚本文件。
 config -- HornetQ的配置文件。它包括了单独模式或者运行在 JBoss AS 4 或 5中的配置。请参考配置索引来了解配置有详细信息。
 docs -- HornetQ的文档及Javadoc。
 examples -- JMS and Java EE例子。有关详细信息请参见 'running examples'一章。
 lib -- 运行HornetQ所需要的jar文件和库文件
 licenses -- HornetQ的软件协议
 schemas -- HornetQ配置文件的XML Schema
5.3. HornetQ运行于JBoss应用服务器5.x
HornetQ可以部署在JBoss AS 5中。目前默认的应用服务器没有安装HornetQ（HornetQ将是JBoss 6的默认JMS提供者），因此 你需要为HornetQ创建新的AS 5的配置（profile）。
创建AS 5新配置的步骤：
1. 下载并安装JBoss AS 5
2. 设置环境变量JBOSS_HOME指向JBoss AS 5的安装目录。
3. 运行HornetQ的config/jboss-as-5下的./build.sh （或 者如果在Windows下运行build.bat）。
这将会在$JBOSS_HOME/server创建两个服务器配置：
 default-with-hornetq -- 这个相当于AS 5的default配置但其JMS提供者替换成为HornetQ。在这个配置中的HornetQ 是非集群的。
 all-with-hornetq -- 这个相当于AS 5的all配置但其JMS提供者替换成为HornetQ。这个配置中的HornetQ 是集群的。
这时，你就可以启动上面其中任何一个配置的JBoss AS 5服务器了，例如： $JBOSS_HOME/bin/run.sh -c default-with-hornetq
5.4. HornetQ运行于JBoss应用服务器4.x
为了在AS 4中安装HornetQ，你需要创建新的配置（profile）。
步骤如下：
1. 下载并安装JBoss AS 4
2. 设置环境变量JBOSS_HOME指向JBoss AS 4的安装目录。
3. 运行HornetQ的config/jboss-as-4下的./build.sh （或 者如果在Windows下运行build.bat）。
这将会在$JBOSS_HOME/server创建两个服务器配置：
 default-with-hornetq -- 这个相当于AS 4的default配置但其JMS提供者替换成为HornetQ。在这个配置中的HornetQ 是非集群的。
 all-with-hornetq -- 这个相当于AS 4的all配置但其JMS提供者替换成为HornetQ。这个配置中的HornetQ 是集群的。
这时，你就可以启动上面其中任何一个配置的JBoss AS 4服务器了，例如： $JBOSS_HOME/bin/run.sh -c default-with-hornetq
Chapter 6. Starting The Server
6.1. 单独HornetQ
要运行单独的HornetQ服务，打开一个命令行窗口，进入到HornetQ的bin 目录下，执行./run.sh (或者在Windows下 run.bat）。你将看到如下的输出： bin$ ./run.sh 15:05:54,108 INFO @main [HornetQBootstrapServer] Starting HornetQ server ... 15:06:02,566 INFO @main [HornetQServerImpl] HornetQ Server version 2.0.0.CR3 (yellowjacket, 111) started
这表明HornetQ已经启动并运行了。
默认情况下，不论是启动还是停止脚本都使用config/stand-alone/non-clustered 下的配置文件。要使用不同的配置目录，可运行./run.sh ../config/stand-alone/clustered 或者其它选定的目录。同样方法适用于停止脚本。
6.2. HornetQ在JBoss AS 5.x中运行
要在JBoss AS 5运行HornetQ，你需要创建安装有HornetQ的AS 5的配置。然后用这个配置启动AS 5。 例如，要运行一个带有非集群的HornetQ服务的AS 5，进入$JBOSS_HOME/bin目录，然后键入： bin$ ./run.sh -c default-with-hornetq
15:18:35,460 INFO [ServerImpl] Starting JBoss (Microcontainer)... 15:18:35,462 INFO [ServerImpl] Release ID: JBoss (Microcontainer) [5.1.0.GA (build: SVNTag= JBoss_5_1_0_GA date=200905221053) ... 15:19:30,305 INFO [HornetQServerImpl] HornetQ Server version 2.0.0.CR3 (yellowjacket, 111) started ... 15:19:43,601 INFO [ServerImpl] JBoss (Microcontainer) [5.1.0.GA (build: SVNTag= JBoss_5_1_0_GA date=200905221053)]Started in 1m:14s:556ms
6.3. HornetQ在JBoss AS 4中运行
首先按照与JBoss AS 5相同的步骤创建安装有HornetQ的AS 4配置 然后以相同的方式启动AS。
6.4. HornetQ在JBoss AS 6.0中运行
从JBoss AS 6.0 M3开始，HornetQ已经是默认的（内建）JMS提供者。所以无需安装即可运行。
Chapter 7. 运行HornetQ例子
在HornetQ的examples目录下有两组例子，它们是：
 JMS例子 - 这些例子展示的是使用JMS发送与接收消息的功能。
 Java EE 例子 - 这些例子展示的是与应用服务器的集成，例如MDB，EJB，Servlet等。
7.1. JMS例子
所有JMS都有统一的格式。每个例子都有自己的目录，它的内容包括：
 build.xml
ant的build文件，用来运行例子。
 src 目录
例子的代码。
 server0配置目录
它包含了运行服务器所需要的配置文件。有的集群的例子可能有多个这样的目录，如server0, server1等。
在运行每个例子时，都要先启动一个或多个单独的服务器。当例子运行完毕，再将它们停止。
做为演示我们这里运行queue例子。其它的例子可以参见用户手册。
首先打开一个命令行窗口（shell），进入到HornetQ的 examples/jms/queue目录。
敲入命令./build.sh (或者在Windows上build.bat），你 将看到如下的输出： Buildfile: build.xml run: init: compile: [echo] src.example.dir=/home/andy/projects/hornetq/trunk/examples/jms/queue/src [javac] Compiling 5 source files to /home/andy/projects/hornetq/trunk/examples/jms/queue /build/classes runExample: [java] 10:41:04,149 INFO @main [JMSExample] hornetq.example.runServer is true [java] 10:41:04,149 INFO @main [JMSExample] starting server with config 'server0' logServerOutput true [java] 10:41:04,149 INFO @main [JMSExample] and vm args: -Xms512M,-Xmx512M,-XX:+U seParallelGC,-XX:+AggressiveOpts,-XX:+UseFastAccessorMethods,-Djava.util.logging.config. file=/home/andy/projects/hornetq/trunk/examples/jms/common/../../../src/config/stand-alone/no
n-clustered/logging.properties [java] org.hornetq.jms.example.SpawnedJMSServer out:10:41:08,437 INFO @main [Journal StorageManager] AIO journal selected [java] org.hornetq.jms.example.SpawnedJMSServer out:10:41:08,437 WARN @main [Journal StorageManager] AIO wasn't located on this platform, it will fall back to using pure Jav a NIO. If your platform is Linux, install LibAIO to enable the AIO journal [java] org.hornetq.jms.example.SpawnedJMSServer out:10:41:08,437 WARN @main [Securit yStoreImpl] It has been detected that the cluster admin password which is used to replic ate management operation from one node to the other has not had its password changed fro m the installation default. Please see the HornetQ user guide for instructions o n how to do this. [java] org.hornetq.jms.example.SpawnedJMSServer out:10:41:10,941 INFO @main [HornetQCo nnectionFactory] read only is false [java] org.hornetq.jms.example.SpawnedJMSServer out:10:41:10,941 INFO @main [HornetQCo nnectionFactory] read only is false [java] org.hornetq.jms.example.SpawnedJMSServer out:10:41:10,941 INFO @main [HornetQCo nnectionFactory] read only is false [java] org.hornetq.jms.example.SpawnedJMSServer out:10:41:10,991 WARN @main [JMSServ erManagerImpl] Binding for java:/ConnectionFactory already exists [java] org.hornetq.jms.example.SpawnedJMSServer out:10:41:10,991 WARN @main [JMSServ erManagerImpl] Binding for java:/XAConnectionFactory already exists [java] org.hornetq.jms.example.SpawnedJMSServer out:10:41:11,241 INFO @main [Messagi ngServerImpl] HornetQ Server version 2.0.0.BETA5 (buzz-buzz, 107) started [java] org.hornetq.jms.example.SpawnedJMSServer out:10:41:11,241 INFO @main [HornetQBoot strapServer] HornetQ server started [java] org.hornetq.jms.example.SpawnedJMSServer out:STARTED:: [java] 10:41:11,276 INFO @main [JMSExample] using server0/client-jndi.properties f
or jndi [java] Sent message: This is a text message [java] Received message: This is a text message [java] [java] ##################### [java] ### SUCCESS! ### [java] ##################### BUILD SUCCESSFUL Total time: 13 seconds
恭喜！你已经成功地运行了你的第一个HornetQ例子。试着运行其它的例子。
7.2. Java EE例子
Java EE的例子需要首先运行一个JEE应用服务器。这些例子包括MDB，Servlet，EJB等等。你首先要安装JBoss应用服务 器。参见前面的章节进行安装。
这里我们将用MDB例子来说明。有关其它例子的详细信息参见用户手册。首先确认JBoss应用服务器已经启动。
如同其它Java EE例子一样，MDB需要部署到应用服务器。第一，将JBOSS_HOME环境变量 指向你的应用服务器安装目录。如在Linux下： export JBOSS_HOME=/home/jbossas5.1/build/output/jboss-5.1.0.GA
然后就可以进行部署了。在examples/javaee/mdb目录下运行： ./build.sh deploy
它将创建一个“messaging"的AS配置，并用它来启动AS服务器。
在命令行窗口你会看到如下的输出： Buildfile: build.xml validate-jboss: deploy: deploy-resources:
[copy] Copying 1 file to /home/andy/projects/jbossas5.1/build/output/jboss-5.1.0.GA /server/default-with-hornetq/deploy/hornetq.sar [copy] Copying 1 file to /home/andy/projects/jbossas5.1/build/output/jboss-5.1.0.GA /server/default-with-hornetq/deploy/hornetq.sar init: compile: jar: [jar] Building jar: /home/andy/projects/hornetq/trunk/examples/javaee/mdb/build/mdb-exa mple.jar ear: [jar] Building jar: /home/andy/projects/hornetq/trunk/examples/javaee/mdb/build/mdb-exa mple.ear deploy-ear: [copy] Copying 1 file to /home/andy/projects/jbossas5.1/build/output/jboss-5.1.0.GA ....... [exec] 16:01:04,607 INFO [JBossASKernel] Class:javax.jms.MessageListener [exec] 16:01:04,607 INFO [JBossASKernel] Added bean(jboss.j2ee:ear=mdb-example.ear, jar=mdb-example.jar,name=MessageMDBExample,service=EJB3) to KernelDeployment of: mdb-example.jar [exec] 16:01:04,702 INFO [EJBContainer] STARTED EJB: org.hornetq.javaee.example.server .MDBExample ejbName: MessageMDBExample [exec] 16:01:09,496 INFO [TomcatDeployment] deploy, ctxPath=/mdb-example [exec] 16:01:09,812 WARNING [config] Unable to process deployment descriptor for cont
ext '/mdb-example' [exec] 16:01:09,812 INFO [config] Initializing Mojarra (1.2_12-b01-FCS) for context '/mdb-example' [exec] 16:01:09,958 INFO [Http11Protocol] Starting Coyote HTTP/1.1 on http-127.0.0.1- 8080 [exec] 16:01:09,990 INFO [AjpProtocol] Starting Coyote AJP/1.3 on ajp-127.0.0.1-8009 [exec] 16:01:10,001 INFO [ServerImpl] JBoss (Microcontainer) [5.1.0.GA (build: SVNTag =JBoss_5_1_0_GA date=200905151005)] Started in 6m:21s:797ms
现在我们可以运行例子了。在mdb目录下运行下列命令： ./build.sh
你将看到如下输出： Buildfile: build.xml run: init: compile: runExample: [java] Sent message: This is a text message BUILD SUCCESSFUL Total time: 7 seconds
在JBoss应用服务器端你还会看到如下的输出： 16:27:54,703 INFO [STDOUT] message This is a text message received
然后在mdb目录下运行下面的命令可以将这个例子卸载。
./build.sh undeploy
你将会看到如下的输出： Buildfile: build.xml validate-jboss: undeploy: undeploy-misc: [delete] Deleting: /home/andy/projects/jbossas5.1/build/output/jboss-5.1.0.GA /server/default-with-hornetq/deploy/mdb-example.ear [delete] Deleting: /home/andy/projects/jbossas5.1/build/output/jboss-5.1.0.GA /server/default-with-hornetq/deploy/hornetq.sar/hornetq-queues.xml [delete] Deleting: /home/andy/projects/jbossas5.1/build/output/jboss-5.1.0.GA /server/default-with-hornetq/deploy/hornetq.sar/hornetq-jms.xml BUILD SUCCESSFUL Total time: 1 second
你还会在窗口输出中看到MDB的应用最終被删除了，如： 16:36:45,277 INFO [EJBContainer] STOPPED EJB: org.jboss.javaee.example.server.MDBExample ejbName: MessageMDBExample
恭喜！你已经成功地部署并运行了一个Java EE的例子。