JBoss.orgCommunity Documentation

Chapter 8. Pushing Messages

8.1. The Queue Push Subscription XML
8.2. The Topic Push Subscription XML
8.3. Creating a Push Subscription at Runtime
8.4. Creating a Push Subscription by Hand
8.5. Pushing to Authenticated Servers

You can configure the HornetQ REST server to push messages to a registered URL either remotely through the REST interface, or by creating a pre-configured XML file for the HornetQ REST server to load at boot time.

Creating a push consumer for a queue first involves creating a very simple XML document. This document tells the server if the push subscription should survive server reboots (is it durable). It must provide a URL to ship the forwarded message to. Finally, you have to provide authentication information if the final endpoint requires authentication. Here's a simple example:

<push-registration>
<durable>false</durable>
<selector><![CDATA[
      SomeAttribute > 1
    ]]>
</selector>
<link rel="push" href="http://somewhere.com" type="application/json" method="PUT"/>
<maxRetries>5</maxRetries>
<retryWaitMillis>1000</retryWaitMillis>
<disableOnFailure>true</disableOnFailure>
</push-registration>

The durable element specifies whether the registration should be saved to disk so that if there is a server restart, the push subscription will still work. This element is not required. If left out it defaults to false. If durable is set to true, an XML file for the push subscription will be created within the directory specified by the queue-push-store-dir config variable defined in Chapter 2. (topic-push-store-dir for topics).

The selector element is optional and defines a JMS message selector. You should enclose it within CDATA blocks as some of the selector characters are illegal XML.

The maxRetries element specifies how many times a the server will try to push a message to a URL if there is a connection failure.

The retryWaitMillis element specifies how long to wait before performing a retry.

The disableOnFailure element, if set to true, will disable the registration if all retries have failed. It will not disable the connection on non-connection-failure issues (like a bad request for instance). In these cases, the dead letter queue logic of HornetQ will take over.

The link element specifies the basis of the interaction. The href attribute contains the URL you want to interact with. It is the only required attribute. The type attribute specifies the content-type ofwhat the push URL is expecting. The method attribute defines what HTTP method the server will use when it sends the message to the server. If it is not provided it defaults to POST. The rel attribute is very important and the value of it triggers different behavior. Here's the values a rel attribute can have:

The push XML for a topic is the same except the root element is push-topic-registration. (Also remember the selector element is optional). The rest of the document is the same. Here's an example of a template registration:

<push-topic-registration>
<durable>true</durable>
<selector><![CDATA[
      SomeAttribute > 1
    ]]>
</selector>
<link rel="template" href="http://somewhere.com/resources/{id}/messages" method="POST"/>
</push-topic registration>

Creating a push subscription at runtime involves getting the factory resource URL from the msg-push-consumers header, if the destination is a queue, or msg-push-subscriptions header, if the destination is a topic. Here's an example of creating a push registration for a queue:

Here's an example of creating a push registration for a topic:

You can create a push XML file yourself if you do not want to go through the REST interface to create a push subscription. There is some additional information you need to provide though. First, in the root element, you must define a unique id attribute. You must also define a destination element to specify the queue you should register a consumer with. For a topic, the destination element is the name of the subscription that will be reated. For a topic, you must also specify the topic name within the topic element.

Here's an example of a hand-created queue registration. This file must go in the directory specified by the queue-push-store-dir config variable defined in Chapter 2:

<push-registration id="111">
<destination>jms.queue.bar</destination>
<durable>true>
<link rel="template" href="http://somewhere.com/resources/{id}/messages" method="PUT"/>
</push-registration>

Here's an example of a hand-created topic registration. This file must go in the directory specified by the topic-push-store-dir config variable defined in Chapter 2:

<push-topic-registration id="112">
<destination>my-subscription-1</destination
<durable>true</durable>
<link rel="template" href="http://somewhere.com/resources/{id}/messages" method="PUT"/>
<topic>jms.topic.foo</topic>
</push-topic-registration>

Push subscriptions only support BASIC and DIGEST authentication out of the box. Here is an example of adding BASIC authentication:

<push-topic-registration>
<durable>true</durable>
<link rel="template" href="http://somewhere.com/resources/{id}/messages" method="POST"/>
<authentication>
   <basic-auth>
      <username>guest</username>
      <password>geheim</password>
   </basic-auth>
</authentication>
</push-topic registration>

For DIGEST, just replace basic-auth with digest-auth.

For other authentication mechanisms, you can register headers you want transmitted with each request. Use the header element with the name attribute representing the name of the header. Here's what custom headers might look like:

<push-topic-registration>
<durable>true</durable>
<link rel="template" href="http://somewhere.com/resources/{id}/messages" method="POST"/>
<header name="secret-header">jfdiwe3321</header>
</push-topic registration>