JBoss.org Community Documentation

- Prev
- Next

## Chapter 6. Pushing Messages

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.

## 6.1. The Queue Push Subscription XML

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"/>
    </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 `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:

destination

  The href URL is assumed to be a queue or topic resource of another HornetQ REST server. The push registration will initially do a HEAD request to this URL to obtain a msg-create-with-id header. It will use this header to push new messages to the HornetQ REST endpoint reliably. Here's an example:

      <push-registration>
         <link rel="destination" href="http://somewhere.com/queues/jms.queue.foo"/>
      </push-registration>

template

  In this case, the server is expecting the link element's href attribute to be a URL expression. The URL expression must have one and only one URL parameter within it. The server will use a unique value to create the endpoint URL. Here's an example:

      <push-registration>
         <link rel="template" href="http://somewhere.com/resources/{id}/messages" method="PUT"/>
      </push-registration>

  In this example, the {id} sub-string is the one and only one URL parameter.

user defined

  If the rel attributes is not destination or template (or is empty or missing), then the server will send an HTTP message to the href URL using the HTTP method defined in the method attribute. Here's an example:

      <push-registration>
         <link href="http://somewhere.com" type="application/json" method="PUT"/>
      </push-registration>

## 6.2. The Topic Push Subscription XML

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>

## 6.3. Creating a Push Subscription at Runtime

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:

1. First do a HEAD request to the queue resource:

       HEAD /queues/jms.queue.bar HTTP/1.1
       Host: example.com

       --- Response ---
       HTTP/1.1 200 Ok
       msg-create: http://example.com/queues/jms.queue.bar/create
       msg-pull-consumers: http://example.com/queues/jms.queue.bar/pull-consumers
       msg-push-consumers: http://example.com/queues/jms.queue.bar/push-consumers

2. Next POST your subscription XML to the URL returned from msg-push-consumers header

       POST /queues/jms.queue.bar/push-consumers
       Host: example.com
       Content-Type: application/xml

       <push-registration>
          <link rel="destination" href="http://somewhere.com/queues/jms.queue.foo"/>
       </push-registration>

       --- Response ---
       HTTP/1.1 201 Created
       Location: http://example.com/queues/jms.queue.bar/push-consumers/1-333-1212

   The Location header contains the URL for the created resource. If you want to unregister this, then do a HTTP DELETE on this URL.

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

1. First do a HEAD request to the topic resource:

       HEAD /topics/jms.topic.bar HTTP/1.1
       Host: example.com

       --- Response ---
       HTTP/1.1 200 Ok
       msg-create: http://example.com/topics/jms.topic.bar/create
       msg-pull-subscriptions: http://example.com/topics/jms.topic.bar/pull-subscriptions
       msg-push-subscriptions: http://example.com/topics/jms.topic.bar/push-subscriptions

2. Next POST your subscription XML to the URL returned from msg-push-subscriptions header

       POST /topics/jms.topic.bar/push-subscriptions
       Host: example.com
       Content-Type: application/xml

       <push-registration>
          <link rel="template" href="http://somewhere.com/resources/{id}"/>
       </push-registration>

       --- Response ---
       HTTP/1.1 201 Created
       Location: http://example.com/topics/jms.topic.bar/push-subscriptions/1-333-1212

   The Location header contains the URL for the created resource. If you want to unregister this, then do a HTTP DELETE on this URL.

## 6.4. Creating a Push Subscription by Hand

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>

## 6.5. Pushing to Authenticated Servers

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>

- PrevChapter 5. Consuming Messages via Pull
- Top of page
- Front page
- NextChapter 7. Creating Destinations