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).
* Implementing the https://github.com/apache/activemq-artemis/blob/main/artemis-server/src/main/java/org/apache/activemq/artemis/core/server/plugin/ActiveMQServerPlugin.java[`ActiveMQServerPlugin`] interface
* Making sure the plugin is xref:using-server.adoc#adding-runtime-dependencies[on the classpath]
* Registering it with the broker either via <<registering-a-plugin,xml>> or <<registering-a-plugin-programmatically,programmatically>>.
Only the methods that you want to add behavior for need to be implemented as all of the interface methods are default methods.
== 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.
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.
== 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.
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.
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:
