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
Step One
Create aClientRequestor
to send messages to the management address and receive repliesStep Two
Create aClientMessage
Step Three
Use the helper classorg.hornetq.api.core.management.ManagementHelper
to fill the message with the management properties.Step Four
Send the message using theClientRequestor
Step Five
Use the helper classorg.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>