You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@activemq.apache.org by cl...@apache.org on 2018/06/07 15:26:51 UTC
[09/16] activemq-artemis git commit: ARTEMIS-1912 big doc refactor
http://git-wip-us.apache.org/repos/asf/activemq-artemis/blob/2b5d8f3b/docs/user-manual/en/management.md
----------------------------------------------------------------------
diff --git a/docs/user-manual/en/management.md b/docs/user-manual/en/management.md
index 65b0b53..ca523b7 100644
--- a/docs/user-manual/en/management.md
+++ b/docs/user-manual/en/management.md
@@ -1,53 +1,56 @@
# Management
-Apache ActiveMQ Artemis has an extensive *management API* that allows a user to modify a
-server configuration, create new resources (e.g. addresses and queues),
-inspect these resources (e.g. how many messages are currently held in a
-queue) and interact with it (e.g. to remove messages from a queue). Apache ActiveMQ Artemis
-also allows clients to subscribe to management notifications.
+Apache ActiveMQ Artemis has an extensive *management API* that allows a user to
+modify a server configuration, create new resources (e.g. addresses and
+queues), inspect these resources (e.g. how many messages are currently held in
+a queue) and interact with it (e.g. to remove messages from a queue). Apache
+ActiveMQ Artemis also allows clients to subscribe to management notifications.
There are four ways to access Apache ActiveMQ Artemis management API:
-- Using JMX -- *JMX* is the standard way to manage Java applications
+- Using JMX -- *JMX* is the standard way to manage Java applications
-- Using Jolokia -- Jolokia exposes the JMX API of an application through a *REST interface*
+- Using Jolokia -- Jolokia exposes the JMX API of an application through a
+ *REST interface*
-- Using the Core Client -- management operations are sent to Apache ActiveMQ Artemis
- server using *Core Client messages*
+- Using the Core Client -- management operations are sent to Apache ActiveMQ
+ Artemis server using *Core Client messages*
-- Using the Core JMS Client -- management operations are sent to Apache ActiveMQ Artemis
- server using *Core JMS Client messages*
+- Using any JMS Client -- management operations are sent to Apache ActiveMQ
+ Artemis server using *JMS Client messages*
-Although there are four different ways to manage Apache ActiveMQ Artemis, each API supports
-the same functionality. If it is possible to manage a resource using JMX
-it is also possible to achieve the same result using Core messages.
+Although there are four different ways to manage Apache ActiveMQ Artemis, each
+API supports the same functionality. If it is possible to manage a resource
+using JMX it is also possible to achieve the same result using Core messages.
-Besides the programmatic management interfaces, a *Web Console* and a Command Line
-*management utility* are also available to administrators of ActiveMQ Artemis.
+Besides these four management interfaces, a [Web Console](management-console.md)
+and a Command Line *management utility* are also available to administrators of
+ActiveMQ Artemis.
-The choice depends on your requirements, your application settings and
-your environment to decide which way suits you best.
+The choice depends on your requirements, your application settings, and your
+environment to decide which way suits you best.
-> **Note**
+> **Note:**
>
-> In version 2 of Apache ActiveMQ Artemis the syntax used for MBean Object names has changed significantly due to changes
-> in the addressing scheme. See the documentation for each individual resource for details on the new syntax.
+> In version 2 of Apache ActiveMQ Artemis the syntax used for MBean Object
+> names has changed significantly due to changes in the addressing scheme. See
+> the documentation for each individual resource for details on the new syntax.
## The Management API
-Regardless of the way you *invoke* management operations, the management
-API is the same.
+Regardless of the way you *invoke* management operations, the management API is
+the same.
-For each *managed resource*, there exists a Java interface describing
-what operations can be invoked for this type of resource.
+For each *managed resource*, there exists a Java interface describing what
+operations can be invoked for this type of resource.
-To learn about available *management operations*, see the Javadoc
-for these interfaces. They are located in the
+To learn about available *management operations*, see the Javadoc for these
+interfaces. They are located in the
`org.apache.activemq.artemis.api.core.management` package and they are named
with the word `Control` at the end.
-The way to invoke management operations depends on whether JMX, Core
-messages, or Core JMS messages are used.
+The way to invoke management operations depends on whether JMX, Core messages,
+or JMS messages are used.
### Management API
@@ -57,224 +60,219 @@ For full details of the API please consult the Javadoc. In summary:
The `ActiveMQServerControl` interface is the entry point for broker management.
-- Listing, creating, deploying and destroying queues
+- Listing, creating, deploying and destroying queues
- A list of deployed queues can be retrieved using the
- `getQueueNames()` method.
+ A list of deployed queues can be retrieved using the `getQueueNames()`
+ method.
- Queues can be created or destroyed using the management
- operations `createQueue()` or `deployQueue()` or `destroyQueue()`
+ Queues can be created or destroyed using the management operations
+ `createQueue()` or `deployQueue()` or `destroyQueue()`.
- `createQueue` will fail if the queue already exists while
- `deployQueue` will do nothing.
+ `createQueue` will fail if the queue already exists while `deployQueue` will
+ do nothing.
-- Listing and closing remote connections
+- Listing and closing remote connections
- Client's remote addresses can be retrieved using
- `listRemoteAddresses()`. It is also possible to close the
- connections associated with a remote address using the
- `closeConnectionsForAddress()` method.
+ Client's remote addresses can be retrieved using `listRemoteAddresses()`. It
+ is also possible to close the connections associated with a remote address
+ using the `closeConnectionsForAddress()` method.
- Alternatively, connection IDs can be listed using
- `listConnectionIDs()` and all the sessions for a given connection ID
- can be listed using `listSessions()`.
+ Alternatively, connection IDs can be listed using `listConnectionIDs()` and
+ all the sessions for a given connection ID can be listed using
+ `listSessions()`.
-- Transaction heuristic operations
+- Transaction heuristic operations
- In case of a server crash, when the server restarts, it it possible
- that some transaction requires manual intervention. The
- `listPreparedTransactions()` method lists the transactions which are
- in the prepared states (the transactions are represented as opaque
- Base64 Strings.) To commit or rollback a given prepared transaction,
- the `commitPreparedTransaction()` or `rollbackPreparedTransaction()`
- method can be used to resolve heuristic transactions. Heuristically
- completed transactions can be listed using the
- `listHeuristicCommittedTransactions()` and
- `listHeuristicRolledBackTransactions` methods.
+ In case of a server crash, when the server restarts, it it possible that some
+ transaction requires manual intervention. The `listPreparedTransactions()`
+ method lists the transactions which are in the prepared states (the
+ transactions are represented as opaque Base64 Strings.) To commit or rollback a
+ given prepared transaction, the `commitPreparedTransaction()` or
+ `rollbackPreparedTransaction()` method can be used to resolve heuristic
+ transactions. Heuristically completed transactions can be listed using the
+ `listHeuristicCommittedTransactions()` and
+ `listHeuristicRolledBackTransactions` methods.
-- Enabling and resetting Message counters
+- Enabling and resetting Message counters
- Message counters can be enabled or disabled using the
- `enableMessageCounters()` or `disableMessageCounters()` method. To
- reset message counters, it is possible to invoke
- `resetAllMessageCounters()` and `resetAllMessageCounterHistories()`
- methods.
+ Message counters can be enabled or disabled using the
+ `enableMessageCounters()` or `disableMessageCounters()` method. To reset
+ message counters, it is possible to invoke `resetAllMessageCounters()` and
+ `resetAllMessageCounterHistories()` methods.
-- Retrieving the server configuration and attributes
+- Retrieving the server configuration and attributes
- The `ActiveMQServerControl` exposes Apache ActiveMQ Artemis server configuration
- through all its attributes (e.g. `getVersion()` method to retrieve
- the server's version, etc.)
+ The `ActiveMQServerControl` exposes Apache ActiveMQ Artemis server
+ configuration through all its attributes (e.g. `getVersion()` method to
+ retrieve the server's version, etc.)
-- Listing, creating and destroying Core bridges and diverts
+- Listing, creating and destroying Core bridges and diverts
- A list of deployed core bridges (resp. diverts) can be retrieved
- using the `getBridgeNames()` (resp. `getDivertNames()`) method.
+ A list of deployed core bridges (resp. diverts) can be retrieved using the
+ `getBridgeNames()` (resp. `getDivertNames()`) method.
- Core bridges (resp. diverts) can be created or destroyed using the
- management operations `createBridge()` and `destroyBridge()` (resp.
- `createDivert()` and `destroyDivert()`).
+ Core bridges (resp. diverts) can be created or destroyed using the management
+ operations `createBridge()` and `destroyBridge()` (resp. `createDivert()` and
+ `destroyDivert()`).
-- It is possible to stop the server and force failover to occur with
- any currently attached clients.
+- It is possible to stop the server and force failover to occur with any
+ currently attached clients.
- To do this use the `forceFailover()` operation.
+ To do this use the `forceFailover()` operation.
- > **Note**
- >
- > Since this method actually stops the server you will probably
- > receive some sort of error depending on which management service
- > you use to call it.
+ > **Note:**
+ >
+ > Since this method actually stops the server you will probably receive some
+ > sort of error depending on which management service you use to call it.
#### Address Management
Individual addresses can be managed using the `AddressControl` interface.
-- Modifying roles and permissions for an address
+- Modifying roles and permissions for an address
- You can add or remove roles associated to a queue using the
- `addRole()` or `removeRole()` methods. You can list all the roles
- associated to the queue with the `getRoles()` method
+ You can add or remove roles associated to a queue using the `addRole()` or
+ `removeRole()` methods. You can list all the roles associated to the queue with
+ the `getRoles()` method
#### Queue Management
-The bulk of the management API deals with queues. The
-`QueueControl` interface defines the queue management operations.
+The bulk of the management API deals with queues. The `QueueControl` interface
+defines the queue management operations.
-Most of the management operations on queues take either a single message
-ID (e.g. to remove a single message) or a filter (e.g. to expire all
-messages with a given property.)
+Most of the management operations on queues take either a single message ID
+(e.g. to remove a single message) or a filter (e.g. to expire all messages with
+a given property.)
-> **Note**
+> **Note:**
>
-> Passing `null` or an empty string in the `filter` parameter means that
-> the management operation will be performed on *all messages* in a queue.
+> Passing `null` or an empty string in the `filter` parameter means that the
+> management operation will be performed on *all messages* in a queue.
-- Expiring, sending to a dead letter address and moving messages
+- Expiring, sending to a dead letter address and moving messages
- Messages can be expired from a queue by using the `expireMessages()`
- method. If an expiry address is defined, messages will be sent to
- it, otherwise they are discarded. The queue's expiry address can be
- set with the `setExpiryAddress()` method.
+ Messages can be expired from a queue by using the `expireMessages()` method.
+ If an expiry address is defined, messages will be sent to it, otherwise they
+ are discarded. The queue's expiry address can be set with the
+ `setExpiryAddress()` method.
- Messages can also be sent to a dead letter address with the
- `sendMessagesToDeadLetterAddress()` method. It returns the number of
- messages which are sent to the dead letter address. If a dead letter
- address is not defined, message are removed from the queue and
- discarded. The queue's dead letter address can be set with the
- `setDeadLetterAddress()` method.
+ Messages can also be sent to a dead letter address with the
+ `sendMessagesToDeadLetterAddress()` method. It returns the number of messages
+ which are sent to the dead letter address. If a dead letter address is not
+ defined, message are removed from the queue and discarded. The queue's dead
+ letter address can be set with the `setDeadLetterAddress()` method.
- Messages can also be moved from a queue to another queue by using
- the `moveMessages()` method.
+ Messages can also be moved from a queue to another queue by using the
+ `moveMessages()` method.
-- Listing and removing messages
+- Listing and removing messages
- Messages can be listed from a queue by using the `listMessages()`
- method which returns an array of `Map`, one `Map` for each message.
+ Messages can be listed from a queue by using the `listMessages()` method
+ which returns an array of `Map`, one `Map` for each message.
- Messages can also be removed from the queue by using the
- `removeMessages()` method which returns a `boolean` for the single
- message ID variant or the number of removed messages for the filter
- variant. The `removeMessages()` method takes a `filter` argument to
- remove only filtered messages. Setting the filter to an empty string
- will in effect remove all messages.
+ Messages can also be removed from the queue by using the `removeMessages()`
+ method which returns a `boolean` for the single message ID variant or the
+ number of removed messages for the filter variant. The `removeMessages()`
+ method takes a `filter` argument to remove only filtered messages. Setting the
+ filter to an empty string will in effect remove all messages.
-- Counting messages
+- Counting messages
- The number of messages in a queue is returned by the
- `getMessageCount()` method. Alternatively, the `countMessages()`
- will return the number of messages in the queue which *match a given
- filter*.
+ The number of messages in a queue is returned by the `getMessageCount()`
+ method. Alternatively, the `countMessages()` will return the number of messages
+ in the queue which *match a given filter*.
-- Changing message priority
+- Changing message priority
- The message priority can be changed by using the
- `changeMessagesPriority()` method which returns a `boolean` for the
- single message ID variant or the number of updated messages for the
- filter variant.
+ The message priority can be changed by using the `changeMessagesPriority()`
+ method which returns a `boolean` for the single message ID variant or the
+ number of updated messages for the filter variant.
-- Message counters
+- Message counters
- Message counters can be listed for a queue with the
- `listMessageCounter()` and `listMessageCounterHistory()` methods
- (see Message Counters section). The message counters can also be
- reset for a single queue using the `resetMessageCounter()` method.
+ Message counters can be listed for a queue with the `listMessageCounter()`
+ and `listMessageCounterHistory()` methods (see Message Counters section). The
+ message counters can also be reset for a single queue using the
+ `resetMessageCounter()` method.
-- Retrieving the queue attributes
+- Retrieving the queue attributes
- The `QueueControl` exposes queue settings through its
- attributes (e.g. `getFilter()` to retrieve the queue's filter if it
- was created with one, `isDurable()` to know whether the queue is
- durable or not, etc.)
+ The `QueueControl` exposes queue settings through its attributes (e.g.
+ `getFilter()` to retrieve the queue's filter if it was created with one,
+ `isDurable()` to know whether the queue is durable or not, etc.)
-- Pausing and resuming Queues
+- Pausing and resuming Queues
- The `QueueControl` can pause and resume the underlying queue. When a
- queue is paused, it will receive messages but will not deliver them.
- When it's resumed, it'll begin delivering the queued messages, if
- any.
+ The `QueueControl` can pause and resume the underlying queue. When a queue is
+ paused, it will receive messages but will not deliver them. When it's resumed,
+ it'll begin delivering the queued messages, if any.
#### Other Resources Management
-Apache ActiveMQ Artemis allows to start and stop its remote resources (acceptors,
-diverts, bridges, etc.) so that a server can be taken off line for a
-given period of time without stopping it completely (e.g. if other
-management operations must be performed such as resolving heuristic
-transactions). These resources are:
+Apache ActiveMQ Artemis allows to start and stop its remote resources
+(acceptors, diverts, bridges, etc.) so that a server can be taken off line for
+a given period of time without stopping it completely (e.g. if other management
+operations must be performed such as resolving heuristic transactions). These
+resources are:
-- Acceptors
+- Acceptors
- They can be started or stopped using the `start()` or. `stop()`
- method on the `AcceptorControl` interface. The acceptors parameters
- can be retrieved using the `AcceptorControl` attributes (see [Understanding Acceptors](configuring-transports.md))
+ They can be started or stopped using the `start()` or. `stop()` method on the
+ `AcceptorControl` interface. The acceptors parameters can be retrieved using
+ the `AcceptorControl` attributes (see [Understanding
+ Acceptors](configuring-transports.md))
-- Diverts
+- Diverts
- They can be started or stopped using the `start()` or `stop()`
- method on the `DivertControl` interface. Diverts
- parameters can be retrieved using the `DivertControl` attributes
- (see [Diverting and Splitting Message Flows)](diverts.md))
+ They can be started or stopped using the `start()` or `stop()` method on the
+ `DivertControl` interface. Diverts parameters can be retrieved using the
+ `DivertControl` attributes (see [Diverting and Splitting Message
+ Flows)](diverts.md))
-- Bridges
+- Bridges
- They can be started or stopped using the `start()` (resp. `stop()`)
- method on the `BridgeControl` interface. Bridges parameters can be retrieved
- using the `BridgeControl` attributes (see [Core bridges](core-bridges.md))
+ They can be started or stopped using the `start()` (resp. `stop()`) method on
+ the `BridgeControl` interface. Bridges parameters can be retrieved using the
+ `BridgeControl` attributes (see [Core bridges](core-bridges.md))
-- Broadcast groups
+- Broadcast groups
- They can be started or stopped using the `start()` or `stop()`
- method on the `BroadcastGroupControl` interface. Broadcast groups
- parameters can be retrieved using the `BroadcastGroupControl`
- attributes (see [Clusters](clusters.md))
+ They can be started or stopped using the `start()` or `stop()` method on the
+ `BroadcastGroupControl` interface. Broadcast groups parameters can be retrieved
+ using the `BroadcastGroupControl` attributes (see [Clusters](clusters.md))
-- Cluster connections
+- Cluster connections
- They can be started or stopped using the `start()` or `stop()`
- method on the `ClusterConnectionControl` interface. Cluster
- connections parameters can be retrieved using the
- `ClusterConnectionControl` attributes (see [Clusters](clusters.md))
+ They can be started or stopped using the `start()` or `stop()` method on the
+ `ClusterConnectionControl` interface. Cluster connections parameters can be
+ retrieved using the `ClusterConnectionControl` attributes (see
+ [Clusters](clusters.md))
## Using Management Via JMX
Apache ActiveMQ Artemis can be managed using
[JMX](http://www.oracle.com/technetwork/java/javase/tech/javamanagement-140525.html).
-The management API is exposed by Apache ActiveMQ Artemis using MBeans interfaces.
-Apache ActiveMQ Artemis registers its resources with the domain `org.apache.activemq.artemis`.
+The management API is exposed by Apache ActiveMQ Artemis using MBeans
+interfaces. Apache ActiveMQ Artemis registers its resources with the domain
+`org.apache.activemq.artemis`.
-For example, the `ObjectName` to manage the anycast queue `exampleQueue` on the address `exampleAddress` is:
+For example, the `ObjectName` to manage the anycast queue `exampleQueue` on the
+address `exampleAddress` is:
- org.apache.activemq.artemis:broker=<brokerName>,component=addresses,address="exampleAddress",subcomponent=queues,routing-type="anycast",queue="exampleQueue"
+```
+org.apache.activemq.artemis:broker=<brokerName>,component=addresses,address="exampleAddress",subcomponent=queues,routing-type="anycast",queue="exampleQueue"
+```
and the MBean is:
- org.apache.activemq.artemis.api.core.management.QueueControl
+```
+org.apache.activemq.artemis.api.core.management.QueueControl
+```
The MBean `ObjectName`'s are built using the helper class
`org.apache.activemq.artemis.api.core.management.ObjectNameBuilder`. You can
-also use `jconsole` to find the `ObjectName` of the MBean you want to
-manage.
+also use `jconsole` to find the `ObjectName` of the MBean you want to manage.
Example usage of the `ObjectNameBuilder` to obtain `ActiveMQServerControl`'s name:
@@ -284,39 +282,43 @@ objectNameBuilder = ObjectNameBuilder.create(ArtemisResolver.DEFAULT_DOMAIN, bro
serverObjectName = objectNameBuilder.getActiveMQServerObjectName()
```
-Managing Apache ActiveMQ Artemis using JMX is identical to management of any Java
-Applications using JMX. It can be done by reflection or by creating
+Managing Apache ActiveMQ Artemis using JMX is identical to management of any
+Java Applications using JMX. It can be done by reflection or by creating
proxies of the MBeans.
### Configuring JMX
-By default, JMX is enabled to manage Apache ActiveMQ Artemis. It can be disabled by
-setting `jmx-management-enabled` to `false` in
-`broker.xml`:
+By default, JMX is enabled to manage Apache ActiveMQ Artemis. It can be
+disabled by setting `jmx-management-enabled` to `false` in `broker.xml`:
- <!-- false to disable JMX management for Apache ActiveMQ Artemis -->
- <jmx-management-enabled>false</jmx-management-enabled>
-
+```xml
+<!-- false to disable JMX management for Apache ActiveMQ Artemis -->
+<jmx-management-enabled>false</jmx-management-enabled>
+```
+
#### Role Based Authorisation for JMX
-Although by default Artemis uses the Java Virtual Machine's `Platform MBeanServer`
-this is guarded using role based authentication that leverages Artemis's JAAS plugin support.
-This is configured via the `authorisation` element in the `management.xml` configuration file
-and can be used to restrict access to attributes and methods on mbeans.
+Although by default Artemis uses the Java Virtual Machine's `Platform
+MBeanServer` this is guarded using role based authentication that leverages
+Artemis's JAAS plugin support. This is configured via the `authorisation`
+element in the `management.xml` configuration file and can be used to restrict
+access to attributes and methods on mbeans.
-There are 3 elements within the `authorisation` element, `whitelist`, `default-access` and
-`role-access`, Lets discuss each in turn.
+There are 3 elements within the `authorisation` element, `whitelist`,
+`default-access` and `role-access`, Lets discuss each in turn.
-Whitelist contains a list of mBeans that will by pass the authentication, this is typically
-used for any mbeans that are needed by the console to run etc. The default configuration is:
+Whitelist contains a list of mBeans that will by pass the authentication, this
+is typically used for any mbeans that are needed by the console to run etc. The
+default configuration is:
```xml
<whitelist>
<entry domain="hawtio"/>
</whitelist>
```
-This means that any mbean with the domain `hawtio` will be allowed access without authorisation. for instance
-`hawtio:plugin=artemis`. You can also use wildcards for the mBean properties so the following would also match.
+This means that any mbean with the domain `hawtio` will be allowed access
+without authorisation. for instance `hawtio:plugin=artemis`. You can also use
+wildcards for the mBean properties so the following would also match.
```xml
<whitelist>
@@ -324,32 +326,35 @@ This means that any mbean with the domain `hawtio` will be allowed access withou
</whitelist>
```
-The `role-access`defines how roles are mapped to particular mBeans and its attributes and methods,
-the default configuration looks like:
+The `role-access`defines how roles are mapped to particular mBeans and its
+attributes and methods, the default configuration looks like:
```xml
<role-access>
- <match domain="org.apache.activemq.artemis">
- <access method="list*" roles="view,update,amq"/>
- <access method="get*" roles="view,update,amq"/>
- <access method="is*" roles="view,update,amq"/>
- <access method="set*" roles="update,amq"/>
- <access method="*" roles="amq"/>
- </match>
+ <match domain="org.apache.activemq.artemis">
+ <access method="list*" roles="view,update,amq"/>
+ <access method="get*" roles="view,update,amq"/>
+ <access method="is*" roles="view,update,amq"/>
+ <access method="set*" roles="update,amq"/>
+ <access method="*" roles="amq"/>
+ </match>
</role-access>
```
-This contains 1 match and will be applied to any mBean that has the domain `org.apache.activemq.artemis`.
-Any access to any mBeans that have this domain are controlled by the `access` elements which contain a
-method and a set of roles. The method being invoked will be used to pick the closest matching method and
-the roles for this will be applied for access. For instance if you try the invoke a method called `listMessages` on an mBean
-with the `org.apache.activemq.artemis` domain then this would match the `access` with the method of `list*`.
-You could also explicitly configure this by using the full method name, like so:
+This contains 1 match and will be applied to any mBean that has the domain
+`org.apache.activemq.artemis`. Any access to any mBeans that have this domain
+are controlled by the `access` elements which contain a method and a set of
+roles. The method being invoked will be used to pick the closest matching
+method and the roles for this will be applied for access. For instance if you
+try the invoke a method called `listMessages` on an mBean with the
+`org.apache.activemq.artemis` domain then this would match the `access` with
+the method of `list*`. You could also explicitly configure this by using the
+full method name, like so:
```xml
<access method="listMessages" roles="view,update,amq"/>
```
-You can also match specific mBeans within a domain by adding a key attribute that is used to match one of the properties
-on the mBean, like:
+You can also match specific mBeans within a domain by adding a key attribute
+that is used to match one of the properties on the mBean, like:
```xml
<match domain="org.apache.activemq.artemis" key="subcomponent=queues">
@@ -360,9 +365,11 @@ on the mBean, like:
<access method="*" roles="amq"/>
</match>
```
-You could also match a specific queue for instance :
+You could also match a specific queue for instance:
-`org.apache.activemq.artemis:broker=<brokerName>,component=addresses,address="exampleAddress",subcomponent=queues,routing-type="anycast",queue="exampleQueue"`
+```
+org.apache.activemq.artemis:broker=<brokerName>,component=addresses,address="exampleAddress",subcomponent=queues,routing-type="anycast",queue="exampleQueue"
+```
by configuring:
@@ -376,85 +383,111 @@ by configuring:
</match>
```
-Access to JMX mBean attributes are converted to method calls so these are controlled via the `set*`, `get*` and `is*`.
-The `*` access is the catch all for everything other method that isn't specifically matched.
+Access to JMX mBean attributes are converted to method calls so these are
+controlled via the `set*`, `get*` and `is*`. The `*` access is the catch all
+for everything other method that isn't specifically matched.
-The `default-access` element is basically the catch all for every method call that isn't handled via the `role-access` configuration.
-This has teh same semantics as a `match` element.
+The `default-access` element is basically the catch all for every method call
+that isn't handled via the `role-access` configuration. This has teh same
+semantics as a `match` element.
-> **Note**
+> **Note:**
>
-> If JMX is enabled, Apache ActiveMQ Artemis can *not* be managed locally using `jconsole` when connecting as a local process,
-> this is because jconsole does not using any authentication when connecting this way. If you want to use jconsole you will
-either have to disable authentication, by removing the `authentication` element or enable remote access.
+> If JMX is enabled, Apache ActiveMQ Artemis can *not* be managed locally using
+> `jconsole` when connecting as a local process, this is because jconsole does
+> not using any authentication when connecting this way. If you want to use
+> jconsole you will either have to disable authentication, by removing the
+> `authentication` element or enable remote access.
#### Configuring remote JMX Access
By default remote JMX access to Artemis is disabled for security reasons.
-Artemis has a JMX agent which allows access to JMX mBeans remotely. This is configured via the `connector` element in the
-`management.xml` configuration file. To enable this you simply add the following xml:
+Artemis has a JMX agent which allows access to JMX mBeans remotely. This is
+configured via the `connector` element in the `management.xml` configuration
+file. To enable this you simply add the following xml:
```xml
<connector connector-port="1099"/>
```
-This exposes the agent remotely on the port 1099. If you were connecting via jconsole you would connect as a remote process
-using the service url `service:jmx:rmi:///jndi/rmi://localhost:1099/jmxrmi` and an appropriate user name and password.
+This exposes the agent remotely on the port 1099. If you were connecting via
+jconsole you would connect as a remote process using the service url
+`service:jmx:rmi:///jndi/rmi://localhost:1099/jmxrmi` and an appropriate user
+name and password.
You can also configure the connector using the following:
-- connector-host
+- `connector-host`
- The host to expose the agent on
-- connector-port
+ The host to expose the agent on.
+
+- `connector-port`
- The port to expose the agent on
-- jmx-realm
+ The port to expose the agent on.
- The jmx realm to use for authentication, defaults to `activemq` to match the JAAS configuration.
-- object-name
+- `jmx-realm`
- The object name to expose the remote connector on, default is `connector:name=rmi`
-- secured
+ The jmx realm to use for authentication, defaults to `activemq` to match the
+ JAAS configuration.
+
+- `object-name`
- Whether the connector is secured using SSL
-- key-store-path
+ The object name to expose the remote connector on; default is
+ `connector:name=rmi`.
+
+- `secured`
- The location of the keystore
-- key-store-password
+ Whether the connector is secured using SSL.
+
+- `key-store-path`
- The keystore password
-- key-store-provider
- The provider, JKS by default
-- trust-store-path
+ The location of the keystore.
- The location of the truststore
-- trust-store-password
+- `key-store-password`
- The trustore password
-- trust-store-provider
+ The keystore password.
- The provider, JKS by default
+- `key-store-provider`
-> **Note**
+ The provider; `JKS` by default.
+
+- `trust-store-path`
+
+ The location of the truststore.
+
+- `trust-store-password`
+
+ The trustore password.
+
+- `trust-store-provider`
+
+ The provider; `JKS` by default.
+
+> **Note:**
>
-> It is important to note that the rmi registry will pick an ip address to bind to, If you have a multi IP addresses/NICs
-> present on the system then you can choose the ip address to use by adding the following to artemis.profile
+> It is important to note that the rmi registry will pick an ip address to bind
+> to, If you have a multi IP addresses/NICs present on the system then you can
+> choose the ip address to use by adding the following to artemis.profile
> `-Djava.rmi.server.hostname=localhost`
-> **Note**
+> **Note:**
>
-> Remote connections using the default JVM Agent not enabled by default as Artemis exposes the mBean Server via its own configuration.
-> This is so Artemis can leverage the JAAS authentication layer via JMX. If you want to expose this then you will need to
-> disable both the connector and the authorisation by removing them from the `management.xml` configuration.
-> Please refer to [Java Management guide](https://docs.oracle.com/javase/8/docs/technotes/guides/management/agent.html)
-> to configure the server for remote management (system properties must be set in `artemis.profile`).
-
-By default, Apache ActiveMQ Artemis server uses the JMX domain "org.apache.activemq.artemis".
-To manage several Apache ActiveMQ Artemis servers from the *same* MBeanServer, the JMX
-domain can be configured for each individual Apache ActiveMQ Artemis server by setting
-`jmx-domain` in `broker.xml`:
+> Remote connections using the default JVM Agent not enabled by default as
+> Artemis exposes the mBean Server via its own configuration. This is so
+> Artemis can leverage the JAAS authentication layer via JMX. If you want to
+> expose this then you will need to disable both the connector and the
+> authorisation by removing them from the `management.xml` configuration.
+> Please refer to [Java Management
+> guide](https://docs.oracle.com/javase/8/docs/technotes/guides/management/agent.html)
+> to configure the server for remote management (system properties must be set
+> in `artemis.profile`).
+
+By default, Apache ActiveMQ Artemis server uses the JMX domain
+"org.apache.activemq.artemis". To manage several Apache ActiveMQ Artemis
+servers from the *same* MBeanServer, the JMX domain can be configured for each
+individual Apache ActiveMQ Artemis server by setting `jmx-domain` in
+`broker.xml`:
```xml
<!-- use a specific JMX domain for ActiveMQ Artemis MBeans -->
@@ -463,81 +496,87 @@ domain can be configured for each individual Apache ActiveMQ Artemis server by s
### Example
-See the [Examples](examples.md) chapter for an example which shows how to use a remote connection to JMX
-and MBean proxies to manage Apache ActiveMQ Artemis.
+See the [JMX Management Example](examples.md#jmx-management) which shows how to
+use a remote connection to JMX and MBean proxies to manage Apache ActiveMQ
+Artemis.
### Exposing JMX using Jolokia
The default Broker configuration ships with the [Jolokia](https://jolokia.org)
-HTTP agent deployed as a Web Application. Jolokia is a remote
-JMX-over-HTTP bridge that exposes MBeans. For a full guide as
-to how to use it refer to [Jolokia Documentation](https://jolokia.org/documentation.html),
-however a simple example to query the broker's version would
-be to use a browser and go to the URL [http://username:password@localhost:8161/console/jolokia/read/org.apache.activemq.artemis:broker="0.0.0.0"/Version]().
+HTTP agent deployed as a web application. Jolokia is a remote JMX-over-HTTP
+bridge that exposes MBeans. For a full guide as to how to use it refer to
+[Jolokia Documentation](https://jolokia.org/documentation.html), however a
+simple example to query the broker's version would be to use a browser and go
+to the URL
+[http://username:password@localhost:8161/console/jolokia/read/org.apache.activemq.artemis:broker="0.0.0.0"/Version]().
This would give you back something like the following:
- {"request":{"mbean":"org.apache.activemq.artemis:broker=\"0.0.0.0\"","attribute":"Version","type":"read"},"value":"2.0.0-SNAPSHOT","timestamp":1487017918,"status":200}
+```
+{"request":{"mbean":"org.apache.activemq.artemis:broker=\"0.0.0.0\"","attribute":"Version","type":"read"},"value":"2.0.0-SNAPSHOT","timestamp":1487017918,"status":200}
+```
### JMX and the Console
-The console that ships with Artemis uses Jolokia under the covers which in turn uses JMX. This will use the authentication
-configuration in the `management.xml` file as described in the previous section. This means that when mBeans are accessed
-via the console the credentials used to log into the console and the roles associated with them. By default access to the
-console is only allow via users with the amq role. This is configured in the `artemis.profile` via the system property `-Dhawtio.role=amq`.
-You can configure multiple roles by changing this to `-Dhawtio.roles=amq,view,update`.
+The console that ships with Artemis uses Jolokia under the covers which in turn
+uses JMX. This will use the authentication configuration in the
+`management.xml` file as described in the previous section. This means that
+when mBeans are accessed via the console the credentials used to log into the
+console and the roles associated with them. By default access to the console is
+only allow via users with the amq role. This is configured in the
+`artemis.profile` via the system property `-Dhawtio.role=amq`. You can
+configure multiple roles by changing this to `-Dhawtio.roles=amq,view,update`.
-If a user doesn't have the correct role to invoke a specific operation then this will display an authorisation exception
-in the console.
+If a user doesn't have the correct role to invoke a specific operation then
+this will display an authorisation exception in the console.
## Using Management Message API
-The management message API in ActiveMQ Artemis is accessed by sending Core Client messages
-to a special address, the *management address*.
+The management message API in ActiveMQ Artemis is accessed by sending Core
+Client messages to a special address, the *management address*.
*Management messages* are regular Core Client messages with well-known
-properties that the server needs to understand to interact with the
-management API:
+properties that the server needs to understand to interact with the management
+API:
-- The name of the managed resource
+- The name of the managed resource
-- The name of the management operation
+- The name of the management operation
-- The parameters of the management operation
+- The parameters of the management operation
-When such a management message is sent to the management address,
-Apache ActiveMQ Artemis server will handle it, extract the information, invoke the
+When such a management message is sent to the management address, Apache
+ActiveMQ Artemis server will handle it, extract the information, invoke the
operation on the managed resources and send a *management reply* to the
management message's reply-to address (specified by
`ClientMessageImpl.REPLYTO_HEADER_NAME`).
-A `ClientConsumer` can be used to consume the management reply and
-retrieve the result of the operation (if any) stored in the reply's
-body. For portability, results are returned as a [JSON](https://json.org)
-String rather than Java Serialization (the
+A `ClientConsumer` can be used to consume the management reply and retrieve the
+result of the operation (if any) stored in the reply's body. For portability,
+results are returned as a [JSON](https://json.org) String rather than Java
+Serialization (the
`org.apache.activemq.artemis.api.core.management.ManagementHelper` can be used
to convert the JSON string to Java objects).
-These steps can be simplified to make it easier to invoke management
-operations using Core messages:
+These steps can be simplified to make it easier to invoke management operations
+using Core messages:
-1. Create a `ClientRequestor` to send messages to the management
- address and receive replies
+1. Create a `ClientRequestor` to send messages to the management address and
+ receive replies
-2. Create a `ClientMessage`
+2. Create a `ClientMessage`
-3. Use the helper class
- `org.apache.activemq.artemis.api.core.management.ManagementHelper` to fill
- the message with the management properties
+3. Use the helper class
+ `org.apache.activemq.artemis.api.core.management.ManagementHelper` to fill
+ the message with the management properties
-4. Send the message using the `ClientRequestor`
+4. Send the message using the `ClientRequestor`
-5. Use the helper class
- `org.apache.activemq.artemis.api.core.management.ManagementHelper` to
- retrieve the operation result from the management reply
+5. Use the helper class
+ `org.apache.activemq.artemis.api.core.management.ManagementHelper` to
+ retrieve the operation result from the management reply.
-For example, to find out the number of messages in the queue
-`exampleQueue`:
+For example, to find out the number of messages in the queue `exampleQueue`:
```java
ClientSession session = ...
@@ -550,35 +589,38 @@ int count = (Integer) ManagementHelper.getResult(reply);
System.out.println("There are " + count + " messages in exampleQueue");
```
-Management operation name and parameters must conform to the Java
-interfaces defined in the `management` packages.
+Management operation name and parameters must conform to the Java interfaces
+defined in the `management` packages.
Names of the resources are built using the helper class
`org.apache.activemq.artemis.api.core.management.ResourceNames` and are
straightforward (e.g. `queue.exampleQueue` for `QueueControl` of the Queue
`exampleQueue`, or `broker` for the `ActiveMQServerControl`).
-> *NOTE*
+> **Note:**
>
-> The `ManagementHelper` class can be used only with Core JMS messages.
-> When called with a message from a different JMS library, an exception will be thrown.
+> The `ManagementHelper` class can be used only with Core JMS messages. When
+> called with a message from a different JMS library, an exception will be
+> thrown.
### Configuring Management
The management address to send management messages is configured in
`broker.xml`:
- <management-address>activemq.management</management-address>
+```xml
+<management-address>activemq.management</management-address>
+```
By default, the address is `activemq.management`.
-The management address requires a *special* user permission `manage` to
-be able to receive and handle management messages. This is also
-configured in broker.xml:
+The management address requires a *special* user permission `manage` to be able
+to receive and handle management messages. This is also configured in
+broker.xml:
```xml
<!-- users with the admin role will be allowed to manage -->
-<!-- Apache ActiveMQ Artemis using management messages -->
+<!-- Apache ActiveMQ Artemis using management messages -->
<security-setting match="activemq.management">
<permission type="manage" roles="admin" />
</security-setting>
@@ -586,49 +628,50 @@ configured in broker.xml:
### Example
-See the [Examples](examples.md) chapter for an example which shows
-how to use JMS messages to manage the Apache ActiveMQ Artemis server.
+See the [Management Example](examples.md#management) which shows how to use JMS
+messages to manage the Apache ActiveMQ Artemis server.
## Management Notifications
-Apache ActiveMQ Artemis emits *notifications* to inform listeners of potentially
-interesting events (creation of new resources, security violation,
+Apache ActiveMQ Artemis emits *notifications* to inform listeners of
+potentially interesting events (creation of new resources, security violation,
etc.).
These notifications can be received by two different ways:
-- JMX notifications
+- JMX notifications
-- Notification messages
+- Notification messages
### JMX Notifications
-If JMX is enabled (see Configuring JMX section), JMX notifications can be received by
-subscribing to `org.apache.activemq.artemis:type=Broker,brokerName=<broker name>,module=Core,serviceType=Server` for
-notifications on resources.
+If JMX is enabled (see Configuring JMX section), JMX notifications can be
+received by subscribing to
+`org.apache.activemq.artemis:type=Broker,brokerName=<broker
+name>,module=Core,serviceType=Server` for notifications on resources.
### Notification Messages
-Apache ActiveMQ Artemis defines a special *management notification address*.
-Queues can be bound to this address so that clients will receive
-management notifications as messages.
+Apache ActiveMQ Artemis defines a special *management notification address*.
+Queues can be bound to this address so that clients will receive management
+notifications as messages.
-A client which wants to receive management notifications must
-create a queue bound to the management notification address. It can
-then receive the notifications from its queue.
+A client which wants to receive management notifications must create a queue
+bound to the management notification address. It can then receive the
+notifications from its queue.
-Notifications messages are regular messages with additional
-properties corresponding to the notification (its type, when it
-occurred, the resources which were concerned, etc.).
+Notifications messages are regular messages with additional properties
+corresponding to the notification (its type, when it occurred, the resources
+which were concerned, etc.).
-Since notifications are regular messages, it is possible to use
-message selectors to filter out notifications and receives only a subset
-of all the notifications emitted by the server.
+Since notifications are regular messages, it is possible to use message
+selectors to filter out notifications and receives only a subset of all the
+notifications emitted by the server.
#### Configuring The Management Notification Address
-The management notification address to receive management notifications
-is configured in `broker.xml`:
+The management notification address to receive management notifications is
+configured in `broker.xml`:
```xml
<management-notification-address>activemq.notifications</management-notification-address>
@@ -645,195 +688,186 @@ Topic notificationsTopic = ActiveMQJMSClient.createTopic("activemq.notifications
Session session = ...
MessageConsumer notificationConsumer = session.createConsumer(notificationsTopic);
-notificationConsumer.setMessageListener(new MessageListener()
-{
- public void onMessage(Message notif)
- {
- System.out.println("------------------------");
- System.out.println("Received notification:");
- try
- {
- Enumeration propertyNames = notif.getPropertyNames();
- while (propertyNames.hasMoreElements())
- {
- String propertyName = (String)propertyNames.nextElement();
- System.out.format(" %s: %s\n", propertyName, notif.getObjectProperty(propertyName));
- }
- }
- catch (JMSException e)
- {
- }
- System.out.println("------------------------");
+notificationConsumer.setMessageListener(new MessageListener() {
+ public void onMessage(Message notif) {
+ System.out.println("------------------------");
+ System.out.println("Received notification:");
+ try {
+ Enumeration propertyNames = notif.getPropertyNames();
+ while (propertyNames.hasMoreElements()) {
+ String propertyName = (String)propertyNames.nextElement();
+ System.out.format(" %s: %s\n", propertyName, notif.getObjectProperty(propertyName));
+ }
+ } catch (JMSException e) {
+ }
+ System.out.println("------------------------");
}
});
```
### Example
-See the [Examples](examples.md) chapter for an example which shows how to use a JMS `MessageListener` to receive management notifications from ActiveMQ Artemis server.
+See the [Management Notification Example](examples.md#management-notification)
+which shows how to use a JMS `MessageListener` to receive management
+notifications from ActiveMQ Artemis server.
### Notification Types and Headers
-Below is a list of all the different kinds of notifications as well as
-which headers are on the messages. Every notification has a
-`_AMQ_NotifType` (value noted in parentheses) and `_AMQ_NotifTimestamp`
-header. The timestamp is the un-formatted result of a call to
-`java.lang.System.currentTimeMillis()`.
+Below is a list of all the different kinds of notifications as well as which
+headers are on the messages. Every notification has a `_AMQ_NotifType` (value
+noted in parentheses) and `_AMQ_NotifTimestamp` header. The timestamp is the
+un-formatted result of a call to `java.lang.System.currentTimeMillis()`.
-- `BINDING_ADDED` (0)
+- `BINDING_ADDED` (0)
- `_AMQ_Binding_Type`, `_AMQ_Address`, `_AMQ_ClusterName`,
- `_AMQ_RoutingName`, `_AMQ_Binding_ID`, `_AMQ_Distance`,
- `_AMQ_FilterString`
+ `_AMQ_Binding_Type`, `_AMQ_Address`, `_AMQ_ClusterName`,
+ `_AMQ_RoutingName`, `_AMQ_Binding_ID`, `_AMQ_Distance`,
+ `_AMQ_FilterString`
-- `BINDING_REMOVED` (1)
+- `BINDING_REMOVED` (1)
- `_AMQ_Address`, `_AMQ_ClusterName`, `_AMQ_RoutingName`,
- `_AMQ_Binding_ID`, `_AMQ_Distance`, `_AMQ_FilterString`
+ `_AMQ_Address`, `_AMQ_ClusterName`, `_AMQ_RoutingName`,
+ `_AMQ_Binding_ID`, `_AMQ_Distance`, `_AMQ_FilterString`
-- `CONSUMER_CREATED` (2)
+- `CONSUMER_CREATED` (2)
- `_AMQ_Address`, `_AMQ_ClusterName`, `_AMQ_RoutingName`, `_AMQ_Distance`,
- `_AMQ_ConsumerCount`, `_AMQ_User`, `_AMQ_RemoteAddress`,
- `_AMQ_SessionName`, `_AMQ_FilterString`
+ `_AMQ_Address`, `_AMQ_ClusterName`, `_AMQ_RoutingName`, `_AMQ_Distance`,
+ `_AMQ_ConsumerCount`, `_AMQ_User`, `_AMQ_RemoteAddress`,
+ `_AMQ_SessionName`, `_AMQ_FilterString`
-- `CONSUMER_CLOSED` (3)
+- `CONSUMER_CLOSED` (3)
- `_AMQ_Address`, `_AMQ_ClusterName`, `_AMQ_RoutingName`, `_AMQ_Distance`,
- `_AMQ_ConsumerCount`, `_AMQ_User`, `_AMQ_RemoteAddress`,
- `_AMQ_SessionName`, `_AMQ_FilterString`
+ `_AMQ_Address`, `_AMQ_ClusterName`, `_AMQ_RoutingName`, `_AMQ_Distance`,
+ `_AMQ_ConsumerCount`, `_AMQ_User`, `_AMQ_RemoteAddress`,
+ `_AMQ_SessionName`, `_AMQ_FilterString`
-- `SECURITY_AUTHENTICATION_VIOLATION` (6)
+- `SECURITY_AUTHENTICATION_VIOLATION` (6)
- `_AMQ_User`
+ `_AMQ_User`
-- `SECURITY_PERMISSION_VIOLATION` (7)
+- `SECURITY_PERMISSION_VIOLATION` (7)
- `_AMQ_Address`, `_AMQ_CheckType`, `_AMQ_User`
+ `_AMQ_Address`, `_AMQ_CheckType`, `_AMQ_User`
-- `DISCOVERY_GROUP_STARTED` (8)
+- `DISCOVERY_GROUP_STARTED` (8)
- `name`
+ `name`
-- `DISCOVERY_GROUP_STOPPED` (9)
+- `DISCOVERY_GROUP_STOPPED` (9)
- `name`
+ `name`
-- `BROADCAST_GROUP_STARTED` (10)
+- `BROADCAST_GROUP_STARTED` (10)
- `name`
+ `name`
-- `BROADCAST_GROUP_STOPPED` (11)
+- `BROADCAST_GROUP_STOPPED` (11)
- `name`
+ `name`
-- `BRIDGE_STARTED` (12)
+- `BRIDGE_STARTED` (12)
- `name`
+ `name`
-- `BRIDGE_STOPPED` (13)
+- `BRIDGE_STOPPED` (13)
- `name`
+ `name`
-- `CLUSTER_CONNECTION_STARTED` (14)
+- `CLUSTER_CONNECTION_STARTED` (14)
- `name`
+ `name`
-- `CLUSTER_CONNECTION_STOPPED` (15)
+- `CLUSTER_CONNECTION_STOPPED` (15)
- `name`
+ `name`
-- `ACCEPTOR_STARTED` (16)
+- `ACCEPTOR_STARTED` (16)
- `factory`, `id`
+ `factory`, `id`
-- `ACCEPTOR_STOPPED` (17)
+- `ACCEPTOR_STOPPED` (17)
- `factory`, `id`
+ `factory`, `id`
-- `PROPOSAL` (18)
+- `PROPOSAL` (18)
- `_JBM_ProposalGroupId`, `_JBM_ProposalValue`, `_AMQ_Binding_Type`,
- `_AMQ_Address`, `_AMQ_Distance`
+ `_JBM_ProposalGroupId`, `_JBM_ProposalValue`, `_AMQ_Binding_Type`,
+ `_AMQ_Address`, `_AMQ_Distance`
-- `PROPOSAL_RESPONSE` (19)
+- `PROPOSAL_RESPONSE` (19)
- `_JBM_ProposalGroupId`, `_JBM_ProposalValue`,
- `_JBM_ProposalAltValue`, `_AMQ_Binding_Type`, `_AMQ_Address`,
- `_AMQ_Distance`
+ `_JBM_ProposalGroupId`, `_JBM_ProposalValue`,
+ `_JBM_ProposalAltValue`, `_AMQ_Binding_Type`, `_AMQ_Address`,
+ `_AMQ_Distance`
-- `CONSUMER_SLOW` (21)
+- `CONSUMER_SLOW` (21)
- `_AMQ_Address`, `_AMQ_ConsumerCount`, `_AMQ_RemoteAddress`,
- `_AMQ_ConnectionName`, `_AMQ_ConsumerName`, `_AMQ_SessionName`
+ `_AMQ_Address`, `_AMQ_ConsumerCount`, `_AMQ_RemoteAddress`,
+ `_AMQ_ConnectionName`, `_AMQ_ConsumerName`, `_AMQ_SessionName`
## Message Counters
-Message counters can be used to obtain information on queues *over time*
-as Apache ActiveMQ Artemis keeps a history on queue metrics.
+Message counters can be used to obtain information on queues *over time* as
+Apache ActiveMQ Artemis keeps a history on queue metrics.
-They can be used to show *trends* on queues. For example, using the
-management API, it would be possible to query the number of messages in
-a queue at regular interval. However, this would not be enough to know
-if the queue is used: the number of messages can remain constant because
-nobody is sending or receiving messages from the queue or because there
-are as many messages sent to the queue than messages consumed from it.
-The number of messages in the queue remains the same in both cases but
-its use is widely different.
+They can be used to show *trends* on queues. For example, using the management
+API, it would be possible to query the number of messages in a queue at regular
+interval. However, this would not be enough to know if the queue is used: the
+number of messages can remain constant because nobody is sending or receiving
+messages from the queue or because there are as many messages sent to the queue
+than messages consumed from it. The number of messages in the queue remains
+the same in both cases but its use is widely different.
Message counters give additional information about the queues:
-- `count`
+- `count`
- The *total* number of messages added to the queue since the server
- was started
+ The *total* number of messages added to the queue since the server was
+ started
-- `countDelta`
+- `countDelta`
- the number of messages added to the queue *since the last message
- counter update*
+ the number of messages added to the queue *since the last message counter
+ update*
-- `messageCount`
+- `messageCount`
- The *current* number of messages in the queue
+ The *current* number of messages in the queue
-- `messageCountDelta`
+- `messageCountDelta`
- The *overall* number of messages added/removed from the queue *since
- the last message counter update*. For example, if
- `messageCountDelta` is equal to `-10` this means that overall 10
- messages have been removed from the queue (e.g. 2 messages were
- added and 12 were removed)
+ The *overall* number of messages added/removed from the queue *since the last
+ message counter update*. For example, if `messageCountDelta` is equal to `-10`
+ this means that overall 10 messages have been removed from the queue (e.g. 2
+ messages were added and 12 were removed)
-- `lastAddTimestamp`
+- `lastAddTimestamp`
- The timestamp of the last time a message was added to the queue
+ The timestamp of the last time a message was added to the queue
-- `udpateTimestamp`
+- `udpateTimestamp`
- The timestamp of the last message counter update
+ The timestamp of the last message counter update
-These attributes can be used to determine other meaningful data as well.
-For example, to know specifically how many messages were *consumed* from
-the queue since the last update simply subtract the `messageCountDelta`
-from `countDelta`.
+ These attributes can be used to determine other meaningful data as well. For
+ example, to know specifically how many messages were *consumed* from the queue
+ since the last update simply subtract the `messageCountDelta` from
+ `countDelta`.
### Configuring Message Counters
-By default, message counters are disabled as it might have a small
-negative effect on memory.
+By default, message counters are disabled as it might have a small negative
+effect on memory.
-To enable message counters, you can set it to `true` in
-`broker.xml`:
+To enable message counters, you can set it to `true` in `broker.xml`:
```xml
<message-counter-enabled>true</message-counter-enabled>
```
-Message counters keep a history of the queue metrics (10 days by
-default) and sample all the queues at regular interval (10 seconds by
-default). If message counters are enabled, these values should be
-configured to suit your messaging use case in
-`broker.xml`:
+Message counters keep a history of the queue metrics (10 days by default) and
+sample all the queues at regular interval (10 seconds by default). If message
+counters are enabled, these values should be configured to suit your messaging
+use case in `broker.xml`:
```xml
<!-- keep history for a week -->
@@ -842,8 +876,8 @@ configured to suit your messaging use case in
<message-counter-sample-period>60000</message-counter-sample-period>
```
-Message counters can be retrieved using the Management API. For example,
-to retrieve message counters on a queue using JMX:
+Message counters can be retrieved using the Management API. For example, to
+retrieve message counters on a queue using JMX:
```java
// retrieve a connection to Apache ActiveMQ Artemis's MBeanServer
@@ -863,4 +897,5 @@ messageCounter.getMessageCountDelta());
### Example
-See the [Examples](examples.md) chapter for an example which shows how to use message counters to retrieve information on a queue.
+See the [Message Counter Example](examples.md#message-counter) which shows how
+to use message counters to retrieve information on a queue.
http://git-wip-us.apache.org/repos/asf/activemq-artemis/blob/2b5d8f3b/docs/user-manual/en/masking-passwords.md
----------------------------------------------------------------------
diff --git a/docs/user-manual/en/masking-passwords.md b/docs/user-manual/en/masking-passwords.md
index 4ec64ba..c7332c7 100644
--- a/docs/user-manual/en/masking-passwords.md
+++ b/docs/user-manual/en/masking-passwords.md
@@ -1,65 +1,67 @@
# Masking Passwords
-By default all passwords in Apache ActiveMQ Artemis server's configuration files are in
-plain text form. This usually poses no security issues as those files
-should be well protected from unauthorized accessing. However, in some
-circumstances a user doesn't want to expose its passwords to more eyes
-than necessary.
+By default all passwords in Apache ActiveMQ Artemis server's configuration
+files are in plain text form. This usually poses no security issues as those
+files should be well protected from unauthorized accessing. However, in some
+circumstances a user doesn't want to expose its passwords to more eyes than
+necessary.
Apache ActiveMQ Artemis can be configured to use 'masked' passwords in its
-configuration files. A masked password is an obscure string
-representation of a real password. To mask a password a user will use an
-'encoder'. The encoder takes in the real password and outputs the masked
-version. A user can then replace the real password in the configuration
-files with the new masked password. When Apache ActiveMQ Artemis loads a masked
-password, it uses a suitable 'decoder' to decode it into real password.
+configuration files. A masked password is an obscure string representation of a
+real password. To mask a password a user will use an 'encoder'. The encoder
+takes in the real password and outputs the masked version. A user can then
+replace the real password in the configuration files with the new masked
+password. When Apache ActiveMQ Artemis loads a masked password, it uses a
+suitable 'decoder' to decode it into real password.
-Apache ActiveMQ Artemis provides a default password encoder and decoder. Optionally
-users can use or implement their own encoder and decoder for masking the
-passwords.
+Apache ActiveMQ Artemis provides a default password encoder and decoder.
+Optionally users can use or implement their own encoder and decoder for masking
+the passwords.
-In general, a masked password can be identified using one of two ways. The first one
-is the ENC() syntax, i.e. any string value wrapped in ENC() is to be treated as
-a masked password. For example
+In general, a masked password can be identified using one of two ways. The
+first one is the `ENC()` syntax, i.e. any string value wrapped in `ENC()` is to
+be treated as a masked password. For example
`ENC(xyz)`
The above indicates that the password is masked and the masked value is `xyz`.
-The ENC() syntax is the preferred way to indicating a masked password and is
+The `ENC()` syntax is the **preferred way** of masking a password and is
universally supported in every password configuration in Artemis.
-The other way is to use a `mask-password` attribute to tell that a password
-in a configuration file should be treated as 'masked'. For example:
+The other way is to use a `mask-password` attribute to tell that a password in
+a configuration file should be treated as 'masked'. For example:
```xml
<mask-password>true</mask-password>
<cluster-password>xyz</cluster-password>
```
-This method is now deprecated and exists only to maintain backward-compatibility.
-Newer configurations may not support it.
+
+This method is now **deprecated** and exists only to maintain
+backward-compatibility. Newer configurations may not support it.
### Password Masking in Server Configuration File
#### General Masking Configuration
-Besides supporting the ENC() syntax, the server configuration file (i.e. broker.xml)
-has a property that defines the default masking behaviors over the entire file scope.
+Besides supporting the `ENC()` syntax, the server configuration file (i.e.
+broker.xml) has a property that defines the default masking behaviors over the
+entire file scope.
-`mask-password`: this boolean type property indicates if a password
-should be masked or not. Set it to "true" if you want your passwords
-masked. The default value is "false".
+`mask-password`: this boolean type property indicates if a password should be
+masked or not. Set it to "true" if you want your passwords masked. The default
+value is "false".
`password-codec`: this string type property identifies the name of the class
which will be used to decode the masked password within the broker. If not
-specified then the default `org.apache.activemq.artemis.utils.DefaultSensitiveStringCodec`
-will be used.
+specified then the default
+`org.apache.activemq.artemis.utils.DefaultSensitiveStringCodec` will be used.
#### Specific Masking Behaviors
##### cluster-password
-If it is specified in ENC() syntax it will be treated as masked, or
+If it is specified in `ENC()` syntax it will be treated as masked, or
If `mask-password` is `true` the `cluster-password` will be treated as masked.
@@ -73,76 +75,77 @@ will have different password masking needs.
When a `connector` or `acceptor` is initialised, Apache ActiveMQ Artemis will
add the aforementioned `mask-password` and `password-codec` values to the
-`connector` or `acceptor` parameters using the keys `activemq.usemaskedpassword`
-and `activemq.passwordcodec` respectively. The Netty and InVM implementations
-will use these as needed and any other implementations will have access to
-these to use if they so wish.
+`connector` or `acceptor` parameters using the keys
+`activemq.usemaskedpassword` and `activemq.passwordcodec` respectively. The
+Netty and InVM implementations will use these as needed and any other
+implementations will have access to these to use if they so wish.
-The preferred way, however, is to use the ENC() syntax.
+The preferred way, however, is to use the `ENC()` syntax.
##### Core Bridges
-Core Bridges are configured in the server configuration file and so the
-masking of its `password` properties follows the same rules as that of
-`cluster-password`. It supports ENC() syntax.
+Core Bridges are configured in the server configuration file and so the masking
+of its `password` properties follows the same rules as that of
+`cluster-password`. It supports `ENC()` syntax.
-For using `mask-password` property, the following table summarizes the
+For using `mask-password` property, the following table summarizes the
relations among the above-mentioned properties
- mask-password | cluster-password | acceptor/connector passwords | bridge password
- :------------- | :---------------- | :--------------------------- | :---------------
- absent | plain text | plain text | plain text
- false | plain text | plain text | plain text
- true | masked | masked | masked
+mask-password | cluster-password | acceptor/connector passwords | bridge password
+--- | --- | --- | ---
+absent|plain text|plain text|plain text
+false|plain text|plain text|plain text
+true|masked|masked|masked
-It is recommended that you use the `ENC()` syntax for new applications/deployments.
+It is recommended that you use the `ENC()` syntax for new
+applications/deployments.
#### Examples
-Note: In the following examples if related attributed or properties are
+**Note:** In the following examples if related attributed or properties are
absent, it means they are not specified in the configure file.
-example 1
+- Unmasked
-```xml
-<cluster-password>bbc</cluster-password>
-```
+ ```xml
+ <cluster-password>bbc</cluster-password>
+ ```
-This indicates the cluster password is a plain text value ("bbc").
+ This indicates the cluster password is a plain text value `bbc`.
-example 2
+- Masked 1
-```xml
-<cluster-password>ENC(xyz)</cluster-password>
-```
+ ```xml
+ <cluster-password>ENC(xyz)</cluster-password>
+ ```
-This indicates the cluster password is a masked value ("xyz").
+ This indicates the cluster password is a masked value `xyz`.
-example 3
+- Masked 2
-```xml
-<mask-password>true</mask-password>
-<cluster-password>80cf731af62c290</cluster-password>
-```
+ ```xml
+ <mask-password>true</mask-password>
+ <cluster-password>80cf731af62c290</cluster-password>
+ ```
-This indicates the cluster password is a masked value and Apache ActiveMQ Artemis will
-use its built-in decoder to decode it. All other passwords in the
-configuration file, Connectors, Acceptors and Bridges, will also use
-masked passwords.
+ This indicates the cluster password is a masked value and Apache ActiveMQ
+ Artemis will use its built-in decoder to decode it. All other passwords in the
+ configuration file, Connectors, Acceptors and Bridges, will also use masked
+ passwords.
#### Passwords in bootstrap.xml
The broker embeds a web-server for hosting some web applications such as a
-management console. It is configured in bootstrap.xml as a web
-component. The web server can be secured using https protocol, and it can be
-configured with a keystore password and/or truststore password which by
-default are specified in plain text forms.
+management console. It is configured in bootstrap.xml as a web component. The
+web server can be secured using https protocol, and it can be configured with a
+keystore password and/or truststore password which by default are specified in
+plain text forms.
-To mask these passwords you need to use ENC() syntax. The `mask-password` is
-not supported here.
+To mask these passwords you need to use `ENC()` syntax. The `mask-password`
+boolean is not supported here.
-You can also set the `passwordCodec` attribute if you want to use a password codec
-other than the default one. For example
+You can also set the `passwordCodec` attribute if you want to use a password
+codec other than the default one. For example
```xml
<web bind="https://localhost:8443" path="web"
@@ -154,24 +157,23 @@ other than the default one. For example
### Passwords for the JCA Resource Adapter
-Both ra.xml and MDB activation configuration have a `password` property
-that can be masked preferably using ENC() syntax.
+Both ra.xml and MDB activation configuration have a `password` property that
+can be masked preferably using `ENC()` syntax.
-Alternatively it can use a optional attribute in ra.xml to indicate that a password
-is masked:
+Alternatively it can use a optional attribute in ra.xml to indicate that a
+password is masked:
-`UseMaskedPassword` -- If setting to "true" the passwords are masked.
-Default is false.
+`UseMaskedPassword` -- If setting to "true" the passwords are masked. Default
+is false.
There is another property in ra.xml that can specify a codec:
-`PasswordCodec` -- Class name and its parameters for the Decoder used to
-decode the masked password. Ignored if UseMaskedPassword is false. The
-format of this property is a full qualified class name optionally
-followed by key/value pairs. It is the same format as that for JMS
-Bridges. Example:
+`PasswordCodec` -- Class name and its parameters for the Decoder used to decode
+the masked password. Ignored if UseMaskedPassword is false. The format of this
+property is a full qualified class name optionally followed by key/value pairs.
+It is the same format as that for JMS Bridges. Example:
-Example 1 Using the ENC() syntax:
+Example 1 Using the `ENC()` syntax:
```xml
<config-property>
@@ -206,16 +208,17 @@ Example 2 Using the "UseMaskedPassword" property:
</config-property>
```
-With this configuration, both passwords in ra.xml and all of its MDBs
-will have to be in masked form.
+With this configuration, both passwords in ra.xml and all of its MDBs will have
+to be in masked form.
### Passwords in artemis-users.properties
Apache ActiveMQ Artemis's built-in security manager uses plain properties files
-where the user passwords are specified in a hashed form by default. Note, the passwords
-are technically *hashed* rather than masked in this context. The default `PropertiesLoginModule`
-will not decode the passwords in `artemis-users.properties` but will instead hash the input
-and compare the two hashed values for password verification.
+where the user passwords are specified in a hashed form by default. Note, the
+passwords are technically *hashed* rather than masked in this context. The
+default `PropertiesLoginModule` will not decode the passwords in
+`artemis-users.properties` but will instead hash the input and compare the two
+hashed values for password verification.
Please use Artemis CLI command to add a password. For example:
@@ -223,26 +226,27 @@ Please use Artemis CLI command to add a password. For example:
./artemis user add --username guest --password guest --role admin
```
-This will use the default `org.apache.activemq.artemis.utils.DefaultSensitiveStringCodec`
-to perform a "one-way" hash of the password and alter both the `artemis-users.properties`
+This will use the default
+`org.apache.activemq.artemis.utils.DefaultSensitiveStringCodec` to perform a
+"one-way" hash of the password and alter both the `artemis-users.properties`
and `artemis-roles.properties` files with the specified values.
-Passwords in `artemis-users.properties` are automatically detected as hashed or not
-by looking for the syntax `ENC(<hash>)`. The `mask-password` parameter does not need
-to be `true` to use hashed passwords here.
+Passwords in `artemis-users.properties` are automatically detected as hashed or
+not by looking for the syntax `ENC(<hash>)`. The `mask-password` parameter does
+not need to be `true` to use hashed passwords here.
### Password in login.config
-Artemis supports LDAP login modules to be configured in JAAS configuration
-file (default name is `login.config`). When connecting to a LDAP server usually
-you need to supply a connection password in the config file. By default this
+Artemis supports LDAP login modules to be configured in JAAS configuration file
+(default name is `login.config`). When connecting to a LDAP server usually you
+need to supply a connection password in the config file. By default this
password is in plain text form.
-To mask it you need to configure the passwords in your login module
-using ENC() syntax. To specify a codec using the following property:
+To mask it you need to configure the passwords in your login module using
+`ENC()` syntax. To specify a codec using the following property:
-`passwordCodec` - the password codec class name. (the default codec
-will be used if it is absent)
+`passwordCodec` - the password codec class name. (the default codec will be
+used if it is absent)
For example:
@@ -270,24 +274,24 @@ LDAPLoginExternalPasswordCodec {
### Choosing a decoder for password masking
-As described in the previous sections, all password masking requires a
-decoder. A decoder uses an algorithm to convert a masked password into
-its original clear text form in order to be used in various security
-operations. The algorithm used for decoding must match that for
-encoding. Otherwise the decoding may not be successful.
+As described in the previous sections, all password masking requires a decoder.
+A decoder uses an algorithm to convert a masked password into its original
+clear text form in order to be used in various security operations. The
+algorithm used for decoding must match that for encoding. Otherwise the
+decoding may not be successful.
For user's convenience Apache ActiveMQ Artemis provides a default decoder.
However a user can implement their own if they wish.
#### The Default Decoder
-Whenever no decoder is specified in the configuration file, the default
-decoder is used. The class name for the default decoder is
-`org.apache.activemq.artemis.utils.DefaultSensitiveStringCodec`. It has hashing,
-encoding, and decoding capabilities. It uses `java.crypto.Cipher` utilities
-to hash or encode a plaintext password and also to decode a masked string using
-same algorithm and key. Using this decoder/encoder is pretty straightforward. To
-get a mask for a password, just run the `mask` command:
+Whenever no decoder is specified in the configuration file, the default decoder
+is used. The class name for the default decoder is
+`org.apache.activemq.artemis.utils.DefaultSensitiveStringCodec`. It has
+hashing, encoding, and decoding capabilities. It uses `java.crypto.Cipher`
+utilities to hash or encode a plaintext password and also to decode a masked
+string using same algorithm and key. Using this decoder/encoder is pretty
+straightforward. To get a mask for a password, just run the `mask` command:
```sh
./artemis mask <plaintextPassword>
@@ -304,18 +308,19 @@ plaintext password in broker.xml with it.
#### Using a custom decoder
-It is possible to use a custom decoder rather than the built-in one.
-Simply make sure the decoder is in Apache ActiveMQ Artemis's classpath. The custom decoder
-can also be service loaded rather than class loaded, if the decoder's service provider is installed in the classpath.
-Then configure the server to use it as follows:
+It is possible to use a custom decoder rather than the built-in one. Simply
+make sure the decoder is in Apache ActiveMQ Artemis's classpath. The custom
+decoder can also be service loaded rather than class loaded, if the decoder's
+service provider is installed in the classpath. Then configure the server to
+use it as follows:
```xml
<password-codec>com.foo.SomeDecoder;key1=value1;key2=value2</password-codec>
```
-If your decoder needs params passed to it you can do this via key/value
-pairs when configuring. For instance if your decoder needs say a
-"key-location" parameter, you can define like so:
+If your decoder needs params passed to it you can do this via key/value pairs
+when configuring. For instance if your decoder needs say a "key-location"
+parameter, you can define like so:
```xml
<password-codec>com.foo.NewDecoder;key-location=/some/url/to/keyfile</password-codec>
@@ -328,15 +333,14 @@ Then configure your cluster-password like this:
```
When Apache ActiveMQ Artemis reads the cluster-password it will initialize the
-NewDecoder and use it to decode "mask\_password". It also process all
-passwords using the new defined decoder.
+NewDecoder and use it to decode "mask\_password". It also process all passwords
+using the new defined decoder.
#### Implementing Custom Codecs
-To use a different decoder than the built-in one, you either pick one
-from existing libraries or you implement it yourself. All decoders must
-implement the `org.apache.activemq.artemis.utils.SensitiveDataCodec<T>`
-interface:
+To use a different decoder than the built-in one, you either pick one from
+existing libraries or you implement it yourself. All decoders must implement
+the `org.apache.activemq.artemis.utils.SensitiveDataCodec<T>` interface:
```java
public interface SensitiveDataCodec<T>
@@ -347,8 +351,8 @@ public interface SensitiveDataCodec<T>
}
```
-This is a generic type interface but normally for a password you just
-need String type. So a new decoder would be defined like
+This is a generic type interface but normally for a password you just need
+String type. So a new decoder would be defined like
```java
public class MyNewDecoder implements SensitiveDataCodec<String>
@@ -367,4 +371,5 @@ public class MyNewDecoder implements SensitiveDataCodec<String>
```
Last but not least, once you get your own decoder please [add it to the
-classpath](using-server.md#adding-runtime-dependencies) otherwise the broker will fail to load it!
\ No newline at end of file
+classpath](using-server.md#adding-runtime-dependencies) otherwise the broker
+will fail to load it!
http://git-wip-us.apache.org/repos/asf/activemq-artemis/blob/2b5d8f3b/docs/user-manual/en/maven-plugin.md
----------------------------------------------------------------------
diff --git a/docs/user-manual/en/maven-plugin.md b/docs/user-manual/en/maven-plugin.md
index 19bda2f..143db9d 100644
--- a/docs/user-manual/en/maven-plugin.md
+++ b/docs/user-manual/en/maven-plugin.md
@@ -13,17 +13,17 @@ You could for example use these maven plugins on your testsuite or deployment au
There are three goals that you can use
-- create
+- `create`
-This will create a server accordingly to your arguments. You can do some extra tricks here such as installing extra libraries for external modules.
+ This will create a server accordingly to your arguments. You can do some extra tricks here such as installing extra libraries for external modules.
-- cli
+- `cli`
-This will perform any CLI operation. This is basically a maven expression of the CLI classes
+ This will perform any CLI operation. This is basically a maven expression of the CLI classes
-- runClient
+- `runClient`
-This is a simple wrapper around classes implementing a static main call. Notice that this won't spawn a new VM or new Thread.
+ This is a simple wrapper around classes implementing a static main call. Notice that this won't spawn a new VM or new Thread.
## Declaration
@@ -31,11 +31,14 @@ This is a simple wrapper around classes implementing a static main call. Notice
On your pom, use the plugins section:
```xml
- <build>
- <plugins>
- <plugin>
- <groupId>org.apache.activemq</groupId>
- <artifactId>artemis-maven-plugin</artifactId>
+<build>
+ <plugins>
+ <plugin>
+ <groupId>org.apache.activemq</groupId>
+ <artifactId>artemis-maven-plugin</artifactId>
+ </plugin>
+ </plugins>
+</build>
```
## create goal
@@ -43,7 +46,7 @@ On your pom, use the plugins section:
I won't detail every operation of the create plugin here, but I will try to describe the main parameters:
Name | Description
-:--- | :---
+--- | ---
configuration | A place that will hold any file to replace on the configuration. For instance if you are providing your own broker.xml. Default is "${basedir}/target/classes/activemq/server0"
home | The location where you downloaded and installed artemis. Default is "${activemq.basedir}"
alternateHome | This is used case you have two possible locations for your home (e.g. one under compile and one under production
@@ -54,16 +57,15 @@ liblist[] | A list of libraries to be installed under ./lib. ex: "org.jgroups:jg
Example:
```xml
-<executions>
- <execution>
- <id>create</id>
- <goals>
- <goal>create</goal>
- </goals>
- <configuration>
- <ignore>${noServer}</ignore>
- </configuration>
- </execution>
+<execution>
+ <id>create</id>
+ <goals>
+ <goal>create</goal>
+ </goals>
+ <configuration>
+ <ignore>${noServer}</ignore>
+ </configuration>
+</execution>
```
@@ -72,7 +74,7 @@ Example:
Some properties for the CLI
Name | Description
-:--- | :---
+--- | ---
configuration | A place that will hold any file to replace on the configuration. For instance if you are providing your own broker.xml. Default is "${basedir}/target/classes/activemq/server0"
home | The location where you downloaded and installed artemis. Default is "${activemq.basedir}"
alternateHome | This is used case you have two possible locations for your home (e.g. one under compile and one under production
@@ -105,7 +107,7 @@ Example:
This is a simple solution for running classes implementing the main method.
Name | Description
-:--- | :---
+--- | ---
clientClass | A class implement a static void main(String arg[])
args | A string array of arguments passed to the method
http://git-wip-us.apache.org/repos/asf/activemq-artemis/blob/2b5d8f3b/docs/user-manual/en/message-expiry.md
----------------------------------------------------------------------
diff --git a/docs/user-manual/en/message-expiry.md b/docs/user-manual/en/message-expiry.md
index 99cb73f..68463f5 100644
--- a/docs/user-manual/en/message-expiry.md
+++ b/docs/user-manual/en/message-expiry.md
@@ -2,19 +2,19 @@
Messages can be set with an optional *time to live* when sending them.
-Apache ActiveMQ Artemis will not deliver a message to a consumer after it's time to
-live has been exceeded. If the message hasn't been delivered by the time
-that time to live is reached the server can discard it.
+Apache ActiveMQ Artemis will not deliver a message to a consumer after it's
+time to live has been exceeded. If the message hasn't been delivered by the
+time that time to live is reached the server can discard it.
-Apache ActiveMQ Artemis's addresses can be assigned a expiry address so that, when
-messages are expired, they are removed from the queue and sent to the
-expiry address. Many different queues can be bound to an expiry address.
-These *expired* messages can later be consumed for further inspection.
+Apache ActiveMQ Artemis's addresses can be assigned a expiry address so that,
+when messages are expired, they are removed from the queue and sent to the
+expiry address. Many different queues can be bound to an expiry address. These
+*expired* messages can later be consumed for further inspection.
## Core API
-Using Apache ActiveMQ Artemis Core API, you can set an expiration time directly on the
-message:
+Using Apache ActiveMQ Artemis Core API, you can set an expiration time directly
+on the message:
```java
// message will expire in 5000ms from now
@@ -28,23 +28,23 @@ JMS MessageProducer allows to set a TimeToLive for the messages it sent:
producer.setTimeToLive(5000);
```
-Expired messages which are consumed from an expiry address have the
-following properties:
+Expired messages which are consumed from an expiry address have the following
+properties:
-- `_AMQ_ORIG_ADDRESS`
+- `_AMQ_ORIG_ADDRESS`
- a String property containing the *original address* of the expired
- message
+ a String property containing the *original address* of the expired
+ message
-- `_AMQ_ORIG_QUEUE`
+- `_AMQ_ORIG_QUEUE`
- a String property containing the *original queue* of the expired
- message
+ a String property containing the *original queue* of the expired
+ message
-- `_AMQ_ACTUAL_EXPIRY`
+- `_AMQ_ACTUAL_EXPIRY`
- a Long property containing the *actual expiration time* of the
- expired message
+ a Long property containing the *actual expiration time* of the
+ expired message
## Configuring Expiry Addresses
@@ -57,29 +57,29 @@ Expiry address are defined in the address-setting configuration:
</address-setting>
```
-If messages are expired and no expiry address is specified, messages are
-simply removed from the queue and dropped. Address wildcards can be used
-to configure expiry address for a set of addresses (see [Understanding the Wildcard Syntax](wildcard-syntax.md)).
+If messages are expired and no expiry address is specified, messages are simply
+removed from the queue and dropped. Address [wildcards](wildcard-syntax.md) can
+be used to configure expiry address for a set of addresses.
## Configuring The Expiry Reaper Thread
-A reaper thread will periodically inspect the queues to check if
-messages have expired.
+A reaper thread will periodically inspect the queues to check if messages have
+expired.
The reaper thread can be configured with the following properties in
`broker.xml`
-- `message-expiry-scan-period`
+- `message-expiry-scan-period`
- How often the queues will be scanned to detect expired messages (in
- milliseconds, default is 30000ms, set to `-1` to disable the reaper
- thread)
+ How often the queues will be scanned to detect expired messages (in
+ milliseconds, default is 30000ms, set to `-1` to disable the reaper thread)
-- `message-expiry-thread-priority`
+- `message-expiry-thread-priority`
- The reaper thread priority (it must be between 1 and 10, 10 being the
- highest priority, default is 3)
+ The reaper thread priority (it must be between 1 and 10, 10 being the highest
+ priority, default is 3)
## Example
-See the [examples.md](examples.md) chapter for an example which shows how message expiry is configured and used with JMS.
+See the [Message Expiration Example](examples.md#message-expiration) which
+shows how message expiry is configured and used with JMS.