Subscriptions

Quick Start: Subscribing to a Topic

The below is a guide for how to establish a Subscription with Newline's MQ. If you're new to MQ implementations, we'd advise reviewing some of the great Apache Active MQ docs linked below. They help give context to the example code provided.

• Clients must set up subscriptions for each topic Newline enables. Subscription requests must include the prefix “/topic/” ahead of the topic name. For example: /topic/abc-enterprises.sandbox.transaction. Newline will provide both credentials and the preset topic prefixes that Clients can utilize when setting up each subscription.
• The example below, taken from the ruby Stomp gem documentation (here and here), demonstrates one method for setting up a subscription. Other methods are possible, depending on your choice of protocol and implementation language.
  • For ease of access, please refer to the Apache documentation used as reference for the below example.
    • Apache Active MQ, Stomp
    • Apache Active MQ, How does a queue compare to a topic?
    • Apache Active MQ, How do durable queues and topics work?
  • Rows 19 and 20 in the example capture the Newline provided username and password values. The host and port values depend on the protocol Clients select.
  • Row 30 demonstrates the “/topic/topic_name” syntax.
• Newline's MQ will also only deliver one copy of a message to Subscriptions that share the same Subscription ID (see Row 11 below). Clients can use this functionality to create a fault-tolerant model by standing up multiple Subscriptions with the same ID, so in the case one fails, they won't miss a message.

📘

Note

Utilizing the example and supplied libraries above will help jumpstart any implementation with MQ. Our teams can support other protocols or implementation languages. If required, please inform your Newline Specialist so they can appropriately prepare and advise.

A recent experience suggested that we might provide an example of how
to establish a "durable" topic subscription using ActiveMQ.
This code attemps to do that. 
References:
See Newline documentation: https://developers.newline53.com/docs/subscriptions
Specifically, locate the section titled: ActiveMQ extensions to Stomp.
There are two programmatic requirements:
1) On CONNECT, indicate to AMQ that the code will be using a durable topic 
subscription(s).
Done by providing a "client-id" CONNECT header.
2) On SUBSCRIBE, indicate an AMQ specific (unique) subscription ID. Done
by providing a "activemq.subscriptionName" header to SUBSCRIBE.
=end

# login hash
hash = { :host => [
			 {:login => login(), :passcode => passcode(), :host => host(), :port()
       		:ssl => true}, #
     ],
     :reliable => true,
       								 :closed_check => false,
     :connect_headers => {:host => "localhost", :"accept-version" => "1.2",
     	 # Requirement 1, name should be unique.
       :"client-id" => "dursubcli01", # REF the 1st AMQ link above
       								 }
   }
# The topic 
topic = "/topic/topicName"

# Establish the client connection
cli = Stomp::Client.open(hash)
# SUBSCRIBE Headers
sh = {"activemq.subscriptionName" => "subname01" } # REF the 1st AMQ link above
# And the client subscribe
cli.subscribe(topic, sh) do |msg|
	puts "msg: #{msg}"
end

# Unsubscribe when we are done subscribing for now:
cli.unsubscribe(topic)

Unsubscribing from a Topic

• Clients can unsubscribe from topics by submitting an unsubscribe request as outlined on line 40 of the example above.