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 & {:keys [concurrency decode? host], :or {concurrency 1, decode? true}, :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]
   :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 & 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 :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 hash 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]

receive

(receive dest & {:keys [timeout decode?], :or {timeout 10000, decode? true}, :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 nil is returned. 0 means wait forever,
              -1 means don't wait at all [10000]
  :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]

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 begin with 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 [default]:
  :durable    whether messages persist across restarts [true]
  :selector   a JMS (SQL 92) expression to filter published messages [nil]

stop

(stop name & {:keys [force]})
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.

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