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 2014/12/08 16:49:41 UTC
[10/25] activemq-6 git commit: ACTIVEMQ6-9 - port to markdown
http://git-wip-us.apache.org/repos/asf/activemq-6/blob/4245a6b4/docs/user-manual/en/management.md
----------------------------------------------------------------------
diff --git a/docs/user-manual/en/management.md b/docs/user-manual/en/management.md
new file mode 100644
index 0000000..5c37827
--- /dev/null
+++ b/docs/user-manual/en/management.md
@@ -0,0 +1,1094 @@
+Management
+==========
+
+ActiveMQ has an extensive management API that allows a user to modify a
+server configuration, create new resources (e.g. JMS queues and topics),
+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
+the operations allows a client to *manage* ActiveMQ. It also allows
+clients to subscribe to management notifications.
+
+There are 3 ways to manage ActiveMQ:
+
+- Using JMX -- JMX is the standard way to manage Java applications
+
+- Using the core API -- management operations are sent to ActiveMQ
+ server using *core messages*
+
+- Using the JMS API -- management operations are sent to ActiveMQ
+ server using *JMS messages*
+
+Although there are 3 different ways to manage ActiveMQ 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 or
+JMS messages.
+
+This choice depends on your requirements, your application settings and
+your environment to decide which way suits you best.
+
+The Management API
+==================
+
+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 can be invoked for this type of resource.
+
+ActiveMQ exposes its managed resources in 2 packages:
+
+- *Core* resources are located in the
+ `org.apache.activemq.api.core.management` package
+
+- *JMS* resources are located in the
+ `org.apache.activemq.api.jms.management` package
+
+The way to invoke a *management operations* depends whether JMX, core
+messages, or 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*.
+
+Core Management API
+-------------------
+
+ActiveMQ defines a core management API to manage core resources. For
+full details of the API please consult the javadoc. In summary:
+
+### Core Server Management
+
+- Listing, creating, deploying and destroying queues
+
+ A list of deployed core queues can be retrieved using the
+ `getQueueNames()` method.
+
+ Core queues can be created or destroyed using the management
+ operations `createQueue()` or `deployQueue()` or `destroyQueue()`)on
+ the `ActiveMQServerControl` (with the ObjectName
+ `org.apache.activemq:module=Core,type=Server` or the resource name
+ `core.server`)
+
+ `createQueue` will fail if the queue already exists while
+ `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
+
+ 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()`.
+
+- 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.
+
+- 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.
+
+- Retrieving the server configuration and attributes
+
+ The `ActiveMQServerControl` exposes ActiveMQ 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
+
+ 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()`) on the
+ `ActiveMQServerControl` (with the ObjectName
+ `org.apache.activemq:module=Core,type=Server` or the resource name
+ `core.server`).
+
+- It is possible to stop the server and force failover to occur with
+ any currently attached clients.
+
+ to do this use the `forceFailover()` on the `ActiveMQServerControl`
+ (with the ObjectName `org.apache.activemq:module=Core,type=Server`
+ or the resource name `core.server`)
+
+ > **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.
+
+### Core Address Management
+
+Core addresses can be managed using the `AddressControl` class (with the
+ObjectName `org.apache.activemq:module=Core,type=Address,name="<the
+ address name>"` or the resource name
+`core.address.<the
+ address name>`).
+
+- 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
+
+### Core Queue Management
+
+The bulk of the core management API deals with core queues. The
+`QueueControl` class defines the Core queue management operations (with
+the ObjectName
+`org.apache.activemq:module=Core,type=Queue,address="<the bound
+ address>",name="<the queue name>"` or the resource
+name `core.queue.<the queue name>`).
+
+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.)
+
+- 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 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.
+
+- 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 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
+
+ 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
+
+ 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 can be listed for a queue with the
+ `listMessageCounter()` and `listMessageCounterHistory()` methods
+ (see ?). The message counters can also be reset for a single queue
+ using the `resetMessageCounter()` method.
+
+- Retrieving the queue attributes
+
+ The `QueueControl` exposes Core 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
+
+ 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 resume, it'll begin delivering the queued messages, if
+ any.
+
+### Other Core Resources Management
+
+ActiveMQ 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
+
+ They can be started or stopped using the `start()` or. `stop()`
+ method on the `AcceptorControl` class (with the ObjectName
+ `org.apache.activemq:module=Core,type=Acceptor,name="<the acceptor
+ name>"` or the resource name
+ `core.acceptor.<the
+ address name>`). The acceptors parameters
+ can be retrieved using the `AcceptorControl` attributes (see ?)
+
+- Diverts
+
+ They can be started or stopped using the `start()` or `stop()`
+ method on the `DivertControl` class (with the ObjectName
+ `org.apache.activemq:module=Core,type=Divert,name=<the divert name>`
+ or the resource name `core.divert.<the divert name>`). Diverts
+ parameters can be retrieved using the `DivertControl` attributes
+ (see ?)
+
+- Bridges
+
+ They can be started or stopped using the `start()` (resp. `stop()`)
+ method on the `BridgeControl` class (with the ObjectName
+ `org.apache.activemq:module=Core,type=Bridge,name="<the bridge
+ name>"` or the resource name
+ `core.bridge.<the bridge
+ name>`). Bridges parameters can be retrieved
+ using the `BridgeControl` attributes (see ?)
+
+- Broadcast groups
+
+ They can be started or stopped using the `start()` or `stop()`
+ method on the `BroadcastGroupControl` class (with the ObjectName
+ `org.apache.activemq:module=Core,type=BroadcastGroup,name="<the broadcast group
+ name>"` or the resource name
+ `core.broadcastgroup.<the broadcast group name>`). Broadcast groups
+ parameters can be retrieved using the `BroadcastGroupControl`
+ attributes (see ?)
+
+- Discovery groups
+
+ They can be started or stopped using the `start()` or `stop()`
+ method on the `DiscoveryGroupControl` class (with the ObjectName
+ `org.apache.activemq:module=Core,type=DiscoveryGroup,name="<the discovery group
+ name>"` or the resource name
+ `core.discovery.<the
+ discovery group name>`). Discovery groups
+ parameters can be retrieved using the `DiscoveryGroupControl`
+ attributes (see ?)
+
+- Cluster connections
+
+ They can be started or stopped using the `start()` or `stop()`
+ method on the `ClusterConnectionControl` class (with the ObjectName
+ `org.apache.activemq:module=Core,type=ClusterConnection,name="<the cluster
+ connection name>"` or the resource name
+ `core.clusterconnection.<the cluster connection name>`). Cluster
+ connections parameters can be retrieved using the
+ `ClusterConnectionControl` attributes (see ?)
+
+JMS Management API
+------------------
+
+ActiveMQ defines a JMS Management API to manage JMS *administrated
+objects* (i.e. JMS queues, topics and connection factories).
+
+### JMS Server Management
+
+JMS Resources (connection factories and destinations) can be created
+using the `JMSServerControl` class (with the ObjectName
+`org.apache.activemq:module=JMS,type=Server` or the resource name
+`jms.server`).
+
+- Listing, creating, destroying connection factories
+
+ Names of the deployed connection factories can be retrieved by the
+ `getConnectionFactoryNames()` method.
+
+ JMS connection factories can be created or destroyed using the
+ `createConnectionFactory()` methods or `destroyConnectionFactory()`
+ methods. These connection factories are bound to JNDI so that JMS
+ clients can look them up. If a graphical console is used to create
+ the connection factories, the transport parameters are specified in
+ the text field input as a comma-separated list of key=value (e.g.
+ `key1=10, key2="value", key3=false`). If there are multiple
+ transports defined, you need to enclose the key/value pairs between
+ curly braces. For example `{key=10}, {key=20}`. In that case, the
+ first `key` will be associated to the first transport configuration
+ and the second `key` will be associated to the second transport
+ configuration (see ? for a list of the transport parameters)
+
+- Listing, creating, destroying queues
+
+ Names of the deployed JMS queues can be retrieved by the
+ `getQueueNames()` method.
+
+ JMS queues can be created or destroyed using the `createQueue()`
+ methods or `destroyQueue()` methods. These queues are bound to JNDI
+ so that JMS clients can look them up
+
+- Listing, creating/destroying topics
+
+ Names of the deployed topics can be retrieved by the
+ `getTopicNames()` method.
+
+ JMS topics can be created or destroyed using the `createTopic()` or
+ `destroyTopic()` methods. These topics are bound to JNDI so that JMS
+ clients can look them up
+
+- Listing and closing remote connections
+
+ JMS Clients 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()`.
+
+### JMS ConnectionFactory Management
+
+JMS Connection Factories can be managed using the
+`ConnectionFactoryControl` class (with the ObjectName
+`org.apache.activemq:module=JMS,type=ConnectionFactory,name="<the connection factory
+ name>"` or the resource name
+`jms.connectionfactory.<the
+ connection factory name>`).
+
+- Retrieving connection factory attributes
+
+ The `ConnectionFactoryControl` exposes JMS ConnectionFactory
+ configuration through its attributes (e.g. `getConsumerWindowSize()`
+ to retrieve the consumer window size for flow control,
+ `isBlockOnNonDurableSend()` to know whether the producers created
+ from the connection factory will block or not when sending
+ non-durable messages, etc.)
+
+### JMS Queue Management
+
+JMS queues can be managed using the `JMSQueueControl` class (with the
+ObjectName `org.apache.activemq:module=JMS,type=Queue,name="<the queue
+ name>"` or the resource name `jms.queue.<the queue
+ name>`).
+
+*The management operations on a JMS queue are very similar to the
+operations on a core queue.*
+
+- 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 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.
+
+- 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 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
+
+ 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
+
+ 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 can be listed for a queue with the
+ `listMessageCounter()` and `listMessageCounterHistory()` methods
+ (see ?)
+
+- Retrieving the queue attributes
+
+ The `JMSQueueControl` exposes JMS queue settings through its
+ attributes (e.g. `isTemporary()` to know whether the queue is
+ temporary or not, `isDurable()` to know whether the queue is durable
+ or not, etc.)
+
+- Pausing and resuming queues
+
+ The `JMSQueueControl` can pause and resume the underlying queue.
+ When the queue is paused it will continue to receive messages but
+ will not deliver them. When resumed again it will deliver the
+ enqueued messages, if any.
+
+### JMS Topic Management
+
+JMS Topics can be managed using the `TopicControl` class (with the
+ObjectName `org.apache.activemq:module=JMS,type=Topic,name="<the topic
+ name>"` or the resource name `jms.topic.<the topic
+ name>`).
+
+- Listing subscriptions and messages
+
+ JMS topics subscriptions can be listed using the
+ `listAllSubscriptions()`, `listDurableSubscriptions()`,
+ `listNonDurableSubscriptions()` methods. These methods return arrays
+ of `Object` representing the subscriptions information (subscription
+ name, client ID, durability, message count, etc.). It is also
+ possible to list the JMS messages for a given subscription with the
+ `listMessagesForSubscription()` method.
+
+- Dropping subscriptions
+
+ Durable subscriptions can be dropped from the topic using the
+ `dropDurableSubscription()` method.
+
+- Counting subscriptions messages
+
+ The `countMessagesForSubscription()` method can be used to know the
+ number of messages held for a given subscription (with an optional
+ message selector to know the number of messages matching the
+ selector)
+
+Using Management Via JMX
+========================
+
+ActiveMQ can be managed using
+[JMX](http://www.oracle.com/technetwork/java/javase/tech/javamanagement-140525.html).
+
+The management API is exposed by ActiveMQ using MBeans interfaces.
+ActiveMQ registers its resources with the domain `org.apache.activemq`.
+
+For example, the `ObjectName` to manage a JMS Queue `exampleQueue` is:
+
+ org.apache.activemq:module=JMS,type=Queue,name="exampleQueue"
+
+and the MBean is:
+
+ org.apache.activemq.api.jms.management.JMSQueueControl
+
+The MBean's `ObjectName` are built using the helper class
+`org.apache.activemq.api.core.management.ObjectNameBuilder`. You can
+also use `jconsole` to find the `ObjectName` of the MBeans you want to
+manage.
+
+Managing ActiveMQ 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 ActiveMQ. It can be disabled by
+setting `jmx-management-enabled` to `false` in
+`activemq-configuration.xml`:
+
+ <!-- false to disable JMX management for ActiveMQ -->
+ <jmx-management-enabled>false</jmx-management-enabled>
+
+If JMX is enabled, ActiveMQ can be managed locally using `jconsole`.
+
+> **Note**
+>
+> Remote connections to JMX are not enabled by default for security
+> reasons. Please refer to [Java Management
+> guide](http://docs.oracle.com/javase/6/docs/technotes/guides/management/agent.html)
+> to configure the server for remote management (system properties must
+> be set in `run.sh` or `run.bat` scripts).
+
+By default, ActiveMQ server uses the JMX domain "org.apache.activemq".
+To manage several ActiveMQ servers from the *same* MBeanServer, the JMX
+domain can be configured for each individual ActiveMQ server by setting
+`jmx-domain` in `activemq-configuration.xml`:
+
+ <!-- use a specific JMX domain for ActiveMQ MBeans -->
+ <jmx-domain>my.org.apache.activemq</jmx-domain>
+
+### MBeanServer configuration
+
+When ActiveMQ is run in standalone, it uses the Java Virtual Machine's
+`Platform MBeanServer` to register its MBeans. This is configured in
+JBoss Microcontainer Beans file (see ?):
+
+ <!-- MBeanServer -->
+ <bean name="MBeanServer" class="javax.management.MBeanServer">
+ <constructor factoryClass="java.lang.management.ManagementFactory"
+ factoryMethod="getPlatformMBeanServer" />
+ </bean>
+
+When it is integrated in JBoss AS 5+, it uses the Application Server's
+own MBean Server so that it can be managed using AS 5's jmx-console:
+
+ <!-- MBeanServer -->
+ <bean name="MBeanServer" class="javax.management.MBeanServer">
+ <constructor factoryClass="org.jboss.mx.util.MBeanServerLocator"
+ factoryMethod="locateJBoss" />
+ </bean>
+
+Example
+-------
+
+See ? for an example which shows how to use a remote connection to JMX
+and MBean proxies to manage ActiveMQ.
+
+Using Management Via Core API
+=============================
+
+The core management API in ActiveMQ is called by sending Core messages
+to a special address, the *management address*.
+
+*Management messages* are regular Core messages with well-known
+properties that the server needs to understand to interact with the
+management API:
+
+- The name of the managed resource
+
+- The name of the management operation
+
+- The parameters of the management operation
+
+When such a management message is sent to the management address,
+ActiveMQ 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](http://json.org)
+String rather than Java Serialization (the
+`org.apache.activemq.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:
+
+1. Create a `ClientRequestor` to send messages to the management
+ address and receive replies
+
+2. Create a `ClientMessage`
+
+3. Use the helper class
+ `org.apache.activemq.api.core.management.ManagementHelper` to fill
+ the message with the management properties
+
+4. Send the message using the `ClientRequestor`
+
+5. Use the helper class
+ `org.apache.activemq.api.core.management.ManagementHelper` to
+ retrieve the operation result from the management reply
+
+For example, to find out the number of messages in the core queue
+`exampleQueue`:
+
+ ClientSession session = ...
+ ClientRequestor requestor = new ClientRequestor(session, "jms.queue.activemq.management");
+ ClientMessage message = session.createMessage(false);
+ ManagementHelper.putAttribute(message, "core.queue.exampleQueue", "messageCount");
+ session.start();
+ ClientMessage reply = requestor.request(m);
+ 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.
+
+Names of the resources are built using the helper class
+`org.apache.activemq.api.core.management.ResourceNames` and are
+straightforward (`core.queue.exampleQueue` for the Core Queue
+`exampleQueue`, `jms.topic.exampleTopic` for the JMS Topic
+`exampleTopic`, etc.).
+
+Configuring Core Management
+---------------------------
+
+The management address to send management messages is configured in
+`activemq-configuration.xml`:
+
+ <management-address>jms.queue.activemq.management</management-address>
+
+By default, the address is `jms.queue.activemq.management` (it is
+prepended by "jms.queue" so that JMS clients can also send management
+messages).
+
+The management address requires a *special* user permission `manage` to
+be able to receive and handle management messages. This is also
+configured in activemq-configuration.xml:
+
+ <!-- users with the admin role will be allowed to manage -->
+ <!-- ActiveMQ using management messages -->
+ <security-setting match="jms.queue.activemq.management">
+ <permission type="manage" roles="admin" />
+ </security-setting>
+
+Using Management Via JMS
+========================
+
+Using JMS messages to manage ActiveMQ is very similar to using core API.
+
+An important difference is that JMS requires a JMS queue to send the
+messages to (instead of an address for the core API).
+
+The *management queue* is a special queue and needs to be instantiated
+directly by the client:
+
+ Queue managementQueue = ActiveMQJMSClient.createQueue("activemq.management");
+
+All the other steps are the same than for the Core API but they use JMS
+API instead:
+
+1. create a `QueueRequestor` to send messages to the management address
+ and receive replies
+
+2. create a `Message`
+
+3. use the helper class
+ `org.apache.activemq.api.jms.management.JMSManagementHelper` to fill
+ the message with the management properties
+
+4. send the message using the `QueueRequestor`
+
+5. use the helper class
+ `org.apache.activemq.api.jms.management.JMSManagementHelper` to
+ retrieve the operation result from the management reply
+
+For example, to know the number of messages in the JMS queue
+`exampleQueue`:
+
+ Queue managementQueue = ActiveMQJMSClient.createQueue("activemq.management");
+
+ QueueSession session = ...
+ QueueRequestor requestor = new QueueRequestor(session, managementQueue);
+ connection.start();
+ Message message = session.createMessage();
+ JMSManagementHelper.putAttribute(message, "jms.queue.exampleQueue", "messageCount");
+ Message reply = requestor.request(message);
+ int count = (Integer)JMSManagementHelper.getResult(reply);
+ System.out.println("There are " + count + " messages in exampleQueue");
+
+Configuring JMS Management
+--------------------------
+
+Whether JMS or the core API is used for management, the configuration
+steps are the same (see ?).
+
+Example
+-------
+
+See ? for an example which shows how to use JMS messages to manage
+ActiveMQ server.
+
+Management Notifications
+========================
+
+ActiveMQ emits *notifications* to inform listeners of potentially
+interesting events (creation of new resources, security violation,
+etc.).
+
+These notifications can be received by 3 different ways:
+
+- JMX notifications
+
+- Core messages
+
+- JMS messages
+
+JMX Notifications
+-----------------
+
+If JMX is enabled (see ?), JMX notifications can be received by
+subscribing to 2 MBeans:
+
+- `org.apache.activemq:module=Core,type=Server` for notifications on
+ *Core* resources
+
+- `org.apache.activemq:module=JMS,type=Server` for notifications on
+ *JMS* resources
+
+Core Messages Notifications
+---------------------------
+
+ActiveMQ defines a special *management notification address*. Core
+queues can be bound to this address so that clients will receive
+management notifications as Core messages
+
+A Core client which wants to receive management notifications must
+create a core queue bound to the management notification address. It can
+then receive the notifications from its queue.
+
+Notifications messages are regular core messages with additional
+properties corresponding to the notification (its type, when it
+occurred, the resources which were concerned, etc.).
+
+Since notifications are regular core 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 Core Management Notification Address
+
+The management notification address to receive management notifications
+is configured in `activemq-configuration.xml`:
+
+ <management-notification-address>activemq.notifications</management-notification-address>
+
+By default, the address is `activemq.notifications`.
+
+JMS Messages Notifications
+--------------------------
+
+ActiveMQ's notifications can also be received using JMS messages.
+
+It is similar to receiving notifications using Core API but an important
+difference is that JMS requires a JMS Destination to receive the
+messages (preferably a Topic).
+
+To use a JMS Destination to receive management notifications, you must
+change the server's management notification address to start with
+`jms.queue` if it is a JMS Queue or `jms.topic` if it is a JMS Topic:
+
+ <!-- notifications will be consumed from "notificationsTopic" JMS Topic -->
+ <management-notification-address>jms.topic.notificationsTopic</management-notification-address>
+
+Once the notification topic is created, you can receive messages from it
+or set a `MessageListener`:
+
+ Topic notificationsTopic = ActiveMQJMSClient.createTopic("notificationsTopic");
+
+ 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("------------------------");
+ }
+ });
+
+Example
+-------
+
+See ? for an example which shows how to use a JMS `MessageListener` to
+receive management notifications from ActiveMQ 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
+`_HQ_NotifType` (value noted in parentheses) and `_HQ_NotifTimestamp`
+header. The timestamp is the un-formatted result of a call to
+`java.lang.System.currentTimeMillis()`.
+
+- `BINDING_ADDED` (0)
+
+ `_HQ_Binding_Type`, `_HQ_Address`, `_HQ_ClusterName`,
+ `_HQ_RoutingName`, `_HQ_Binding_ID`, `_HQ_Distance`,
+ `_HQ_FilterString`
+
+- `BINDING_REMOVED` (1)
+
+ `_HQ_Address`, `_HQ_ClusterName`, `_HQ_RoutingName`,
+ `_HQ_Binding_ID`, `_HQ_Distance`, `_HQ_FilterString`
+
+- `CONSUMER_CREATED` (2)
+
+ `_HQ_Address`, `_HQ_ClusterName`, `_HQ_RoutingName`, `_HQ_Distance`,
+ `_HQ_ConsumerCount`, `_HQ_User`, `_HQ_RemoteAddress`,
+ `_HQ_SessionName`, `_HQ_FilterString`
+
+- `CONSUMER_CLOSED` (3)
+
+ `_HQ_Address`, `_HQ_ClusterName`, `_HQ_RoutingName`, `_HQ_Distance`,
+ `_HQ_ConsumerCount`, `_HQ_User`, `_HQ_RemoteAddress`,
+ `_HQ_SessionName`, `_HQ_FilterString`
+
+- `SECURITY_AUTHENTICATION_VIOLATION` (6)
+
+ `_HQ_User`
+
+- `SECURITY_PERMISSION_VIOLATION` (7)
+
+ `_HQ_Address`, `_HQ_CheckType`, `_HQ_User`
+
+- `DISCOVERY_GROUP_STARTED` (8)
+
+ `name`
+
+- `DISCOVERY_GROUP_STOPPED` (9)
+
+ `name`
+
+- `BROADCAST_GROUP_STARTED` (10)
+
+ `name`
+
+- `BROADCAST_GROUP_STOPPED` (11)
+
+ `name`
+
+- `BRIDGE_STARTED` (12)
+
+ `name`
+
+- `BRIDGE_STOPPED` (13)
+
+ `name`
+
+- `CLUSTER_CONNECTION_STARTED` (14)
+
+ `name`
+
+- `CLUSTER_CONNECTION_STOPPED` (15)
+
+ `name`
+
+- `ACCEPTOR_STARTED` (16)
+
+ `factory`, `id`
+
+- `ACCEPTOR_STOPPED` (17)
+
+ `factory`, `id`
+
+- `PROPOSAL` (18)
+
+ `_JBM_ProposalGroupId`, `_JBM_ProposalValue`, `_HQ_Binding_Type`,
+ `_HQ_Address`, `_HQ_Distance`
+
+- `PROPOSAL_RESPONSE` (19)
+
+ `_JBM_ProposalGroupId`, `_JBM_ProposalValue`,
+ `_JBM_ProposalAltValue`, `_HQ_Binding_Type`, `_HQ_Address`,
+ `_HQ_Distance`
+
+- `CONSUMER_SLOW` (21)
+
+ `_HQ_Address`, `_HQ_ConsumerCount`, `_HQ_RemoteAddress`,
+ `_HQ_ConnectionName`, `_HQ_ConsumerName`, `_HQ_SessionName`
+
+Message Counters
+================
+
+Message counters can be used to obtain information on queues *over time*
+as ActiveMQ 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.
+
+Message counters gives additional information about the queues:
+
+- `count`
+
+ The *total* number of messages added to the queue since the server
+ was started
+
+- `countDelta`
+
+ the number of messages added to the queue *since the last message
+ counter update*
+
+- `messageCount`
+
+ The *current* number of messages in the queue
+
+- `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)
+
+- `lastAddTimestamp`
+
+ The timestamp of the last time a message was added to the queue
+
+- `udpateTimestamp`
+
+ 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`.
+
+Configuring Message Counters
+----------------------------
+
+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
+`activemq-configuration.xml`:
+
+ <message-counter-enabled>true</message-counter-enabled>
+
+Message counters keeps a history of the queue metrics (10 days by
+default) and samples 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
+`activemq-configuration.xml`:
+
+ <!-- keep history for a week -->
+ <message-counter-max-day-history>7</message-counter-max-day-history>
+ <!-- sample the queues every minute (60000ms) -->
+ <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 JMS Queue using JMX:
+
+ // retrieve a connection to ActiveMQ's MBeanServer
+ MBeanServerConnection mbsc = ...
+ JMSQueueControlMBean queueControl = (JMSQueueControl)MBeanServerInvocationHandler.newProxyInstance(mbsc,
+ on,
+ JMSQueueControl.class,
+ false);
+ // message counters are retrieved as a JSON String
+ String counters = queueControl.listMessageCounter();
+ // use the MessageCounterInfo helper class to manipulate message counters more easily
+ MessageCounterInfo messageCounter = MessageCounterInfo.fromJSON(counters);
+ System.out.format("%s message(s) in the queue (since last sample: %s)\n",
+ messageCounter.getMessageCount(),
+ messageCounter.getMessageCountDelta());
+
+Example
+-------
+
+See ? for an example which shows how to use message counters to retrieve
+information on a JMS `Queue`.
+
+Administering ActiveMQ Resources Using The JBoss AS Admin Console
+=================================================================
+
+Its possible to create and configure ActiveMQ resources via the admin
+console within the JBoss Application Server.
+
+The Admin Console will allow you to create destinations (JMS Topics and
+Queues) and JMS Connection Factories.
+
+Once logged in to the admin console you will see a JMS Manager item in
+the left hand tree. All ActiveMQ resources will be configured via this.
+This will have a child items for JMS Queues, Topics and Connection
+Factories, clicking on each node will reveal which resources are
+currently available. The following sections explain how to create and
+configure each resource in turn.
+
+JMS Queues
+----------
+
+To create a new JMS Queue click on the JMS Queues item to reveal the
+available queues. On the right hand panel you will see an add a new
+resource button, click on this and then choose the default(JMS Queue)
+template and click continue. The important things to fill in here are
+the name of the queue and the JNDI name of the queue. The JNDI name is
+what you will use to look up the queue in JNDI from your client. For
+most queues this will be the only info you will need to provide as
+sensible defaults are provided for the others. You will also see a
+security roles section near the bottom. If you do not provide any roles
+for this queue then the servers default security configuration will be
+used, after you have created the queue these will be shown in the
+configuration. All configuration values, except the name and JNDI name,
+can be changed via the configuration tab after clicking on the queue in
+the admin console. The following section explains these in more detail
+
+After highlighting the configuration you will see the following screen
+
+
+
+The name and JNDI name can't be changed, if you want to change these
+recreate the queue with the appropriate settings. The rest of the
+configuration options, apart from security roles, relate to address
+settings for a particular address. The default address settings are
+picked up from the servers configuration, if you change any of these
+settings or create a queue via the console a new Address Settings entry
+will be added. For a full explanation on Address Settings see ?
+
+To delete a queue simply click on the delete button beside the queue
+name in the main JMS Queues screen. This will also delete any address
+settings or security settings previously created for the queues address
+
+The last part of the configuration options are security roles. If non
+are provided on creation then the servers default security settings will
+be shown. If these are changed or updated then new security settings are
+created for the address of this queue. For more information on security
+setting see ?
+
+It is also possible via the metrics tab to view statistics for this
+queue. This will show statistics such as message count, consumer count
+etc.
+
+Operations can be performed on a queue via the control tab. This will
+allow you to start and stop the queue, list,move,expire and delete
+messages from the queue and other useful operations. To invoke an
+operation click on the button for the operation you want, this will take
+you to a screen where you can parameters for the operation can be set.
+Once set clicking the ok button will invoke the operation, results
+appear at the bottom of the screen.
+
+JMS Topics
+----------
+
+Creating and configuring JMS Topics is almost identical to creating
+queues. The only difference is that the configuration will be applied to
+the queue representing a subscription.
+
+JMS Connection Factories
+------------------------
+
+The format for creating connection factories is the same as for JMS
+Queues and topics apart from the configuration being different. For as
+list of all the connection factory settings see the configuration index