Apache
/
activemq-artemis
mirror of https://github.com/apache/activemq-artemis.git
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

NO-JIRA Updates to management.md doc 

* add Jolokia to the initial list of ways to access management API
* remove mentions of core queues, etc. (pre-addressing change)
* activemq.notifications can be consumed with any client
* activemq.management can be accessed only with Core or Core JMS clients
* *.management.*Control are interfaces, not classes
* remove ObjectNames from the summary of management methods.
    IMO that made the short paragraphs hard to read.
    And one can intuitively find them in jconsole,
    or use the Builder class to construct them in code.
* move the note about empty filter to the queue management section
* add code snippet for creating ObjectName with ObjectNameBuilder
* mention web console and bin/artemis for interactive management
* fix few typos
This commit is contained in:
Jiri Danek 2017-07-31 12:26:28 +02:00 committed by Clebert Suconic
parent d0a9d017dd
commit 48f50fccbe
3 changed files with 99 additions and 115 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

2
docs/user-manual/en/intercepting-operations.md
View File

@ -14,7 +14,7 @@ All interceptors are protocol specific.
An interceptor for the core protocol must implement the interface `Interceptor`: An interceptor for the core protocol must implement the interface `Interceptor`:
``` java ``` java
package org.apache.artemis.activemq.api.core.interceptor; package org.apache.activemq.artemis.api.core.interceptor;
public interface Interceptor public interface Interceptor
{ {

210
docs/user-manual/en/management.md
View File

@ -1,32 +1,37 @@
# Management # Management
Apache ActiveMQ Artemis has an extensive management API that allows a user to modify a 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), server configuration, create new resources (e.g. addresses and queues),
inspect these resources (e.g. how many messages are currently held in a 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). All queue) and interact with it (e.g. to remove messages from a queue). Apache ActiveMQ Artemis
the operations allows a client to *manage* Apache ActiveMQ Artemis. It also allows also allows clients to subscribe to management notifications.
clients to subscribe to management notifications.
There are 3 ways to manage Apache ActiveMQ Artemis: 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 the core API -- management operations are sent to Apache ActiveMQ Artemis - Using Jolokia -- Jolokia exposes the JMX API of an application through a *REST interface*
server using *core messages*
- Using the JMS API -- management operations are sent to Apache ActiveMQ Artemis - Using the Core Client -- management operations are sent to Apache ActiveMQ Artemis
server using *JMS messages* server using *Core Client messages*
Although there are 3 different ways to manage Apache ActiveMQ Artemis each API supports - Using the Core JMS Client -- management operations are sent to Apache ActiveMQ Artemis
server using *Core 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 the same functionality. If it is possible to manage a resource using JMX
it is also possible to achieve the same result using Core. it is also possible to achieve the same result using Core messages.
This choice depends on your requirements, your application settings and Besides the programmatic management interfaces, a *Web Console* 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. your environment to decide which way suits you best.
> **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 sytanx. > 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 ## The Management API
@ -34,48 +39,35 @@ Regardless of the way you *invoke* management operations, the management
API is the same. API is the same.
For each *managed resource*, there exists a Java interface describing For each *managed resource*, there exists a Java interface describing
what can be invoked for this type of resource. what operations can be invoked for this type of resource.
Apache ActiveMQ Artemis exposes its managed resources in the `org.apache.activemq.artemis.api.core.management` package 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 a *management operations* depends whether JMX, core The way to invoke management operations depends on whether JMX, Core
messages, or JMS messages are used. messages, or Core JMS messages are used.
> **Note**
>
> A few management operations requires a `filter` parameter to chose
> which messages are involved by the operation. Passing `null` or an
> empty string means that the management operation will be performed on
> *all messages*.
### Apache ActiveMQ Artemis Management API ### Apache ActiveMQ Artemis Management API
Apache ActiveMQ Artemis defines a core management API to manage core resources. For For full details of the API please consult the Javadoc. In summary:
full details of the API please consult the javadoc. In summary:
#### Apache ActiveMQ Artemis Server Management #### Apache ActiveMQ Artemis Server Management
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 core queues can be retrieved using the A list of deployed queues can be retrieved using the
`getQueueNames()` method. `getQueueNames()` method.
Core queues can be created or destroyed using the management Queues can be created or destroyed using the management
operations `createQueue()` or `deployQueue()` or `destroyQueue()`)on operations `createQueue()` or `deployQueue()` or `destroyQueue()`
the `ActiveMQServerControl` (with the ObjectName
`org.apache.activemq.artemis:broker="<brokerName>"` or the resource name
`broker`)
`createQueue` will fail if the queue already exists while `createQueue` will fail if the queue already exists while
`deployQueue` will do nothing. `deployQueue` will do nothing.
- 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.
- Listing and closing remote connections - Listing and closing remote connections
Client's remote addresses can be retrieved using Client's remote addresses can be retrieved using
@ -121,17 +113,12 @@ full details of the API please consult the javadoc. In summary:
Core bridges (resp. diverts) can be created or destroyed using the Core bridges (resp. diverts) can be created or destroyed using the
management operations `createBridge()` and `destroyBridge()` (resp. management operations `createBridge()` and `destroyBridge()` (resp.
`createDivert()` and `destroyDivert()`) on the `createDivert()` and `destroyDivert()`).
`ActiveMQServerControl` (with the ObjectName
`org.apache.activemq.artemis:broker="<brokerName>"` or the resource name
`broker`).
- It is possible to stop the server and force failover to occur with - It is possible to stop the server and force failover to occur with
any currently attached clients. any currently attached clients.
to do this use the `forceFailover()` on the `ActiveMQServerControl` To do this use the `forceFailover()` operation.
(with the ObjectName `org.apache.activemq.artemis:broker="<brokerName>"`
or the resource name `broker`)
> **Note** > **Note**
> >
@ -141,9 +128,7 @@ full details of the API please consult the javadoc. In summary:
#### Address Management #### Address Management
Core addresses can be managed using the `AddressControl` class (with the Individual addresses can be managed using the `AddressControl` interface.
ObjectName `org.apache.activemq.artemis:broker="<brokerName>",component=addresses,address="<addressName>"` or the resource name
`address.<addressName>`).
- Modifying roles and permissions for an address - Modifying roles and permissions for an address
@ -153,16 +138,18 @@ ObjectName `org.apache.activemq.artemis:broker="<brokerName>",component=addresse
#### Queue Management #### Queue Management
The bulk of the core management API deals with core queues. The The bulk of the management API deals with queues. The
`QueueControl` class defines the Core queue management operations (with `QueueControl` interface defines the queue management operations.
the ObjectName
`org.apache.activemq.artemis:broker="<brokerName>",component=addresses,address="<addressName>",subcomponent=queues,routing-type="<routingType>",queue="<queueName>"`
or the resource name `queue.<queueName>`).
Most of the management operations on queues take either a single message 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 ID (e.g. to remove a single message) or a filter (e.g. to expire all
messages with a given property.) messages with a given property.)
> **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.
- 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()` Messages can be expired from a queue by using the `expireMessages()`
@ -197,7 +184,7 @@ messages with a given property.)
The number of messages in a queue is returned by the The number of messages in a queue is returned by the
`getMessageCount()` method. Alternatively, the `countMessages()` `getMessageCount()` method. Alternatively, the `countMessages()`
will return the number of messages in the queue which *match a given will return the number of messages in the queue which *match a given
filter* filter*.
- Changing message priority - Changing message priority
@ -224,7 +211,7 @@ messages with a given property.)
The `QueueControl` can pause and resume the underlying queue. When a The `QueueControl` can pause and resume the underlying queue. When a
queue is paused, it will receive messages but will not deliver them. queue is paused, it will receive messages but will not deliver them.
When it's resume, it'll begin delivering the queued messages, if When it's resumed, it'll begin delivering the queued messages, if
any. any.
#### Other Resources Management #### Other Resources Management
@ -238,45 +225,33 @@ transactions). These resources are:
- Acceptors - Acceptors
They can be started or stopped using the `start()` or. `stop()` They can be started or stopped using the `start()` or. `stop()`
method on the `AcceptorControl` class (with the ObjectName method on the `AcceptorControl` interface. The acceptors parameters
`org.apache.activemq.artemis:broker="<brokerName>",component=acceptor,name="<acceptorName>"`
or the resource name
`acceptor.<acceptorName>`). The acceptors parameters
can be retrieved using the `AcceptorControl` attributes (see [Understanding Acceptors](configuring-transports.md)) 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()` They can be started or stopped using the `start()` or `stop()`
method on the `DivertControl` class (with the ObjectName method on the `DivertControl` interface. Diverts
`org.apache.activemq.artemis:broker="<brokerName>",component=addresses,address="<addressName>",subcomponent=diverts,divert="<divertName>"`
or the resource name `divert.<divertName>`). Diverts
parameters can be retrieved using the `DivertControl` attributes parameters can be retrieved using the `DivertControl` attributes
(see [Diverting and Splitting Message Flows)](diverts.md)) (see [Diverting and Splitting Message Flows)](diverts.md))
- Bridges - Bridges
They can be started or stopped using the `start()` (resp. `stop()`) They can be started or stopped using the `start()` (resp. `stop()`)
method on the `BridgeControl` class (with the ObjectName method on the `BridgeControl` interface. Bridges parameters can be retrieved
`org.apache.activemq.artemis:broker="<brokerName>",component=bridges,name="<bridgeName>"`
or the resource name
`bridge.<the bridge name>`). Bridges parameters can be retrieved
using the `BridgeControl` attributes (see [Core bridges](core-bridges.md)) 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()` They can be started or stopped using the `start()` or `stop()`
method on the `BroadcastGroupControl` class (with the ObjectName method on the `BroadcastGroupControl` interface. Broadcast groups
`org.apache.activemq.artemis:broker="<brokerName>",component=broadcast-groups,name="<broadcastgroupName>"` or the resource name
`broadcastgroup.<the broadcast group name>`). Broadcast groups
parameters can be retrieved using the `BroadcastGroupControl` parameters can be retrieved using the `BroadcastGroupControl`
attributes (see [Clusters](clusters.md)) attributes (see [Clusters](clusters.md))
- Cluster connections - Cluster connections
They can be started or stopped using the `start()` or `stop()` They can be started or stopped using the `start()` or `stop()`
method on the `ClusterConnectionControl` class (with the ObjectName method on the `ClusterConnectionControl` interface. Cluster
`org.apache.activemq.artemis:broker="<brokerName>",component=cluster-connections,name="<clusterconnectionName>"` or the resource name
`clusterconnection.<the cluster connection name>`). Cluster
connections parameters can be retrieved using the connections parameters can be retrieved using the
`ClusterConnectionControl` attributes (see [Clusters](clusters.md)) `ClusterConnectionControl` attributes (see [Clusters](clusters.md))
@ -296,11 +271,19 @@ and the MBean is:
org.apache.activemq.artemis.api.core.management.QueueControl org.apache.activemq.artemis.api.core.management.QueueControl
The MBean's `ObjectName` are built using the helper class The MBean `ObjectName`'s are built using the helper class
`org.apache.activemq.artemis.api.core.management.ObjectNameBuilder`. You can `org.apache.activemq.artemis.api.core.management.ObjectNameBuilder`. You can
also use `jconsole` to find the `ObjectName` of the MBeans you want to also use `jconsole` to find the `ObjectName` of the MBean you want to
manage. manage.
Example usage of the `ObjectNameBuilder` to obtain `ActiveMQServerControl`'s name:
``` java
brokerName = "0.0.0.0"; // configured e.g. in broker.xml <broker-name> element
objectNameBuilder = ObjectNameBuilder.create(ArtemisResolver.DEFAULT_DOMAIN, brokerName, true);
serverObjectName = objectNameBuilder.getActiveMQServerObjectName()
```
Managing Apache ActiveMQ Artemis using JMX is identical to management of any Java 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 Applications using JMX. It can be done by reflection or by creating
proxies of the MBeans. proxies of the MBeans.
@ -335,22 +318,22 @@ domain can be configured for each individual Apache ActiveMQ Artemis server by s
#### MBeanServer configuration #### MBeanServer configuration
When Apache ActiveMQ Artemis is run in standalone, it uses the Java Virtual Machine's When Apache ActiveMQ Artemis is run in standalone, it uses the Java Virtual Machine's
`Platform MBeanServer` to register its MBeans. By default [Jolokia](http://www.jolokia.org/) `Platform MBeanServer` to register its MBeans. By default, [Jolokia](http://www.jolokia.org/)
is also deployed to allow access to the mbean server via rest. is also deployed to allow access to the MBean server via [REST](https://en.wikipedia.org/wiki/Representational_state_transfer).
### Example ### Example
See the [chapters](examples.md) chapter for an example which shows how to use a remote connection to JMX 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. and MBean proxies to manage Apache ActiveMQ Artemis.
### Exposing JMX using Jolokia ### Exposing JMX using Jolokia
The default Broker configuration ships with the [Jolokia](http://www.jolokia.org) The default Broker configuration ships with the [Jolokia](http://www.jolokia.org)
http agent deployed as a Web Application. Jolokia is a remote HTTP agent deployed as a Web Application. Jolokia is a remote
JMX over HTTP bridge that exposed mBeans, for a full guids as JMX-over-HTTP bridge that exposes MBeans. For a full guide as
to how to use refer to [Jolokia Documentation](http://www.jolokia.org/documentation.html), to how to use it refer to [Jolokia Documentation](http://www.jolokia.org/documentation.html),
however a simple example to query the broker's version would however a simple example to query the broker's version would
be to use a browser and go to the URL http://localhost:8161/jolokia/read/org.apache.activemq.artemis:broker="0.0.0.0"/Version. be to use a browser and go to the URL [http://localhost:8161/jolokia/read/org.apache.activemq.artemis:broker="0.0.0.0"/Version]().
This would give you back something like the following: This would give you back something like the following:
@ -358,7 +341,7 @@ This would give you back something like the following:
## Using Management Via Apache ActiveMQ Artemis API ## Using Management Via Apache ActiveMQ Artemis API
The management API in ActiveMQ Artemis is called by sending Core Client messages The management API in ActiveMQ Artemis is accessed by sending Core Client messages
to a special address, the *management address*. to a special address, the *management address*.
*Management messages* are regular Core Client messages with well-known *Management messages* are regular Core Client messages with well-known
@ -402,7 +385,7 @@ operations using Core messages:
`org.apache.activemq.artemis.api.core.management.ManagementHelper` to `org.apache.activemq.artemis.api.core.management.ManagementHelper` to
retrieve the operation result from the management reply retrieve the operation result from the management reply
For example, to find out the number of messages in the core queue For example, to find out the number of messages in the queue
`exampleQueue`: `exampleQueue`:
``` java ``` java
@ -421,8 +404,13 @@ interfaces defined in the `management` packages.
Names of the resources are built using the helper class Names of the resources are built using the helper class
`org.apache.activemq.artemis.api.core.management.ResourceNames` and are `org.apache.activemq.artemis.api.core.management.ResourceNames` and are
straightforward (e.g. `queue.exampleQueue` for the Core Queue straightforward (e.g. `queue.exampleQueue` for `QueueControl` of the Queue
`exampleQueue`. `exampleQueue`, or `broker` for the `ActiveMQServerControl`).
> *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.
### Configuring Management ### Configuring Management
@ -445,7 +433,7 @@ configured in broker.xml:
### Example ### Example
See the [examples](examples.md) chapter for an example which shows See the [Examples](examples.md) chapter for an example which shows
how to use JMS messages to manage the Apache ActiveMQ Artemis server. how to use JMS messages to manage the Apache ActiveMQ Artemis server.
## Management Notifications ## Management Notifications
@ -454,13 +442,11 @@ Apache ActiveMQ Artemis emits *notifications* to inform listeners of potentially
interesting events (creation of new resources, security violation, interesting events (creation of new resources, security violation,
etc.). etc.).
These notifications can be received by 3 different ways: These notifications can be received by two different ways:
- JMX notifications - JMX notifications
- Core messages - Notification messages
- JMS messages
### JMX Notifications ### JMX Notifications
@ -468,25 +454,25 @@ If JMX is enabled (see Configuring JMX section), JMX notifications can be receiv
subscribing to `org.apache.activemq.artemis:type=Broker,brokerName=<broker name>,module=Core,serviceType=Server` for subscribing to `org.apache.activemq.artemis:type=Broker,brokerName=<broker name>,module=Core,serviceType=Server` for
notifications on resources. notifications on resources.
### Core Messages Notifications ### Notification Messages
Apache ActiveMQ Artemis defines a special *management notification address*. Core Apache ActiveMQ Artemis defines a special *management notification address*.
queues can be bound to this address so that clients will receive Queues can be bound to this address so that clients will receive
management notifications as Core messages management notifications as messages.
A Core client which wants to receive management notifications must A client which wants to receive management notifications must
create a core queue bound to the management notification address. It can create a queue bound to the management notification address. It can
then receive the notifications from its queue. then receive the notifications from its queue.
Notifications messages are regular core messages with additional Notifications messages are regular messages with additional
properties corresponding to the notification (its type, when it properties corresponding to the notification (its type, when it
occurred, the resources which were concerned, etc.). occurred, the resources which were concerned, etc.).
Since notifications are regular core messages, it is possible to use Since notifications are regular messages, it is possible to use
message selectors to filter out notifications and receives only a subset message selectors to filter out notifications and receives only a subset
of all the notifications emitted by the server. of all the notifications emitted by the server.
#### Configuring The Core Management Notification Address #### Configuring The Management Notification Address
The management notification address to receive management notifications The management notification address to receive management notifications
is configured in `broker.xml`: is configured in `broker.xml`:
@ -495,14 +481,12 @@ is configured in `broker.xml`:
By default, the address is `activemq.notifications`. By default, the address is `activemq.notifications`.
### JMS Messages Notifications #### Receiving Notification Messages
Apache ActiveMQ Artemis's notifications can also be received using JMS messages. Apache ActiveMQ Artemis's Core JMS Client can be used to receive notifications:
It is similar to receiving notifications using Core API:
``` java ``` java
Topic notificationsTopic = ActiveMQJMSClient.createTopic("notificationsTopic"); Topic notificationsTopic = ActiveMQJMSClient.createTopic("activemq.notifications");
Session session = ... Session session = ...
MessageConsumer notificationConsumer = session.createConsumer(notificationsTopic); MessageConsumer notificationConsumer = session.createConsumer(notificationsTopic);
@ -530,7 +514,7 @@ notificationConsumer.setMessageListener(new MessageListener()
``` ```
### Example ### 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 [Examples](examples.md) chapter for an example which shows how to use a JMS `MessageListener` to receive management notifications from ActiveMQ Artemis server.
### Notification Types and Headers ### Notification Types and Headers
@ -641,7 +625,7 @@ 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 The number of messages in the queue remains the same in both cases but
its use is widely different. its use is widely different.
Message counters gives additional information about the queues: Message counters give additional information about the queues:
- `count` - `count`
@ -688,8 +672,8 @@ To enable message counters, you can set it to `true` in
<message-counter-enabled>true</message-counter-enabled> <message-counter-enabled>true</message-counter-enabled>
Message counters keeps a history of the queue metrics (10 days by Message counters keep a history of the queue metrics (10 days by
default) and samples all the queues at regular interval (10 seconds by default) and sample all the queues at regular interval (10 seconds by
default). If message counters are enabled, these values should be default). If message counters are enabled, these values should be
configured to suit your messaging use case in configured to suit your messaging use case in
`broker.xml`: `broker.xml`:
@ -720,4 +704,4 @@ messageCounter.getMessageCountDelta());
### Example ### Example
See the [examples](examples.md) chapter for an example which shows how to use message counters to retrieve information on a JMS `Queue`. See the [Examples](examples.md) chapter for an example which shows how to use message counters to retrieve information on a queue.

2
examples/features/standard/message-group/readme.html
View File

@ -36,7 +36,7 @@ under the License.
<li>Messages in a message group will be all delivered to no more than one of the queue's consumers. The consumer that receives the <li>Messages in a message group will be all delivered to no more than one of the queue's consumers. The consumer that receives the
first message of a group will receive all the messages that belong to the group.</li> first message of a group will receive all the messages that belong to the group.</li>
<p>You can make any message belong to a message group by setting its 'JMXGroupID' string property to the group id. <p>You can make any message belong to a message group by setting its 'JMSXGroupID' string property to the group id.
In this example we create a message group 'Group-0'. And make such a message group of 10 messages. It also create two consumers on the queue In this example we create a message group 'Group-0'. And make such a message group of 10 messages. It also create two consumers on the queue
where the 10 'Group-0' group messages are to be sent. You can see that with message grouping enabled, all the 10 messages will be received by where the 10 'Group-0' group messages are to be sent. You can see that with message grouping enabled, all the 10 messages will be received by
the first consumer. The second consumer will receive none. </p> the first consumer. The second consumer will receive none. </p>