Amazon MQ Starter Kit

Amazon MQ starter kit described in AWS blog Implementing FIFO message ordering with Amazon MQ for Apache ActiveMQ

CloudFormation Templates & Supporting Resources

Template	Purpose
CF_Template_AmazonMQBroker.yaml	Sample template to provision Amazon MQ broker
custom-broker-configuration.xml	Sample Broker Configuration File

Setup Instructions

1. Clone or download this source code

2. Import the source code to Eclipse or IntelliJ IDEA as a Maven project

3. Build the project using Maven commands

4. This will generate a jar file with name amazon-mq-fifo-starter-kit-1.0.jar

5. Provision Amazon MQ Broker using CF_Template_AmazonMQBroker.yaml

   Note: To make the set up easy, you can provision the broker in a public subnet with a security group that has inbound access from your Laptop / EC2 instance. For production deployments, check the following resources:

   • Using Amazon MQ Securely
   • Accessing the ActiveMQ Web Console of a Broker without Public Accessibility

6. Optionally, you can use AWS Management Console to provision broker by following this AWS Blog

7. From AWS Management Console, go to Amazon MQ, select the broker, and make a note of the below values. You will need them to access Broker console and run the PoC.

   1. ActiveMQ Web Console URL
   2. OpenWire Endpoint URL

8. Configure Security Group from Broker details section on AWS Console as shown in the below screenshot.

Running the Starter Kit from a local IDE

1. Find out the Public IP address of your system and follow step # 8 of Setup Instructions
2. Run the program AmazonMQFIFOStarterKit with the following program arguments separated by a space
   1. Amazon MQ OpenWire Endpoint URL
   2. Amazon MQ username
   3. Amazon MQ password
   4. Number of messages to be inserted per producer

Running the Starter Kit from Command-line on your Laptop

1. Go to the folder /amazon-mq-fifo-starter-kit/target and run the jar file.

   java -jar amazon-mq-fifo-starter-kit-1.0.jar \
   Replace_this_with_OpenWire_Endpoint_URL \
   Replace_this_with_AmazonMQ_UserName \
   Replace_this_with_AmazonMQ_Password \
   5000

Running the Starter Kit from an EC2 Instance

1. Launch an EC2 instance with an IAM role that has read and write permission on DynamoDB.

2. Take the Private IP address of your EC2 instance and follow step # 8 of Setup Instructions

3. Log on to EC2 instance and do the following:

   sudo yum -y install java-1.8.0-openjdk.x86_64
   mkdir amazon-mq-starter-kit
   cd amazon-mq-starter-kit/

4. Copy the Jar file amazon-mq-fifo-starter-kit-1.0.jar from your Laptop to EC2 instance using secure copy (SCP) or PuTTY:

   1. An example SCP command is below:

      scp -i ec2_keypair.pem amazon-mq-fifo-starter-kit-1.0.jar 
      ec2-user@IP_Address_of_EC2:/home/ec2-user/amazon-mq-starter-kit

   2. To use PuTTY, refer Connecting to Your Linux Instance from Windows Using PuTTY

5. Run the Java Application

   java -jar amazon-mq-fifo-starter-kit-1.0.jar \
   Replace_this_with_OpenWire_Endpoint_URL \
   Replace_this_with_AmazonMQ_UserName \
   Replace_this_with_AmazonMQ_Password \
   5000

6. The above step generates message metrics in CSV files. Use the following command to import them back to your Laptop for analysis.

   scp -i /The_Path_To/ec2_keypair.pem ec2-user@IP_Address_of_EC2:/home/ec2-user/amazon-mq-starter-kit/*.csv .

Scenarios Demonstrated: Multiple producers and consumers with Message Groups

Scenario 1: All consumers started at the same time

Test Case Description	Java Class
The driver program to execute all test cases	AmazonMQFIFOStarterKit
Queue with 3 producers, 3 message groups, 1 consumer	FIFO_Testcase_1
Queue with 3 producers, 3 message groups, 2 consumers	FIFO_Testcase_2
Queue with 3 producers, 3 message groups, 3 consumers	FIFO_Testcase_3
Queue with 3 producers, 3 message groups, 4 consumers	FIFO_Testcase_4
Queue with 4 producers, 4 message groups, 3 consumers	FIFO_Testcase_5

Scenario 2a: All consumers not started at same time

Test Case Description	Java Class
Queue with 3 producers, 3 message groups, 3 consumers	FIFO_Testcase_6

Scenario 2b: All consumers not started at same time – mitigate consumer message distribution by closing message groups

Test Case Description	Java Class
Queue with 3 producers, 3 message groups, 3 consumers	FIFO_Testcase_7

Tags

Amazon MQ, Enterprise Messaging, Queues, FIFO, Message Ordering

License Summary

This sample code is made available under the MIT-0 license. See the LICENSE file.