Apache ActiveMQ Artemis is designed to allow extra functionality to be added by creating a plugin. Multiple plugins can be registered at the same time and they will be chained together and executed in the order they are registered (i.e. the first plugin registered is always executed first).

Creating a plugin is very simple. It requires:

Only the methods that you want to add behavior for need to be implemented as all of the interface methods are default methods.

1. Registering a Plugin

To register a plugin with by XML you need to add the broker-plugins element at the broker.xml. It is also possible to pass configuration to a plugin using the property child element(s). These properties (zero to many) will be read and passed into the plugin’s init(Map<String, String>) operation after the plugin has been instantiated.

<broker-plugins>
   <broker-plugin class-name="some.plugin.UserPlugin">
      <property key="property1" value="val_1" />
      <property key="property2" value="val_2" />
   </broker-plugin>
</broker-plugins>

2. Registering a Plugin Programmatically

For registering a plugin programmatically you need to call the registerBrokerPlugin() method and pass in a new instance of your plugin. In the example below assuming your plugin is called UserPlugin, registering it looks like the following:

...

Configuration config = new ConfigurationImpl();
...

config.registerBrokerPlugin(new UserPlugin());

3. Using the LoggingActiveMQServerPlugin

The LoggingActiveMQServerPlugin logs specific broker events.

You can select which events are logged by setting the following configuration properties to true.

Property Trigger Event Default Value

LOG_CONNECTION_EVENTS

Connection is created/destroy.

false

LOG_SESSION_EVENTS

Session is created/closed.

false

LOG_CONSUMER_EVENTS

Consumer is created/closed

false

LOG_DELIVERING_EVENTS

Message is delivered to a consumer and when a message is acknowledged by a consumer.

false

LOG_SENDING_EVENTS

When a message has been sent to an address and when a message has been routed within the broker.

false

LOG_INTERNAL_EVENTS

When a queue created/destroyed, when a message is expired, when a bridge is deployed and when a critical failure occurs.

false

LOG_ALL_EVENTS

Includes all the above events.

false

By default the LoggingActiveMQServerPlugin will not log any information. The logging is activated by setting one (or a selection) of the above configuration properties to true.

To configure the plugin, you can add the following configuration to the broker. In the example below both LOG_DELIVERING_EVENTS and LOG_SENDING_EVENTS will be logged by the broker.

<broker-plugins>
   <broker-plugin class-name="org.apache.activemq.artemis.core.server.plugin.impl.LoggingActiveMQServerPlugin">
      <property key="LOG_DELIVERING_EVENTS" value="true" />
      <property key="LOG_SENDING_EVENTS" value="true" />
   </broker-plugin>
</broker-plugins>

Most events in the LoggingActiveMQServerPlugin follow a beforeX and afterX notification pattern (e.g beforeCreateConsumer() and afterCreateConsumer()).

At Log Level INFO, the LoggingActiveMQServerPlugin logs an entry when an afterX notification occurs. By setting the logger org.apache.activemq.artemis.core.server.plugin.impl to DEBUG, log entries are generated for both beforeX and afterX notifications. Log level DEBUG will also log more information for a notification when available.

4. Using the NotificationActiveMQServerPlugin

The NotificationActiveMQServerPlugin can be configured to send extra notifications for specific broker events.

You can select which notifications are sent by setting the following configuration properties to true.

Property Property Description Default Value

SEND_CONNECTION_NOTIFICATIONS

Sends a notification when a Connection is created/destroy.

false

SEND_SESSION_NOTIFICATIONS

Sends a notification when a Session is created/closed.

false

SEND_ADDRESS_NOTIFICATIONS

Sends a notification when an Address is added/removed.

false

SEND_DELIVERED_NOTIFICATIONS

Sends a notification when message is delivered to a consumer.

false

SEND_EXPIRED_NOTIFICATIONS

Sends a notification when message has been expired by the broker.

false

By default the NotificationActiveMQServerPlugin will not send any notifications. The plugin is activated by setting one (or a selection) of the above configuration properties to true.

To configure the plugin, you can add the following configuration to the broker. In the example below both SEND_CONNECTION_NOTIFICATIONS and SEND_SESSION_NOTIFICATIONS will be sent by the broker.

<broker-plugins>
   <broker-plugin class-name="org.apache.activemq.artemis.core.server.plugin.impl.NotificationActiveMQServerPlugin">
      <property key="SEND_CONNECTION_NOTIFICATIONS" value="true" />
      <property key="SEND_SESSION_NOTIFICATIONS" value="true" />
   </broker-plugin>
</broker-plugins>

5. Using the BrokerMessageAuthorizationPlugin

The BrokerMessageAuthorizationPlugin filters messages sent to consumers based on if they have a role that matches the value specified in a message property.

You can select which property will be used to specify the required role for consuming a message by setting the following configuration.

Property Property Description Default Value

ROLE_PROPERTY

Property name used to determine the role required to consume a message.

requiredRole.

If the message does not have a property matching the configured ROLE_PROPERTY then the message will be sent to any consumer.

To configure the plugin, you can add the following configuration to the broker. In the example below ROLE_PROPERTY is set to permissions when that property is present messages will only be sent to consumers with a role matching its value.

<broker-plugins>
   <broker-plugin class-name="org.apache.activemq.artemis.core.server.plugin.impl.BrokerMessageAuthorizationPlugin">
      <property key="ROLE_PROPERTY" value="permissions" />
   </broker-plugin>
</broker-plugins>

6. Using the ConnectionPeriodicExpiryPlugin

The ConnectionPeriodicExpiryPlugin will implement a global expiry (and disconnect) for connections that live longer than periodSeconds on a matching acceptor basis.

This plugin can be useful when credential rotation or credential validation must be enforced at regular intervals as authentication will be enforced on reconnect.

The plugin requires the configuration of the acceptorMatchRegex to determine the acceptors to monitor. It is typical to separate client acceptors and federation or cluster acceptors such that only client connections will be subject to periodic expiry. The acceptorMatchRegex must be configured to match the name of the acceptor(s) whose connections will be subject to periodic expiry.

Property Property Description Default Value

acceptorMatchRegex

the regular expression used to match against the names of acceptors to monitor

periodSeconds

the max period, in seconds, that a connection can last

900 seconds (15 minutes)

accuracyWindowSeconds

determines how often we check connections for expiry and also provides an upper bound on the random seconds we use to schedule a disconnect. Using a random second will potentially avoid many reconnects occurring at the exact same time. It must be positive value > 0

30 seconds

The plugin can be configured via xml in the normal broker-plugin way:

<broker-plugins>
   <broker-plugin class-name="org.apache.activemq.artemis.core.server.plugin.impl.ConnectionPeriodicExpiryPlugin">
      <property key="acceptorMatchRegex" value="netty-client-acceptor" />
   </broker-plugin>
</broker-plugins>