Skip to content

Configuring RabbitMQ for Martini

RabbitMQ is a robust messaging broker using the Advanced Message Queuing Protocol (AMQP), facilitating seamless message exchange. While RabbitMQ is not inherently a Java Message Service (JMS) provider, it offers JMS API compatibility through its JMS topic exchange plugin and JMS client libraries. This flexibility allows systems like Martini Runtime to establish connectivity with RabbitMQ, leveraging its powerful message-brokering capabilities for diverse application needs.

Broker Configuration

To start things off, you are required to configure your RabbitMQ setup and successfully verify all of it's functionality. You can refer to the RabbitMQ Documentation for the initial setup.

In addition, ensure the following Prerequisites are added to ensure that RabbitMQ will function properly with Martini Runtime. 

1
rabbitmq-plugins enable rabbitmq_jms_topic_exchange

1
rabbitmq-plugins enable rabbitmq_management

Info

After downloading the required libraries, Go to the installed location of your Martini and place the files in \/lib/ext.

Authentication & Authorization

For a Local Setup, the default credentials of RabbitMQ will suffice. However, with a Remote Setup, you cannot connect to a remote host using the default credentials. It is recommended to create a new user, or a set of users with the necessary permissions to gain access to your RabbitMQ Console. For more information, refer to their official documentation here.

Martini Configuration

In this section, we'll go through the initial steps to configure Martini Runtime and establish connectivity with RabbitMQ. This setup will include the bare minimum configurations to be connected to RabbitMQ and enable robust message brokering capabilities.

Configuration

  1. Use the Configuration File:

Open \/conf/overrides/override.properties and add or change the following property: 

1
jms.configuration-file=rabbitmq
  1. Modify the Configuration File:

Locate the rabbitmq.xml file within the Martini Directory, specifically, it is located at <martini-home>/conf/broker/rabbitmq.xml. Make the following configurations below based on your scenario.

  • For a Local RabbitMQ Setup, the bare minimum configuration is to change the uri property value under the RabbitMQ Connection Factory bean to:
1
<property name="uri" value="amqp://{broker-ip-address}:{port}"/>
  • For a Remote RabbitMQ Setup, the following properties must also be edited for Martini to establish a successful connection with RabbitMQ.

!!! tip Use the credentials that you have created as username and password for Martini to be given authorization. Refer to the Authentication & Authorization section for more details.

1
2
3
1.  <property name="uri" value="amqp://{broker-ip-address}:{port}"/>
2.  <property name="username" value="{username}"/>
3.  <property name="password" value="{password}/>

Lastly, apply the following configurations for Martini to utilize the RabbitMQ Management Plugin API located under the RabbitMQ Management Rest Broker Stats bean.

1
2
3
1. <constructor-arg name="baseUrl" value="http://{broker-ip-address}:{port}/api"
2. <constructor-arg name="username" value="{username}"/>
3. <constructor-arg name="password" value="{password}"/>
  1. Restart Martini:

Restart your Martini Instance for the configuration changes to take effect. Verify the connection status under the Connections tab using the RabbitMQ management plugin.

AMQP Messaging

RabbitMQ uses the Advanced Message Queuing Protocol (AMQP) by default, for messaging. AMQP provides a standardized, reliable message exchange between applications.

Martini's runtime is adept at both publishing and receiving JMS messages. However, special measures are required for dealing with AMQP message formats, underscoring the importance of thorough preparation and understanding of RabbitMQ's capabilities and limitations.

Sending AMQP Messages with Martini CLI

AMQP Messages

With the use of Martini CLI, Martini can interact with RabbitMQ to create and publish messages. To start, locate and start your Martini Runtime.

For further insight, you can execute Martini Runtime with a debug parameter to see logs in real-time. 

1
./toro-martini or ./toro-martini debug

When Startup has finished, access Martini CLI using the command:

1
java -jar toro-martini-cli.jar

Now, the Martini CLI can be used in a wide variety of ways. You can execute the help command to learn more. In this case, we need to access a Martini Server Runtime Instance. To connect, execute this command with the necessary credentials. 

1
connect --uri {address} --client-id {username} --client-secret {password}

Once you're able to successfully login, you can use the help command to explore the functionalities of Martini CLI. For this instance, using the command list-destination should show your available queues in RabbitMQ.

!!! info You can also show your available queues in RabbitMQ using the API Explorer

1
2
3
4
  1. Open a web browser and navigate to `[HOST]:8080/api-explorer/` to access the API Explorer.
  2. Locate and click on the `broker` tag within the API Explorer to view various broker configuration and operation endpoints.
  3. Use the `/esbapi/broker/destinations` endpoint found under the `broker` tag to list available destinations.
  4. Execute the request using the `GET` method at the `/esbapi/broker/destinations` endpoint.

To send an AMQP message, the amqp parameter must be set to true in the destination string. If exchangeName and routingKey are not specified, they will assume default values.

1
publish-string --destination {uri} --value {string}

The URI can be queue://{name}?amqp=true.

!!! warning Sending an AMQP-formatted message to a JMS queue may lead to deserialization issues, especially if the queue bindings involve jms.durable.queues exchange.

JMS Messaging

RabbitMQ doesn't natively support JMS. However, it can be integrated with JMS systems by using a bridge or plugin, such as RabbitMQ's JMS Client or by converting JMS to AMQP. These tools allow you to receive JMS messages in a RabbitMQ environment by mapping JMS concepts (e.g., topics, queues) to RabbitMQ equivalents.

!!! warning It's important to acknowledge that the RabbitMQ JMS client currently does not offer a full implementation of the JMS API. This partial support may lead to connection issues or messages not being delivered as expected. Given these constraints, Martini defaults to utilizing an in-memory broker for handling WebSocket messages, thereby excluding RabbitMQ from WebSocket message routing.

Sending JMS Messages

To send JMS Messages, you can follow the same method of sending a message with AMQP.

Queue

When sending a JMS message to a RabbitMQ queue, the destination is automatically created if it does not exist. However, ensure pre-existing destination queues are configured with classic queue type, Durable durability, and true auto-delete.

1
publish-string --destination {uri} --value {string}

!!! danger Failure to meet these configurations results in a PRECONDITION_FAILED error in the Martini Runtime logs.

Topic

Unlike queues, topics in RabbitMQ are not created upon message sending but through subscription, i.e., creating a JMS listener endpoint. Topics are assigned auto-generated names like jms-cons-{UUID} and not registered under the destination name in RabbitMQ. Sending messages to a topic is straightforward and does not require specific configurations.

Using API Explorer

  1. Open a web browser and navigate to [HOST]:8080/api-explorer/ to access the API Explorer.
  2. Locate and click on the broker tag within the API Explorer to view various broker configuration and operation endpoints.
  3. Choose a endpoint and the type you want to use for sending messages:
  4. To publish a string, use /esbapi/broker/destinations/{type}/{name}/sendString.
  5. To publish an object, use /esbapi/broker/destinations/{type}/{name}/sendObject.

!!! warning Sending objects to a RabbitMQ Queue will only work if the amqp parameter is set to false.

  1. For the type field, you can type queue. For the name field, specify the destination name you want to send to.
  2. Execute the request using the POST method at the chosen endpoint.