Skip to content

Configuring ActiveMQ Classic for Martini

ActiveMQ Classic can be connected to by the Martini Server Runtime, providing the capability to integrate with an external instance. This integration allows users to leverage the robust messaging features of ActiveMQ, facilitating efficient communication between applications. By configuring the connection settings, developers can utilize the external broker for message sending and receiving, enhancing the overall scalability and performance of their messaging workflows.

Prerequisites

Before configuring Martini Server Runtime to connect with an ActiveMQ Classic broker, ensure the following prerequisite is met:

  • Apache ActiveMQ Classic: Ensure your message broker is running. You can follow guides for setup here: Standalone or Docker Container.

Connect to a Remote ActiveMQ Classic instance

  1. Configure Martini's connection properties in the <martini-home>/conf/overrides/override.properties.

    Configuration properties: These properties represent the bare minimum requirements needed to get started with the application.

    1
2
3
    jms.configuration-file=activemq-external
# The URL of the remote broker. 
activemq.uri=tcp://[HOST]:61616

    Authentication properties: If you are using the default credentials, you can skip the following properties. For guidance on setting up authentication, refer to the documentation here.

    1
2
3
4
5
6
    # Sets the login when connecting to a remote ActiveMQ broker.
# If unspecified, Martini will use 'guest' for the login.
activemq.username=[username]
# Sets the password when connecting to a remote ActiveMQ broker.
# If unspecified, Martini will use 'guest' for the password.
activemq.password=[password]

    JMS properties: These settings will prevent Martini colliding with different instances with the default properties.

    1
2
3
4
5
6
    # The value of this property must be unique among clients connected to the ActiveMQ instance.
# This is used to identify the name of the Martini instance in the ActiveMQ connections.
jms.client-id=[client-id]
# The prefix is added to mitigate overlapping JMS destinations and to distinguish between different Martini instances connected to a single message broker.
# It adds a prefix to the beginning of a queue and topic; for example: `your-prefix.io.lonti.martini`
jms.destination-prefix=your-prefix

  2. Restart Martini Server Runtime to apply the changes.

  3. Verify connection establishment.
