Chapter 11. 例子

在HornetQ的发布包中有超过70个不同的例子。这些例子直接可以运行。它们分别展示了HornetQ所具有的各种功能。

所有的例子都在HornetQ发布包的 examples目录下。所有的例子被分成了两大类: JMS例子和内核例子。JMS例子展现的是JMS的各种功能,内核的例子则展示的是内核API的功能。

此外HornetQ还提供了一些Java EE的例子,这些例子需要JBoss应用服务器才能运行。

11.1. JMS 例子

要运行一个JMS例子,只要进入到相应例子的子目录,运行 ./build.sh (或者 在Windows平台上运行build.bat)即可。

下面列出的这些JMS例子并配有简要的说明。

11.1.1. 应用层的失效备援(Failover)

HornetQ支持应用层的失效备援。这在服务器端没有复制(replication)配置的情况下是很有用的。

应用程序可以注册一个JMS ExceptionListener。当HornetQ检测到连接故障时,它会 通知这个注册的Listener。

这个ExceptionListener在接到HornetQ的通知后可以与其它的节点创建 新的连接、会话等对象,以使应用程序能继续运行。

应用层的失效备援是实现高可获得性(HA)的一种方法。它与自动失效备援不同之处在于它需要编写额外的代码。 同时由于发生故障时旧的会话结束,这会造成那些还没来得及提交的工作丢失,还会造成任何没有通知的消息被重发。

11.1.2. 内核桥(Bridge)例子

bridge例子展示的是将一个内核桥部署到一个服务器上,从本地的queue接收消息并将其转发到 另一服务器的地址上。

内核的bridge可用来在两个互相分开的HornetQ的服务器间建立一个消息流。它可以处理临时性的连接故障,特别适用于 不可靠的网络的情况。广域网就是一个例子。

11.1.3. 浏览器(Browser)

browser例子展示的是在HornetQ中如何使用JMS QueueBrowser

有关JMS queue的概念在JMS 1.1 specification有明确的定义,这里就不再叙述。

一个QueueBrowser可以用来观察queue中的消息而影响它们。它可以观察queue中的全部 消息,也可以定义一个选择器(selector)来选择性地察看消息。

11.1.4. Client Kickoff

client-kickoff例子展示的是如何利用JMX管理接口通过已知的IP地址来断开客户端的连接。

11.1.5. 客户端的负载均衡

client-side-load-balancing例子展示的是通过一个JMS连接可以在集群的不同节点上创建 会话。也就是说HornetQ可以对客户端的会话创建进行集群内的负载均衡。

11.1.6. 集群分组

与分组(grouping)例子相似,只是本例所展示的是集群的情况。发向不同节点的具有相同组id的消息 都会传送到同一个节点上的同一个接收者(consumer)。

11.1.7. 集群队列

clustered-queue 例子将一个JMS queue部署到两个节点上。这两个节点组成一个集群。 我们在每个节点上各创建一个接收者(consumer),但只在其中一个节点上创建一个发送者(producer)。利用发送者 发送一些消息,然后确认两个接收者以轮换方式(round-robin)接收这些消息。

11.1.8. 单机集群

clustered-standalone例子所展示的是如何在同一台机器上配置并运行 3个节点的集群。在每个节点上都创建了一个JMS topic的订阅者(subscriber)。只在其中一个节点上 创建了一相发送者来向这个topic发送一些消息。然后我们确认所有的subscriber都接收到了这些消息。

11.1.9. 集群的Topic

clustered-topic例子将一个JMS topic部署到两个节点上。这两个节点组成一个集群。 然后在每个节点上创建了一个订阅者(subscriber),只在一个节点上创建一个发送者(producer)。通过这个发 送者发送一些消息,确认两个订阅者都收到了这些消息。

11.1.10. 限制接收速率

HornetQ可以控制一个JMS消息接收者接收消息的速度。这是在创建或部署连接工厂时通过其配置参数来完成的。

如果设置了这个速度的限制,HornetQ会保证其向接收者传递消息的速度永远不会超过这个限制。

11.1.11. 死消息(Dead Letter)

dead-letter例子让你了解如何定义和处理死消息。有时候消息由于某种原因不能成功 地传递出去,比如接收者在接收消息的交易中发生回滚。

发生回滚后,消息被”退回“到JMS目标(destination)准备进行重发。这一过程可能会被不停地重复下去造成 消息永远发不出去,而且浪费系统的时间。

为了避免上述情况的发生,消息系统引入了死消息的概念:即当一个消息被反复重发不成功达到一定的次数时,该消息 便成为了死消息,它将从所属目标(destination)中删除并发送到一个称为死消息目标的目标。用户可以从死消息目标           上接收这些死消息以便进行分析。

