messaging-changes.clj

(defn ^Context context
  "Creates a messaging context.

   A context represents a remote or local connection to the messaging
   broker.

   There are three reasons you would create a context rather
   than rely on the messaging functions to lazily create them as
   needed:

   1) for communicating with a remote HornetQ instance
   2) for sharing a context among a batch of messaging operations
   3) for decoupling the client-id from the subscription name for
      durable topic subscriptions (see [[subscribe]])

   You are responsible for closing any contexts created via this
   function.

   Options that apply to both local and remote contexts are [default]:

   * :client-id - identifies the context for use with a durable topic
                  subscriber (see [[subscribe]]) [nil]
   * :xa?       - if true, returns an XA context for use in a
                  distributed transaction [false]
   * :mode      - one of: :auto-ack, :client-ack, :transacted. Ignored
                  if :xa? is true. [:auto-ack]

   Options that apply to only remote contexts are [default]:

   * :host - the host of a remote broker [nil]
   * :port - the port of a remote broker [nil, 5445 if :host provided]
   * :username - a username for the remote broker [nil]
   * :password - the corresponding password for :username [nil]
   * :remote-type - when connecting to a HornetQ instance running
                    inside WildFly, this needs to be set to
                    :hornetq-wildfly [:hornetq-standalone]
   * :reconnect-attempts - total number of reconnect attempts to make
                           before giving up (-1 for unlimited) [0]
   * :reconnect-retry-interval - the period in milliseconds between subsequent
                                 recontext attempts [2000]
   * :reconnect-max-retry-interval - the max retry interval that will be used [2000]
   * :reconnect-retry-interval-multiplier - a multiplier to apply to the time
                                            since the last retry to compute the
                                            time to the next retry [1.0]")


(defn subscribe
  "Sets up a durable subscription to `topic`, and registers a listener with `f`.

   `subscription-name` is used to identify the subscription, allowing
   you to stop the listener and resubscribe with the same name in the
   future without losing messages sent in the interim. The subscription
   is uniquely identified by the context's :client-id paired with the
   subscription name. If no :context is provided, a new context is
   created for this subscriber and the subscription name is used as
   the :client-id of the internally-created context. If a context is
   provided, it *must* have its :client-id set.

   If a :selector is provided, then only messages having
   metadata/properties matching that expression may be received.

   The following options are supported [default]:

     * :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]
     * :context      - a context to use; caller expected to close [nil]

   Returns a listener object that can can be stopped by passing it to [[stop]], or by
   calling .close on it.

   Subscriptions should be torn down when no longer needed - see [[unsubscribe]].")

(defn unsubscribe
  "Tears down the durable topic subscription on `topic` named `subscription-name`.


   The subscription is uniquely identified by the context's :client-id
   paired with the subscription name. If no :context is provided, a new
   context is created for this subscriber and the subscription name is
   used as the :client-id of the internally-created context. If a
   context is provided, it *must* have its :client-id set to the same
   value given to the context passed to [[subscribe]].

   The following options are supported [default]:

     * :context   - a context to use; caller expected to close [nil]")