在HornetQ的发布包中有超过70个不同的例子。这些例子直接可以运行。它们分别展示了HornetQ所具有的各种功能。
所有的例子都在HornetQ发布包的 examples目录下。所有的例子被分成了两大类: JMS例子和内核例子。JMS例子展现的是JMS的各种功能,内核的例子则展示的是内核API的功能。
此外HornetQ还提供了一些Java EE的例子,这些例子需要JBoss应用服务器才能运行。
要运行一个JMS例子,只要进入到相应例子的子目录,运行 ./build.sh (或者 在Windows平台上运行build.bat)即可。
下面列出的这些JMS例子并配有简要的说明。
HornetQ支持应用层的失效备援。这在服务器端没有复制(replication)配置的情况下是很有用的。
应用程序可以注册一个JMS ExceptionListener。当HornetQ检测到连接故障时,它会 通知这个注册的Listener。
这个ExceptionListener在接到HornetQ的通知后可以与其它的节点创建 新的连接、会话等对象,以使应用程序能继续运行。
应用层的失效备援是实现高可获得性(HA)的一种方法。它与自动失效备援不同之处在于它需要编写额外的代码。 同时由于发生故障时旧的会话结束,这会造成那些还没来得及提交的工作丢失,还会造成任何没有通知的消息被重发。
bridge例子展示的是将一个内核桥部署到一个服务器上,从本地的queue接收消息并将其转发到 另一服务器的地址上。
内核的bridge可用来在两个互相分开的HornetQ的服务器间建立一个消息流。它可以处理临时性的连接故障,特别适用于 不可靠的网络的情况。广域网就是一个例子。
browser例子展示的是在HornetQ中如何使用JMS QueueBrowser。
有关JMS queue的概念在JMS 1.1 specification有明确的定义,这里就不再叙述。
一个QueueBrowser可以用来观察queue中的消息而影响它们。它可以观察queue中的全部 消息,也可以定义一个选择器(selector)来选择性地察看消息。
client-side-load-balancing例子展示的是通过一个JMS连接可以在集群的不同节点上创建 会话。也就是说HornetQ可以对客户端的会话创建进行集群内的负载均衡。
clustered-queue 例子将一个JMS queue部署到两个节点上。这两个节点组成一个集群。 我们在每个节点上各创建一个接收者(consumer),但只在其中一个节点上创建一个发送者(producer)。利用发送者 发送一些消息,然后确认两个接收者以轮换方式(round-robin)接收这些消息。
clustered-standalone例子所展示的是如何在同一台机器上配置并运行 3个节点的集群。在每个节点上都创建了一个JMS topic的订阅者(subscriber)。只在其中一个节点上 创建了一相发送者来向这个topic发送一些消息。然后我们确认所有的subscriber都接收到了这些消息。
clustered-topic例子将一个JMS topic部署到两个节点上。这两个节点组成一个集群。 然后在每个节点上创建了一个订阅者(subscriber),只在一个节点上创建一个发送者(producer)。通过这个发 送者发送一些消息,确认两个订阅者都收到了这些消息。
HornetQ可以控制一个JMS消息接收者接收消息的速度。这是在创建或部署连接工厂时通过其配置参数来完成的。
如果设置了这个速度的限制,HornetQ会保证其向接收者传递消息的速度永远不会超过这个限制。
dead-letter例子让你了解如何定义和处理死消息。有时候消息由于某种原因不能成功 地传递出去,比如接收者在接收消息的交易中发生回滚。
发生回滚后,消息被”退回“到JMS目标(destination)准备进行重发。这一过程可能会被不停地重复下去造成 消息永远发不出去,而且浪费系统的时间。
为了避免上述情况的发生,消息系统引入了死消息的概念:即当一个消息被反复重发不成功达到一定的次数时,该消息 便成为了死消息,它将从所属目标(destination)中删除并发送到一个称为死消息目标的目标。用户可以从死消息目标 上接收这些死消息以便进行分析。
delayed-redelivery是一个展示如何配置HornetQ延迟再发送消息的例子。
当客户端经常发生故障或发生事务回滚时,消息会不停地重复发送,这样会造成CPU和网络资源被不间断的 重复发送所占用,影响其它工作的进行。延迟再发送可以有效地减轻这种情况。
durable-subscription是一个在HornetQ中如何使用持久订阅(durable subscription)的例子。持久订阅是标准JMS的一部分,在JMS 1.1规范中有它的详细定义。
对于一个持久订阅来说,它的消息可以在订阅没有处于接收状态时被保留。另外,如果发到它的消息是持久 消息的话,这些消息可以在服务器故障或重启时不丢失。
JMS 对象是指 连接工厂(ConnectionFactory)、队列(Queue)和话题(Topic) 的实例。通常情况下它们通过JNDI服务 来获取。它们在JMS术语中被称为“被管理的对象(administered objects)”。
有的时候客户端没有JNDI服务可用,或者不适合使用JNDI。那么在没有JNDI的情况下HornetQ允许直接在客户端 将这些JMS对象实例化。
large-message例子给用户展示了使用HornetQ来发送和接收大消息的功能。HornetQ 支持超大消息的发送与接收。这些消息可以大到内存无法装下。它的大小只受服务器的硬盘空间的限制。
在服务器端大消息是被持久化的,所以它可以承受服务器的崩溃或重启而不丢失或损坏。
last-value-queue向用户展示了如何定义与使用最新值队列。当在配置文件定义好 最新值的参数后,这些最新值队列就会自动地用新的消息取代旧的消息,也就是说旧的消息被抛弃掉。这样一个最新 值的队列总是保留最新的消息在队列中。
股票价格消息就是一个典型的最新值队列的用例。对用户来说他所关心的是一支股票的最新价格,对于过去的价格 是没有多大兴趣的。
在clustered-queue例子中配置了一个2节点的HornetQ服务集群。在集群上部署了 一个分布式JMS队列。
然后在一个节点上创建了一个发送者(producer),在两个节点上分别创建一个接收者(consumer)。通过 发送者向队列发送一些消息然后被两的接收者以轮流(round-robin)的方式接收。
本例说明了HornetQ可以将消息向集群中的每个接收者分布式地传递消息。
management-notification展示了HornetQ如何以JMS消息的形式向用户发送 管理通知。当某些事件发生时(如接收都创建,关闭;地址创建与删除;安全验证失败等等),HornetQ会向客户 发出JMS消息以通知客户这些事件的相关信息。客户接收到这些信息后可以作出相应的处理。
expiry例子中包括了如何定义和使用消息失效期。消息如果在消息服务器中存留超过一定 的时间,就可以被删除。根据JMS规范,接收者就不应该接收到已经过了失效期的消息。(但是并不保证一定接收不到)。
HornetQ可以给一个队列配上一个失效地址,当队列中的消息失效时,它们就会从队列中删除并转移到该失效地址。 这些“失效"的消息可以从失效地址中接收并进行分析。
message-group展示的是如何在HornetQ中配置消息组。消息组可以让你的消息 只被一个接收者接收。属于一个消息组中的消息有如下特性:
同一个消息组中的消息都有相同的组ID。即它们的JMSXGroupID属性值相同。
第一个接收到消息组中的消息的接收者将会接收到所有该组中的消息。
消息优先级会影响消息的传递顺序。
消息优先级由标准的JMS消息头属性JMSPriority的值确定。参见JMS 1.1规范。
优先级是一个0到9之间的整数值。当消息被传递时,根据优先级的不同消息的传递顺序会收到影响。优先级 高的消息往往会比优先级低的先传递给接收者。
优先级相同的消息会按照它们到达目标的顺序来传递。在JMS 1.1规范中有详细的规定。
默认时HornetQ的接收者客户端有一个消息缓冲,它用来保存从服务器上预先接收的消息。这样做是为了提高 性能。因为如果没有这个缓冲,每次调用receive()或onMessage()后,HornetQ就会访问一次服务器请求下 一个消息。
这样每接收一个消息就会增加一次网络往返的传输。因此,HornetQ在默认情况下使用客户端的接收缓冲来 预先接收消息,以提高效率。
然而在某些情况下这样的缓冲不符合应用需要。那么可以将缓冲关闭。本例就是展示如何关闭接收缓冲。
non-transaction-failover例子展示了由两个服务器组成的高可获得性主/从关系。 客户端使用一个非交易的JMS会话(session)可以在主节点崩溃的情况下从主节点失效备援到备份节点。
HornetQ的这一功能是通过主、备节点间的状态复制来实现的。当主节点发生故障崩溃时,客户端的连接可以自动 转向备份节点以继续的发送或接收消息。当使用非事务性的会话时,有可能发生消息丢失或重复传递的情况。
paging例子展示了HornetQ在内存有限时如何支持超大容量的队列。当内存不够时, HornetQ会将消息保存到磁盘上;需要时再将它们从磁盘读入内存。这一过程对用户是透明的。
标准的JMS支持3种通知模式: AUTO_ACKNOWLEDGE(自动通知)、CLIENT_ACKNOWLEDGE客户通知以及 DUPS_OK_ACKNOWLEDGE可重复通知。请参阅JMS规范和教程来进一步了解这几种通知方式。
所有方式都需要从客户端发通知到服务器端。有时当发生故障时你并不在乎丢失一些消息,这样可以采用在服务器端在消息 传递前进行通知就显得比较合理。本例就是展示如何使用这一HornetQ独有的通知方式。
reattach-node例子展示了如何使客户端在发生故障时重试连接到原有服务器,而不是 直接放弃并通知用户的ExceptionListener。通过配置,客户端可以自动的不断重试连接直到服务器连接上为止。
send-acknowledgements例子展示了如何使用HornetQ提供的高级异步发送通知功能 (asynchronous send acknowledgements)。这是服务器向客户端通知消息已经 被接收。
stomp-websockets例子给出了如何配置一个HornetQ服务器直接从Web浏览器 中(需要支持Web Socket)发送和接收Stomp消息。
symmetric-cluster例子展示如何设置一个HornetQ的对称型集群。
HornetQ的集群配置是非常灵活的。你可以根据需要设置不同的集群结构。最常用的就是对称型的集群了。这是在应用 服务器中常见的集群类型。
对称型的集群具有同一性,即每个节点与其他节点处于同等地位,并且每一个节点都与其他任一节点相连接。
HornetQ支持话题体系。所谓话题体系就是允许你使用通配符来注册一个订阅(subscriber),这样所有发送到 与该通配符相匹配的地址的消息都可以被该订阅收到。
transaction-failover例子展示了由两个服务器组成的高可获得性主/备关系。 客户端使用一个交易的JMS会话(session)可以在主节点崩溃的情况下从主节点失效备援到备份节点。
HornetQ的这一功能是通过主、备节点间的状态复制来实现的。当主节点发生故障崩溃时,客户端的连接可以自动 转向备份节点以继续的发送或接收消息。当使用事务性的会话时,能够保证消息被传递并且只被传递一次。
xa-heuristic例子给出了如何通过HornetQ的管理接口来做出一个XA的heuristic决定。 一个XA的heuristic决定是一个单方面的对一个已经准备的(prepared)XA事务分支提交或回滚的决定。
绝大多数的Java EE例子都可以按如下步骤运行:进入到相应的目录中,先运行ant deploy。 这一步创建了一个新的JBoss的服务器配置方案并启动它。当JBoss服务器启动后,再运行ant run 启动例子程序。有些例子需要额外的步骤,请参见相关的例子的文档。