11.1.12. 延迟再发送

delayed-redelivery是一个展示如何配置HornetQ延迟再发送消息的例子。

当客户端经常发生故障或发生事务回滚时,消息会不停地重复发送,这样会造成CPU和网络资源被不间断的 重复发送所占用,影响其它工作的进行。延迟再发送可以有效地减轻这种情况。

11.1.13. 转移(Divert)

HornetQ通过配置可以将消息从一个地址自动地转移到另一地址。这个例子就是向用户展示转移的配置和使用。

11.1.14. 持久订阅(Durable Subscription)

durable-subscription是一个在HornetQ中如何使用持久订阅(durable subscription)的例子。持久订阅是标准JMS的一部分,在JMS 1.1规范中有它的详细定义。

对于一个持久订阅来说,它的消息可以在订阅没有处于接收状态时被保留。另外,如果发到它的消息是持久 消息的话,这些消息可以在服务器故障或重启时不丢失。

11.1.15. 嵌入方式(Embedded)

embedded是一个如何将HornetQ服务嵌入到你的应用中的例子。

11.1.16. HTTP 传输协议的支持

http-transport展示了HornetQ如何支持在传输层使用HTTP协议来发送和接收消息。

11.1.17. 直接实例化JMS对象

JMS 对象是指 连接工厂(ConnectionFactory)队列(Queue)话题(Topic) 的实例。通常情况下它们通过JNDI服务 来获取。它们在JMS术语中被称为“被管理的对象(administered objects)”。

有的时候客户端没有JNDI服务可用,或者不适合使用JNDI。那么在没有JNDI的情况下HornetQ允许直接在客户端 将这些JMS对象实例化。

11.1.18. 拦截器(Interceptor)

HornetQ可以配置拦截器以便用户可以自己处理各种各样的消息事件。这个例子就是给用户展示如何使用 拦截器。

11.1.19. JAAS

jaas是一个如何配置JAAS安全模式的例子。HornetQ可以使用JAAS来进行用户的验证与权限控制。

11.1.20. JMS桥(Bridge)

jms-brige是一个在两个单独HornetQ服务器之间设置桥的例子。

11.1.21. JMX管理

jmx例子展示了如何使用JMX来管理HornetQ。

11.1.22. 大消息

large-message例子给用户展示了使用HornetQ来发送和接收大消息的功能。HornetQ 支持超大消息的发送与接收。这些消息可以大到内存无法装下。它的大小只受服务器的硬盘空间的限制。

在服务器端大消息是被持久化的,所以它可以承受服务器的崩溃或重启而不丢失或损坏。

11.1.23. 最新值队列

last-value-queue向用户展示了如何定义与使用最新值队列。当在配置文件定义好 最新值的参数后,这些最新值队列就会自动地用新的消息取代旧的消息,也就是说旧的消息被抛弃掉。这样一个最新 值的队列总是保留最新的消息在队列中。

股票价格消息就是一个典型的最新值队列的用例。对用户来说他所关心的是一支股票的最新价格,对于过去的价格 是没有多大兴趣的。

11.1.24. 分布式队列的负载均衡

clustered-queue例子中配置了一个2节点的HornetQ服务集群。在集群上部署了 一个分布式JMS队列。

然后在一个节点上创建了一个发送者(producer),在两个节点上分别创建一个接收者(consumer)。通过 发送者向队列发送一些消息然后被两的接收者以轮流(round-robin)的方式接收。

本例说明了HornetQ可以将消息向集群中的每个接收者分布式地传递消息。

11.1.25. 管理

management例子展示的是如何使用JMS消息来实现对HornetQ的管理。

11.1.26. 管理通知

management-notification展示了HornetQ如何以JMS消息的形式向用户发送 管理通知。当某些事件发生时(如接收都创建,关闭;地址创建与删除;安全验证失败等等),HornetQ会向客户 发出JMS消息以通知客户这些事件的相关信息。客户接收到这些信息后可以作出相应的处理。

11.1.27. 消息计数器

message-counters是一个展示如何使用消息计数器获取JMS队列中的消息信息。

11.1.28. 消息失效

expiry例子中包括了如何定义和使用消息失效期。消息如果在消息服务器中存留超过一定 的时间,就可以被删除。根据JMS规范,接收者就不应该接收到已经过了失效期的消息。(但是并不保证一定接收不到)。

