JBoss.orgCommunity Documentation
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 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>
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.
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>
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:
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
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:
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
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.
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>