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)

Subscription Guidelines for Non-Durable Queues

Clients should subscribe non-durably (i.e., without passing a subscription header) to a QUEUE (NOT TOPIC) named Consumers..greatclient.sandbox., where can be transaction, transfer, customer, etc. For instance, a client might name their queue Consumers.app1.greatclient.sandbox.transfer, where the second segment (app1) is user-defined, and all other segments adhere to the Fifth Third naming convention.

Key Points:

• Multiple Subscribers: Clients can have multiple subscribers to this queue, all of which will compete for messages. Each message will be delivered to only one subscriber per queue name.
• Message Delivery: No message will be delivered to different subscribers of the same-named queue.

Steps to Create Additional Subscriptions

1. Determine the Topic:

   • Purpose: Identify the specific type of message you want to consume. This is crucial because it defines the category of events you are interested in.
   • Example: If you want to consume messages related to transfers, the topic would be greatclient.sandbox.transfer.

2. Create Additional Subscriptions:

   • Purpose: Set up subscriptions for the identified topic. This allows multiple applications or instances to receive messages from the same topic.
   • Example: To consume messages sent to greatclient.sandbox.transfer, you can create subscriptions to Consumers..greatclient.sandbox..

3. Use a Specific Queue Name:

   • Purpose: Define a unique queue name for each subscription to ensure proper message delivery and avoid conflicts.
   • Example: You might use Consumers.app2.greatclient.sandbox.transfer for the second application.

Practical Application

• Scenario: If a client wants a second application to also consume messages sent to greatclient.sandbox.transfer, they can create additional subscriptions to Consumers..greatclient.sandbox.. For instance, they might use Consumers.app2.greatclient.sandbox.transfer.

Example Scenario

Consider a client with the following queue subscriptions:

If Fifth Third sends four messages ("Hello A", "Hello B", "Hello C", "Hello D"), they might be delivered to the consumer queues as follows:

Unsubscribing from a Topic

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