HornetQ可以给一个队列配上一个失效地址,当队列中的消息失效时,它们就会从队列中删除并转移到该失效地址。 这些“失效"的消息可以从失效地址中接收并进行分析。

11.1.29. 消息组

message-group展示的是如何在HornetQ中配置消息组。消息组可以让你的消息 只被一个接收者接收。属于一个消息组中的消息有如下特性:

  • 同一个消息组中的消息都有相同的组ID。即它们的JMSXGroupID属性值相同。

  • 第一个接收到消息组中的消息的接收者将会接收到所有该组中的消息。

11.1.30. 消息组(例2)

message-group2是另外一个消息组的例子。它展示的是通过配置连接工厂来实现 消息组的功能。

11.1.31. 消息优先级

消息优先级会影响消息的传递顺序。

消息优先级由标准的JMS消息头属性JMSPriority的值确定。参见JMS 1.1规范。

优先级是一个0到9之间的整数值。当消息被传递时,根据优先级的不同消息的传递顺序会收到影响。优先级 高的消息往往会比优先级低的先传递给接收者。

优先级相同的消息会按照它们到达目标的顺序来传递。在JMS 1.1规范中有详细的规定。

11.1.32. 零接收缓冲

默认时HornetQ的接收者客户端有一个消息缓冲,它用来保存从服务器上预先接收的消息。这样做是为了提高 性能。因为如果没有这个缓冲,每次调用receive()或onMessage()后,HornetQ就会访问一次服务器请求下 一个消息。

这样每接收一个消息就会增加一次网络往返的传输。因此,HornetQ在默认情况下使用客户端的接收缓冲来 预先接收消息,以提高效率。

然而在某些情况下这样的缓冲不符合应用需要。那么可以将缓冲关闭。本例就是展示如何关闭接收缓冲。

11.1.33. 带有服务器数据复制的非事务失效备援

non-transaction-failover例子展示了由两个服务器组成的高可获得性主/从关系。 客户端使用一个非交易的JMS会话(session)可以在主节点崩溃的情况下从主节点失效备援到备份节点。

HornetQ的这一功能是通过主、备节点间的状态复制来实现的。当主节点发生故障崩溃时,客户端的连接可以自动 转向备份节点以继续的发送或接收消息。当使用非事务性的会话时,有可能发生消息丢失或重复传递的情况。

11.1.34. 分页(paging)

paging例子展示了HornetQ在内存有限时如何支持超大容量的队列。当内存不够时, HornetQ会将消息保存到磁盘上;需要时再将它们从磁盘读入内存。这一过程对用户是透明的。

11.1.35. 预先通知

标准的JMS支持3种通知模式: AUTO_ACKNOWLEDGE(自动通知)、CLIENT_ACKNOWLEDGE客户通知以及 DUPS_OK_ACKNOWLEDGE可重复通知。请参阅JMS规范和教程来进一步了解这几种通知方式。

所有方式都需要从客户端发通知到服务器端。有时当发生故障时你并不在乎丢失一些消息,这样可以采用在服务器端在消息 传递前进行通知就显得比较合理。本例就是展示如何使用这一HornetQ独有的通知方式。

11.1.36. 消息发送速度限制

producer-rte-limit例子展示了如何设置HornetQ的最大消息发送速率。它控制消息的 发送者(JMS producer)发送消息的最大速度。

11.1.37. 队列

这一个简单的JMS队列的例子。

11.1.38. Message再分配

queue-message-redistribution例子展示了如何将消息在集群的各节点同名的队列 间进行再分配。

11.1.39. 队列请求

这是一个简单的实现队列请求的例子。

11.1.40. 带消息选择器(selector)的队列

queue-selector例子展示了如何使用选择器来有条件地选择消息进行接收。

11.1.41. 节点连接重试

reattach-node例子展示了如何使客户端在发生故障时重试连接到原有服务器,而不是 直接放弃并通知用户的ExceptionListener。通过配置,客户端可以自动的不断重试连接直到服务器连接上为止。

11.1.42. 请求/应答

一个简单的展示JMS 请求/应答消息方式的例子。

11.1.43. 定时消息

scheduled-message例子展示了如何向HornetQ发送定时消息(scheduled message)。 所谓定时消息就是在规定的将来的某一时间传递的消息。

11.1.44. 安全

security例子展示了如何配置HornetQ的安全参数。

11.1.45. 发送通知

send-acknowledgements例子展示了如何使用HornetQ提供的高级异步发送通知功能 (asynchronous send acknowledgements)。这是服务器向客户端通知消息已经 被接收。

11.1.46. SSL传输支持

ssl-enabled例子展示了如何配置使用SSL来发送与接收消息。

