JBoss.orgCommunity Documentation

Chapter 30. Management

30.1. The Management API
30.1.1. Core Management API
30.1.2. JMS Management API
30.2. Using Management Via JMX
30.2.1. Configuring JMX
30.2.2. Example
30.3. Using Management Via Core API
30.3.1. Configuring Core Management
30.4. Using Management Via JMS
30.4.1. Configuring JMS Management
30.4.2. Example
30.5. Management Notifications
30.5.1. JMX Notifications
30.5.2. Core Messages Notifications
30.5.3. JMS Messages Notifications
30.5.4. Example
30.6. Message Counters
30.6.1. Configuring Message Counters
30.6.2. Example
30.7. Administering HornetQ Resources Using The JBoss AS Admin Console
30.7.1. JMS Queues
30.7.2. JMS Topics
30.7.3. JMS Connection Factories

HornetQ 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 HornetQ. It also allows clients to subscribe to management notifications.

There are 3 ways to manage HornetQ:

Although there are 3 different ways to manage HornetQ 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.

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.

HornetQ exposes its managed resources in 2 packages:

The way to invoke a management operations depends whether JMX, core messages, or JMS messages are used.

HornetQ defines a core management API to manage core resources. For full details of the API please consult the javadoc. In summary:

The bulk of the core management API deals with core queues. The QueueControl class defines the Core queue management operations (with the ObjectName org.hornetq: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.)

HornetQ 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:

HornetQ defines a JMS Management API to manage JMS administrated objects (i.e. JMS queues, topics and connection factories).

JMS Resources (connection factories and destinations) can be created using the JMSServerControl class (with the ObjectName org.hornetq:module=JMS,type=Server or the resource name jms.server).

JMS queues can be managed using the JMSQueueControl class (with the ObjectName org.hornetq: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.

HornetQ can be managed using JMX.

The management API is exposed by HornetQ using MBeans interfaces. HornetQ registers its resources with the domain org.hornetq.

For example, the ObjectName to manage a JMS Queue exampleQueue is:

   org.hornetq:module=JMS,type=Queue,name="exampleQueue"   
      

and the MBean is:

   org.hornetq.api.jms.management.JMSQueueControl   
      

The MBean's ObjectName are built using the helper class org.hornetq.api.core.management.ObjectNameBuilder. You can also use jconsole to find the ObjectName of the MBeans you want to manage.

Managing HornetQ 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.

By default, JMX is enabled to manage HornetQ. It can be disabled by setting jmx-management-enabled to false in hornetq-configuration.xml:

<!-- false to disable JMX management for HornetQ -->
<jmx-management-enabled>false</jmx-management-enabled>            
         

If JMX is enabled, HornetQ 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 to configure the server for remote management (system properties must be set in run.sh or run.bat scripts).

By default, HornetQ server uses the JMX domain "org.hornetq". To manage several HornetQ servers from the same MBeanServer, the JMX domain can be configured for each individual HornetQ server by setting jmx-domain in hornetq-configuration.xml:

<!-- use a specific JMX domain for HornetQ MBeans -->
<jmx-domain>my.org.hornetq</jmx-domain>            
         

When HornetQ 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 Section 6.7, “JBoss Microcontainer Beans File”):

<!-- 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>            
            

See Section 11.1.28, “JMX Management” for an example which shows how to use a remote connection to JMX and MBean proxies to manage HornetQ.

The core management API in HornetQ 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:

When such a management message is sent to the management address, HornetQ 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 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:

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

  2. Create a ClientMessage

  3. Use the helper class org.hornetq.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.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, etc.).

Using JMS messages to manage HornetQ 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 = HornetQJMSClient.createQueue("hornetq.management");
      

All the other steps are the same than for the Core API but they use JMS API instead:

For example, to know the number of messages in the JMS queue exampleQueue:

   Queue managementQueue = HornetQJMSClient.createQueue("hornetq.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");
      

See Section 11.1.31, “Management” for an example which shows how to use JMS messages to manage HornetQ server.

HornetQ 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:

If JMX is enabled (see Section 30.2.1, “Configuring JMX”), JMX notifications can be received by subscribing to 2 MBeans:

  • org.hornetq:module=Core,type=Server for notifications on Core resources

  • org.hornetq:module=JMS,type=Server for notifications on JMS resources

See Section 11.1.32, “Management Notification” for an example which shows how to use a JMS MessageListener to receive management notifications from HornetQ server.

Message counters can be used to obtain information on queues over time as HornetQ 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:

See Section 11.1.33, “Message Counter” for an example which shows how to use message counters to retrieve information on a JMS Queue.

Its possible to create and configure HornetQ 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 HornetQ 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.

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 cant 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 enrty will be added. For a full explanation on Address Settings see Section 25.3, “Configuring Queues Via Address Settings”

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 securty settings are created for the address of this queue. For more information on securuty setting see Chapter 31, Security

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 opertion can be set. Once set clicking the ok button will invoke the operation, results appear at the bottom of the screen.