immutant.messaging documentation

Easily publish and receive messages containing any type of nested
data structure to dynamically-created topics and queues. Message
distribution is automatically load-balanced when clustered.

*raw-message*

var

Will be bound to the raw javax.jms.Message during the invocation of a
destination listener.

as-queue

(as-queue name)
Marks the given queue name as a queue. Useful for working with queues that
don't follow the Immutant convention of containing "queue" in the name.
The result can be passed to any immutant.messaging functions that take a
queue name.

as-topic

(as-topic name)
Marks the given topic name as a topic. Useful for working with topics that
don't follow the Immutant convention of containing "topic" in the name.
The result can be passed to any immutant.messaging functions that take a
topic name.

listen

(listen dest f & {:as opts})
The handler function, f, will receive each message sent to dest.
 dest can either be the name of the destination, a
 javax.jms.Destination, or the result of as-queue or as-topic. If
 a :selector is provided, then only messages having
 metadata/properties matching that expression may be received.

 listen is asynchronous - if you need to synchronize on its
 completion, you should deref the result.

 The following options are supported [default]:
   :concurrency  the number of threads handling messages [1]
   :xa           Whether the handler demarcates an XA transaction [true]
   :selector     A JMS (SQL 92) expression matching message metadata/properties [nil]
   :decode?      if true, the decoded message body is passed to f. Otherwise, the
                 javax.jms.Message object is passed [true]
   :client-id    identifies a durable topic subscriber, ignored for queues [nil]
   :host         the remote host to connect to (default is to connect in-vm) [nil]
   :port         the remote port to connect to (requires :host to be set) [nil,
                 or 5445 if :host is set]
   :username     the username to use to auth the connection (requires :password
                 to be set) [nil]
   :password     the password to use to auth the connection (requires :username
                 to be set) [nil]

The following options are for connection reconnection/reattachment attributes:
   :retry-interval             the period in milliseconds between subsequent
                               reconnection attempts
   :retry-interval-multiplier  a multiplier to apply to the time since the last
                               retry to compute the time to the next retry
   :max-retry-interval         the max retry interval that will be used [2000]
   :reconnect-attempts         total number of reconnect attempts to make before giving
                               up and shutting down (-1 for unlimited) [0]

message-seq

(message-seq dest & {:as opts})
A lazy sequence of messages received from a destination. Accepts
same options as receive.

publish

(publish dest message & {:as opts})
Send a message to a destination. dest can either be the name of the
destination, a javax.jms.Destination, or the result of as-queue or
as-topic. If the message is a javax.jms.Message, then the message
is sent without modification.  If the message contains metadata, it
will be transferred as JMS properties and reconstituted upon
receipt. Metadata keys must be valid Java identifiers (because they
can be used in selectors) and can be overridden using
the :properties option. Returns the JMS message object that was
published.

The following options are supported [default]:
  :encoding        :clojure :edn :fressian :json or :text [:edn]
  :priority        0-9 or :low :normal :high :critical [4]
  :ttl             time to live, in ms [0=forever]
  :persistent      whether undelivered messages survive restarts [true]
  :properties      a map to which selectors may be applied, overrides metadata [nil]
  :correlation-id  used to set the JMSCorrelationID [nil]
                   see http://docs.oracle.com/javaee/6/api/javax/jms/Message.html#setJMSCorrelationID(java.lang.String) 
  :host            the remote host to connect to (default is to connect in-vm)
                   [nil]
  :port            the remote port to connect to (requires :host to be set)
                   [nil, or 5445 if :host is set]
  :username        the username to use to auth the connection (requires :password
                   to be set) [nil]
  :password        the password to use to auth the connection (requires :username
                   to be set) [nil]
  :connection      a JMS Connection to use; caller expected to close [nil]

receive

(receive dest & {:as opts})
Receive a message from a destination. dest can either be the name
of the destination, a javax.jms.Destination, or the result of
as-queue or as-topic. If a :selector is provided, then only
messages having metadata/properties matching that expression may be
received.

The following options are supported [default]:
  :timeout     time in ms, after which the timeout-val is returned. 0
               means wait forever, -1 means don't wait at all [10000]
  :timeout-val the value to return when a timeout occurs. Also returned when
               a timeout of -1 is specified, and no message is available [nil]
  :selector    A JMS (SQL 92) expression matching message metadata/properties [nil]
  :decode?     if true, the decoded message body is returned. Otherwise, the
               javax.jms.Message object is returned [true]
  :client-id   identifies a durable topic subscriber, ignored for queues [nil]
  :host        the remote host to connect to (default is to connect in-vm) [nil]
  :port        the remote port to connect to (requires :host to be set) [nil, or
               5445 if :host is set]
  :username    the username to use to auth the connection (requires :password to
               be set) [nil]
  :password    the password to use to auth the connection (requires :username to
               be set) [nil]
  :connection  a JMS Connection to use; caller expected to close [nil]

request

(request queue message & {:as opts})
Send a message to queue and return a delay that will retrieve the response.
Implements the request-response pattern, and is used in conjunction
with respond. The queue parameter can either be the name of a
queue, an actual javax.jms.Queue, or the result of as-queue.

It takes the same options as publish.

respond

(respond queue f & {:keys [decode? ttl], :or {decode? true, ttl 60000}, :as opts})
Listen for messages on queue sent by the request function and
respond with the result of applying f to the message. queue can
either be the name of the queue, a javax.jms.Queue, or the result
of as-queue. Accepts the same options as listen, along with [default]:

  :ttl  time for the response mesage to live, in ms [60000, 1 minute]

start

(start name & opts)
Create a message destination; name should contain either 'queue'
or 'topic', or be the result of calling as-queue or as-topic. If
a :selector is provided, then only messages with
metadata/properties matching that expression will be accepted for
delivery.

The following options are supported for queues only [default]:
  :durable    whether messages persist across restarts [true]
  :selector   a JMS (SQL 92) expression to filter published messages [nil]

Additionally, you can pass any of the options expected by
immutant.messaging.hornetq/set-address-options and they
will be applied to the created destination.

stop

(stop name & {:keys [force], :as opts})
Destroy a message destination. Typically not necessary since it
will be done for you when your app is undeployed. This will fail
with a warning if any handlers are listening or any messages are
yet to be delivered unless ':force true' is passed. Returns true on
success.

unlisten

(unlisten listener)
Pass the result of a call to listen or respond to de-register the handler.
You only need to do this if you wish to stop the handler's
destination before your app is undeployed.

unlisten is asynchronous - if you need to synchronize on its
completion, you should deref the result. The result of the
call. The deref will resolve to a boolean that is true if there was
actually something to unlisten, false otherwise.

unsubscribe

(unsubscribe client-id & {:keys [subscriber-name], :or {subscriber-name default-subscriber-name}, :as opts})
Used when durable topic subscribers are no longer interested. This
cleans up some server-side state, but since it'll be be deleted
anyway when the topic is stopped, it's an optional call.

with-connection

macro

(with-connection options & body)
Can be used to set default options for the messaging functions
called within its body. More importantly, the nested calls will
re-use the JMS Connection created by this function unless the
nested calls' connection-related options differ.