1
2
3
4
5
6
7
8
9
   INFO [MartiniBrokerConfiguration] Using broker configuration at '<martini-home>/conf/broker/activemq-external.xml'
   ```

   ## Master / Slave setup

For improved performance and high availability, consider configuring ActiveMQ in a master / slave setup. This configuration is particularly beneficial for Martini's performance, especially when handling search indices. For more information, refer to [Introduction to Master / Slave](https://activemq.apache.org/components/classic/documentation/masterslave) by Apache.

```properties
activemq.uri=failover:(tcp://broker1:61616,tcp://broker2:61616,tcp://broker3:61616)

Failover Transport setup

For improved redundancy, consider configuring ActiveMQ in a Failover setup. This setup ensures continuous operation during broker failures, failover allows for seamless reconnection without manual intervention, which simplifies the application's architecture and improves user experience. It guarantees message delivery, preventing data loss and maintaining integrity, while also enabling load balancing through broker redundancy. For more information, refer to The Failover Transport by Apache.

1
activemq.uri=failover:(tcp://broker1:61616,tcp://broker2:61616)?initialReconnectDelay=100

Using an Embedded ActiveMQ Classic Instance

Martini Server Runtime also has an embedded ActiveMQ broker and is used by default for development purposes. However, for enhanced performance and reliability in production environments, it is strongly recommended to switch to an external instance of ActiveMQ. An external instance offers greater scalability, improved resource management, and better overall performance, making it a more suitable choice for production-level deployments.

1
INFO [MartiniBrokerConfiguration] Using broker configuration at '<martini-home>/conf/broker/activemq-embedded.xml'

Advanced properties

These properties will optimize the performance of ActiveMQ Classic on Martini. Adjust them according to the needs of your applications.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
# The maximum amount of times the message is redelivered to the queue
# before it is thrown to the DLQ (Dead Letter Queue).
# If unspecified, this is set to 6.
# Use -1 to set it to an unlimited amount.
activemq.maximum-redeliveries=5

# The amount of time (in milliseconds) before a message is to be redelivered.
# If unspecified, this is set to -1.
activemq.maximum-redelivery-delay=5000

# Set to true to acknowledge receipt of messages back to the broker in batches (to improve performance).
# If unspecified, defaults to 'true'.
activemq.optimize-acknowledge=true

# The percentage (%) threshold applied to Martini's total allocated JVM memory which,
# when exceeded, will cause the destination's cursor to either block or be written
# to disk while waiting to be processed.
#
# Be careful when setting the value as this may lead to OOM if improperly configured.
activemq.cursor-memory-high-water-mark=25

# If true, ActiveMQ connections will send messages asynchronously.
# This adds a massive performance boost, but could lead to message loss
# since there is no guarantee that messages have been sent or not.
# If unspecified, defaults to 'true'.
activemq.send-asynchronously=true

# If true, advisory topics are created which can be used to receive information
# regarding what is happening on your JMS provider,
# along with what's happening with producers, consumers and destinations.
# If unspecified, defaults to 'false'.
activemq.watch-topic-advisories=true

# A hint to set the maximum size of the message data logs.
# By default, this is set to 32MB.
activemq.maximum-data-log-size=33554432

#Controls storage space usage by the ActiveMQ broker
#Configure the maximum storage limit for broker usage
#defaults to 100GB (https://activemq.apache.org/xml-configuration)
# 107374182400 in bytes
activemq.broker-storage-limit-size=107374182400

Transport Connectors

Transport connectors define the protocols by which clients connect to Martini's embedded ActiveMQ broker. While Martini comes with TCP and VM transports configured out-of-the-box for JMS messaging, additional transport connectors like MQTT, STOMP, and AMQP can be optionally configured if those specific protocols are required. Each transport connector can be customized with specific settings for security, protocol-specific configurations, and performance tuning, but this additional configuration is only necessary if you need to support messaging protocols beyond the default JMS implementation.

Prerequisites

For MQTT, STOMP, and AMQP to function properly, you must first download the following dependencies in the Maven Repository. These dependencies will ensure that your Martini Server Runtime will be able leverage its embedded ActiveMQ broker.

Add the following dependencies in <martini-home>/lib/ext:

Warning

For the Transport Connector Protocols, ensure you download the appropriate versions, as Martini Server Runtime's Transport Factory can only recognize class file versions up to 5.x.x.

For MQTT: 1. ActiveMQ: MQTT Protocol - The ActiveMQ MQTT Protocol Implementation. 2. MQTT Client - Provides an ASL 2.0 licenced API to MQTT.

For STOMP: 1. ActiveMQ: STOMP Protocol - The ActiveMQ STOMP Protocol Implementation.

For AMQP: 1. ActiveMQ: AMQP Protocol - The ActiveMQ implementation of the AMQP Messaging Protocol. 2. Proton J - is a Java-based AMQP (Advanced Message Queuing Protocol) implementation made especially to manage AMQP communications between servers and clients. It is a component of the Apache Qpid project, which offers many implementations of message brokers and clients that are AMQP compatible.

For AMQP, you will need an AMQP-compliant client. Integrating Qpid JMS and Proton J allows you to utilize an embedded ActiveMQ Classic broker as an AMQP-compliant client. This setup offers a JMS API that simplifies AMQP 1.0 messaging, enabling secure, high-performance communication and support for advanced messaging patterns, all within a lightweight application environment. For more information, you can refer to their documentation here.

Adding a Transport Connector

To add a transport connector:

  1. Open the activemq-embedded.xml file located at <martini-home>/conf/broker.
  2. Locate the transportConnectors property under the broker bean.
  3. Modify the connector's properties according to your requirements.
  4. Add a new TransportConnector bean with the desired URI for the new transport protocol. For the transport-protocol value, you can choose from either mqtt, stomp, or amqp. xml <bean class="org.apache.activemq.broker.TransportConnector"> <property name="name" value="[transport-protocol]"/> <property name="uri" value="[transport-protocol]://[IP]:[PORT]"/> </bean>
  5. Save the file and restart Martini Server Runtime to apply the changes.

Editing a Transport Connector

To edit a transport connector:

  1. Modify the existing TransportConnector bean elements in the activemq-embedded.xml file.
  2. Save the changes and restart Martini Server Runtime to reflect the updates.

Removing a Transport Connector

To remove a transport connector:

  1. Comment out or remove the corresponding TransportConnector bean element from the activemq-embedded.xml file.
  2. Save the file and restart Martini Server Runtime as needed.

Testing

To test your broker's messaging capabilities, refer to the following:

  1. MQTT
  2. STOMP
  3. AMQP

Refer to JMS Messaging to learn more about sending and receiving JMS messages.