JBoss Messaging 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 JBoss Messaging. It also allows clients to subscribe to management notifications.
There are 3 ways to manage JBoss Messaging:
Using JMX -- JMX is the standard way to manage Java applications
Using the core API -- management operations are sent to JBoss Messaging server using core messages
Using the JMS API -- management operations are sent to JBoss Messaging server using JMS messages
Although there are 3 different ways to manage JBoss Messaging 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.
JBoss Messaging exposes its managed resources in 2 packages:
Core resources are located in the org.jboss.messaging.core.management package
JMS resources are located in the org.jboss.messaging.jms.server.management package
The way to invoke a management operations depends whether JMX, core messages, or JMS messages are used.
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.
JBoss Messaging defines a core management API to manage core resources. For full details of the API please consult the javadoc. In summary:
Creating, deploying and destroying queues
Core queues can be created or destroyed using the management operations createQueue() or deployQueue() or destroyQueue())on the MessagingServerControl (with the ObjectName org.jboss.messaging:module=Core,type=Server or the resource name core.server)
createQueue will fail if the queue already exists while deployQueue will do nothing.
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.
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 MessagingServerControl exposes JBoss Messaging server configuration through all its attributes (e.g. getVersion() method to retrieve the server's version, etc.)
Core addresses can be managed using the AddressControl class (with the ObjectName org.jboss.messaging: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
The bulk of the core management API deals with core queues. The QueueControl class defines the Core queue management operations (with the ObjectName org.jboss.messaging: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 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.
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 Section 29.7, “Message Counters”). 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 wether the queue is durable or not, etc.)
JBoss Messaging 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.jboss.messaging: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 Section 14.1, “Understanding Acceptors”)
Diverts
They can be started or stopped using the start() or stop() method on the DivertControl class (with the ObjectName org.jboss.messaging: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 Chapter 33, Diverting and Splitting Message Flows)
Bridges
They can be started or stopped using the start() (resp. stop()) method on the BridgeControl class (with the ObjectName org.jboss.messaging: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 Chapter 34, Core Bridges)
Broadcast groups
They can be started or stopped using the start() or stop() method on the BroadcastGroupControl class (with the ObjectName org.jboss.messaging: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 Section 36.2.1, “Broadcast Groups”)
Discovery groups
They can be started or stopped using the start() or stop() method on the DiscoveryGroupControl class (with the ObjectName org.jboss.messaging: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 Section 36.2.2, “Discovery Groups”)
Cluster connections
They can be started or stopped using the start() or stop() method on the ClusterConnectionControl class (with the ObjectName org.jboss.messaging: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 Section 36.3.1, “Configuring Cluster Connections”)
JBoss Messaging 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.jboss.messaging:module=JMS,type=Server or the resource name jms.server).
Creating/destroying connection factories
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 fied 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 Chapter 14, Configuring the Transport for a list of the transport parameters)
Creating/destroying queues
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
Creating/destroying topics
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 Connection Factories can be managed using the ConnectionFactoryControl class (with the ObjectName org.jboss.messaging: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, isBlockOnNonPersistentSend() to know wether the producers created from the connection factory will block or not when sending non-persistent messages, etc.)
JMS queues can be managed using the JMSQueueControl class (with the ObjectName org.jboss.messaging: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 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.
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 Section 29.7, “Message Counters”)
Retrieving the queue attributes
The JMSQueueControl exposes JMS queue settings through its attributes (e.g. isTemporary() to know wether the queue is temporary or not, isDurable() to know wether the queue is durable or not, etc.)
JMS Topics can be managed using the TopicControl class (with the ObjectName org.jboss.messaging: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)
JBoss Messaging can be managed using JMX.
The management API is exposed by JBoss Messaging using MBeans interfaces. JBoss Messaging registers its resources with the domain org.jboss.messaging.
For example, the ObjectName to manage a JMS Queue exampleQueue is:
org.jboss.messaging:module=JMS,type=Queue,name="exampleQueue"
and the MBean is:
org.jboss.messaging.jms.server.management.JMSQueueControl
The MBean's ObjectName are built using the helper class org.jboss.messaging.core.management.ObjectNames. You can also use jconsole to find the ObjectName of the MBeans you want to manage.
Managing JBoss Messaging 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 JBoss Messaging. It can be disabled by setting jmx-management-enabled to false in jbm-configuration.xml:
<!-- false to disable JMX management for JBoss Messaging -->
<jmx-management-enabled>false</jmx-management-enabled>
If JMX is enabled, JBoss Messaging can be managed locally using jconsole. 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).
When JBoss Messaging 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 4.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 9.1.20, “JMX Management” for an example which shows how to use a remote connection to JMX and MBean proxies to manage JBoss Messaging.
The core management API in JBoss Messaging 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, JBoss Messaging 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.jboss.messaging.core.client.management.impl.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:
Create a ClientRequestor to send messages to the management address and receive replies
Create a ClientMessage
Use the helper class org.jboss.messaging.core.client.management.impl.ManagementHelper to fill the message with the management properties
Send the message using the ClientRequestor
Use the helper class org.jboss.messaging.core.client.management.impl.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, "jbm.management");
ClientMessage message = session.createClientMessage(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.jboss.messaging.core.management.ResourceNames and are straightforward (core.queue.exampleQueue for the Core Queue exampleQueue, jms.topic.exampleTopic for the JMS Topic exampleTopic, etc.).
The management address to send management messages is configured in jbm-configuration.xml:
<management-address>jbm.management</management-address>
By default, the address is jbm.management.
The management address requires a special user permission manage to be able to receive and handle management messages. This is also configured in jbm-configuration.xml:
<!-- users with the admin role will be allowed to manage -->
<!-- JBoss Messaging using management messages -->
<security-setting match="jbm.management">
<permission type="manage" roles="admin" />
</security-setting>
Using JMS messages to manage JBoss Messaging 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 = new JBossQueue("jbm.management", "jbm.management");
All the other steps are the same than for the Core API but they use JMS API instead:
create a QueueRequestor to send messages to the management address and receive replies
create a Message
use the helper class org.jboss.messaging.jms.server.management.impl.JMSManagementHelper to fill the message with the management properties
send the message using the QueueRequestor
use the helper class org.jboss.messaging.jms.server.management.impl.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 = new JBossQueue("jbm.management", "jbm.management");
QueueSession session = ...
QueueRequestor requestor = new QueueRequestor(session, managementQueue);
connection.start();
Message message = session.createMessage();
JMSManagementHelper.putAttribute(message, "jms.queue.exampleQueue", "managementQueueessageCount");
Message reply = requestor.request(message);
int count = (Integer)JMSManagementHelper.getResult(reply);
System.out.println("There are " + count + " messages in exampleQueue");
Whether JMS or the core API is used for management, the configuration steps are the same (see Section 29.3.1, “Configuring Core Management”).
See Section 9.1.24, “Management” for an example which shows how to use JMS messages to manage JBoss Messaging server.
JBoss Messaging allows replication of a live server to a backup server. This impacts management as resources created on the live server (e.g. a core address) must also be created on the backup server. Otherwise, when failover occurs, the backup server will not be able to handle messages sent to this address since its resources will have been created on the live server only and not on the backup.
JBoss Messaging replicates management operations regardless of the management API used (JMX, Core messages, JMS messages). Any management operation invoked on a live server will also be invoked on its backup server to ensure a proper replication of resources and state. For example, you only need to manage the live server: if a queue is created on the live server, JBoss Messaging will ensure that the same resource will also be created on the backup server.
If core or JMS messages are used to invoke management operations, replication is handled automatically by JBoss Messaging.
To allow this management replication with JMX, JBoss Messaging defines management cluster credentials: this special user/password must be shared by all nodes. To configure it, change the value in jbm-configuration.xml:
<management-cluster-user>JBM.MANAGEMENT.ADMIN.USER</management-cluster-user>
<management-cluster-password>CHANGE ME!!</management-cluster-password>
It is strongly suggested to change these values from their default. If they are not changed from the default, JBoss Messaging will detect this and pester you with a warning on every start-up.
JBoss Messaging internally uses Core messages to replicate management operations between the live and backup server when JMX is used. By default, there is a timeout of 5s (5000ms) to send a management request from the live server to the backup server and wait for a reply. If a reply is not received before the timeout is hit, JBoss Messaging considers the replication has failed. This timeout can be configured in jbm-configuration.xml:
<management-request-timeout>5000</management-request-timeout>
JBoss Messaging 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
If JMX is enabled (see Section 29.2.1, “Configuring JMX”), JMX notifications can be received by subscribing to 2 MBeans:
org.jboss.messaging:module=Core,type=Server for notifications on Core resources
org.jboss.messaging:module=JMS,type=Server for notifications on JMS resources
JBoss Messaging 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.
the management notification address to receive management notifications is configured in jbm-configuration.xml:
<management-notification-address>jbm.notifications</management-notification-address>
By default, the address is jbm.notifications.
JBoss Messaging'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):
Topic notificationsTopic = new JBossTopic("jbm.notifications", "jbm.notifications");
Once the notification topic is created, you can receive messages from it or set a MessageListener:
Topic notificationsTopic = new JBossTopic("jbm.notifications", "jbm.notifications");
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("------------------------");
}
});
See Section 9.1.25, “Management Notification” for an example which shows how to use a JMS MessageListener to receive management notifications from JBoss Messaging server.
Message counters can be used to obtain information on queues over time as JBoss Messaging 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
depth
The current number of messages in the queue
depthDelta
The overall number of messages added/removed from the queue since the last message counter update. For example, if depthDelta 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
By default, message counters are disabled as it might have a small negative effect on memory (the metrics are kept in memory) and CPU (the queues are sampled at regular interval).
To enable message counters, you can set it to true in jbm-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 jbm-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 JBoss Messaging'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",
counter.getDepth(),
counter.getDepthDelta());
See Section 9.1.27, “Message Counter” for an example which shows how to use message counters to retrieve information on a JMS Queue.