11.1.47. 静态消息选择器

static-selector例子展示了如何配置HornetQ核心队列的静态消息选择器(又称过滤器)。

11.1.48. 使用JMS方法来配置静态消息选择器

static-selector-jms例子采用JMS方法来配置HornetQ的队列的静态选择器(过滤器)。

11.1.49. Stomp

stomp例子展示了如何配置HornetQ来发送与接收Stomp消息。

11.1.50. Stomp与Web Sockets

stomp-websockets例子给出了如何配置一个HornetQ服务器直接从Web浏览器 中(需要支持Web Socket)发送和接收Stomp消息。

11.1.51. 对称型集群

symmetric-cluster例子展示如何设置一个HornetQ的对称型集群。

HornetQ的集群配置是非常灵活的。你可以根据需要设置不同的集群结构。最常用的就是对称型的集群了。这是在应用 服务器中常见的集群类型。

对称型的集群具有同一性,即每个节点与其他节点处于同等地位,并且每一个节点都与其他任一节点相连接。

11.1.52. 临时队列

本例展示的是如何使用一个JMS临时队列(temporary queue)。

11.1.53. 话题(Topic)

一个简单的JMS topic的例子。

11.1.54. 话题体系(Topic Hierarchy)

HornetQ支持话题体系。所谓话题体系就是允许你使用通配符来注册一个订阅(subscriber),这样所有发送到 与该通配符相匹配的地址的消息都可以被该订阅收到。

11.1.55. 话题选择器例1

topic-selector-example1例子展示的是如何创建带有选择器的JMS话题(Topic)订阅。

11.1.56. 话题选择器例2

topic-selector-example2 是另一个使用带有选择器的JMS话题(Topic)订阅的例子。

11.1.57. 带有数据复制的事务性失效备援

transaction-failover例子展示了由两个服务器组成的高可获得性主/备关系。 客户端使用一个交易的JMS会话(session)可以在主节点崩溃的情况下从主节点失效备援到备份节点。

HornetQ的这一功能是通过主、备节点间的状态复制来实现的。当主节点发生故障崩溃时,客户端的连接可以自动 转向备份节点以继续的发送或接收消息。当使用事务性的会话时,能够保证消息被传递并且只被传递一次。

11.1.58. 事务性会话

transactional例子展示了如何在HornetQ中使用事务性会话。

11.1.59. XA Heuristic

xa-heuristic例子给出了如何通过HornetQ的管理接口来做出一个XA的heuristic决定。 一个XA的heuristic决定是一个单方面的对一个已经准备的(prepared)XA事务分支提交或回滚的决定。

11.1.60. XA 接收

xa-receive例子展示的是如何使用HornetQ在一个XA事务内接收消息。

11.1.61. XA 发送

xa-send例子展示的是如何使用HornetQ在一个XA事务内发送消息。

11.1.62. XA与事务管理器(transaction manager)

xa-with-jta展示了如何在HornetQ中使用JTA接口来控制事务。

11.2. 核心API的例子

运行核心API的例子很简单,只要进到相应的例子目录下运行“ant"即可。

11.2.1. 嵌入式

本例展示了如何将HornetQ服务器嵌入到你的代码中。

11.3. Java EE 例子

绝大多数的Java EE例子都可以按如下步骤运行:进入到相应的目录中,先运行ant deploy。 这一步创建了一个新的JBoss的服务器配置方案并启动它。当JBoss服务器启动后,再运行ant run 启动例子程序。有些例子需要额外的步骤,请参见相关的例子的文档。

11.3.1. EJB/JMS 事务

这个例子展示了在一个事务内使用EJB和JMS的方法。

11.3.2. HAJNDI (High Availability)

这个例子展示了如何使用集群中的JNDI服务。

11.3.3. 资源适配器的配置(JCA)

本例展示了如何配置HornetQ的JCA适配器的各种参数。

11.3.4. 资源适配器运程服务器的配置

本例展示了如何配置HornetQ的JCA适配器来与远程的HornetQ服务器通迅。

11.3.5. JMS 桥(Bridge)

本例展示了如何使用HornetQ的JMS bridge。

11.3.6. MDB (消息驱动Bean)

一个消息驱动bean的例子。

11.3.7. Servlet传输

一个展示在HornetQ中使用servlet作为传输层的例子。

11.3.8. Servlet SSL 传输

一个展示在HornetQ中使用基于SSL之上的servlet传输的例子。

11.3.9. XA 恢复(recovery)

这是一个展示HornetQ在JBoss应用服务器中的XA recovery是如何工作的例子。