28.3. Using Management Via Core API

The core management API in HornetQ is called by sending core messages to 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 a management message is sent to the management address, HornetQ processes the message in the following way:
  • extracts the information
  • invokes the operation on the managed resources
  • sends a management reply to the management message's reply-to address.
The management reply sent to the reply-to address is controlled by the org.hornetq.core.client.impl.ClientMessageImpl.REPLYTO_HEADER_NAME parameter.
A ClientConsumer can be used to consume the management reply and retrieve the result of the operation (if any) stored in the body of the reply. For portability, results are returned as a JSON string rather than Java Serialization. The org.hornetq.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:

Procedure 28.1. Invoking Management Operations

  1. Step One

    Create a ClientRequestor to send messages to the management address and receive replies

  2. Step Two

    Create a ClientMessage

  3. Step Three

    Use the helper class org.hornetq.api.core.management.ManagementHelper to fill the message with the management properties.

  4. Step Four

    Send the message using the ClientRequestor

  5. Step Five

    Use the helper class org.hornetq.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.hornetq.management");
   ClientMessage message = session.createMessage(false);
   ManagementHelper.putAttribute(message, "core.queue.exampleQueue", "messageCount");
   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.hornetq.api.core.management.ResourceNames and are straightforward (core.queue.exampleQueue for the Core Queue exampleQueue, jms.topic.exampleTopic for the JMS Topic exampleTopic, and so on).

28.3.1. Configuring Core Management

The management address to send management messages is configured in <JBOSS_HOME>/jboss-as/server/<PROFILE>/deploy/hornetq/hornetq-configuration.xml: 
<management-address>jms.queue.hornetq.management</management-address>
By default, the address is jms.queue.hornetq.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 <JBOSS_HOME>/jboss-as/server/<PROFILE>/deploy/hornetq/hornetq-configuration.xml: 
<!-- users with the admin role will be allowed to manage --> 
<!-- HornetQ using management messages        -->
<security-setting match="jms.queue.hornetq.management">
   <permission type="manage" roles="admin" />
</security-setting>