Chapter 28. Management
HornetQ has an extensive management API that allows a user to:
- Modify a server configuration;
- Create new resources (for example, JMS queues and topics);
- Inspect these resources (for example, how many messages are currently held in a queue);
- Interact with it (that is, to remove messages from a queue).
All the operations allow a client to manage HornetQ. It also allows clients to subscribe to management notifications.
There are three ways to manage HornetQ:
- Using JMX; JMX is the standard way to manage Java applications.
- Using the core API; management operations are sent to HornetQ server using core messages.
- Using the JMS API; management operations are sent to HornetQ server using JMS messages.
Although there are three 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.
28.1. The Management API
The management API is the same regardless of the way you invoke management operations. A Java interface describing what can be invoked exists for each type of managed resource.
HornetQ exposes its managed resources in two packages:
- Core resources are located in the org.hornetq.api.core.management package.
- JMS resources are located in the org.hornetq.api.jms.management package.
The way to invoke a management operation depends whether JMX, core messages, or JMS messages are used.
Note
A few management operations requires a filter parameter to choose which messages are involved by the operation. Passing
null
or an empty string means that the management operation will be performed on all messages.
28.1.1. Core Management API
HornetQ defines a core management API to manage core resources. In summary:
28.1.1.1. 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()
deployQueue()
destroyQueue()
on theHornetQServerControl
(with the ObjectNameorg.hornetq:module=Core,type=Server
or the resource namecore.server
)
createQueue
will fail if the queue already exists whiledeployQueue
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 is resumed, it will begin delivering the queued messages. - Listing and closing remote connections
- Client remote addresses can be retrieved using
listRemoteAddresses()
. It is also possible to close the connections associated with a remote address using thecloseConnectionsForAddress()
method.Alternatively, connection ids can be listed usinglistConnectionIDs()
and all the sessions for a given connection id can be listed usinglistSessions()
. - Transaction heuristic operations
- In the case of a server crash, some transactions may require manual intervention when the server restarts. 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, thecommitPreparedTransaction()
orrollbackPreparedTransaction()
method can be used to resolve heuristic transactions. Heuristically completed transactions can be listed using thelistHeuristicCommittedTransactions()
andlistHeuristicRolledBackTransactions
methods. - Enabling and resetting Message counters
- Message counters can be enabled or disabled using the
enableMessageCounters()
ordisableMessageCounters()
method. To reset message counters, it is possible to invokeresetAllMessageCounters()
andresetAllMessageCounterHistories()
methods. - Retrieving the server configuration and attributes
- The
HornetQServerControl
exposes HornetQ server configuration through all its attributes (for example,getVersion()
method to retrieve the server's version, and so on.)
28.1.1.2. Core Address Management
Core addresses can be managed using the
AddressControl
class (with the ObjectName org.hornetq: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 with the queue with the getRoles()
method.
28.1.1.3. Core Queue Management
The bulk of the core management APIs deal 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 (for example, to remove a single message) or a filter (for example, 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 thesetExpiryAddress()
method.Messages can also be sent to a dead letter address with thesendMessagesToDeadLetterAddress()
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 thesetDeadLetterAddress()
method.Messages can also be moved from a queue to another queue by using themoveMessages()
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 theremoveMessages()
method which returns a boolean for the single message id variant or the number of removed messages for the filter variant. TheremoveMessages()
method takes a filter argument to remove only filtered messages. Setting the filter to an empty string will remove all messages. - Counting messages
- The number of messages in a queue is returned by the
getMessageCount()
method. Alternatively, thecountMessages()
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()
andlistMessageCounterHistory()
methods (see Section 28.6, “Message Counters”). The message counters can also be reset for a single queue using theresetMessageCounter()
method. - Retrieving the queue attributes
- The
QueueControl
exposes core queue settings through its attributes (for example,getFilter()
to retrieve the queue's filter if it was created with one,isDurable()
to know whether the queue is durable or not, and so on). - 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 is resumed, it will begin delivering the queued messages.
28.1.1.4. Other Core Resources Management
HornetQ allows the user to start and stop its remote resources (acceptors, diverts, bridges, and so on) so that a server can be taken offline without stopping it completely (for example, if other management operations must be performed such as resolving heuristic transactions). These resources are:
- Acceptors
- Acceptors can be started or stopped using the
start()
or.stop()
method on theAcceptorControl
class (with the ObjectNameorg.hornetq:module=Core,type=Acceptor,name="<the acceptor name>"
or the resource namecore.acceptor.<the address name>
). The parameters of the acceptors can be retrieved using theAcceptorControl
attributes (see Section 14.1, “Understanding Acceptors”) - Diverts
- Diverts can be started or stopped using the
start()
orstop()
method on theDivertControl
class (with the ObjectNameorg.hornetq:module=Core,type=Divert,name=<the divert name>
or the resource namecore.divert.<the divert name>
). Diverts parameters can be retrieved using theDivertControl
attributes (see Chapter 33, Diverting and Splitting Message Flows) - Bridges
- They can be started or stopped using the
start()
(resp.stop()
) method on theBridgeControl
class (with the ObjectNameorg.hornetq:module=Core,type=Bridge,name="<the bridge name>"
or the resource namecore.bridge.<the bridge name>
). Bridges parameters can be retrieved using theBridgeControl
attributes (see Chapter 34, Core Bridges) - Broadcast groups
- Broadcast groups can be started or stopped using the
start()
orstop()
method on theBroadcastGroupControl
class (with the ObjectNameorg.hornetq:module=Core,type=BroadcastGroup,name="<the broadcast group name>"
or the resource namecore.broadcastgroup.<the broadcast group name>
). Broadcast groups parameters can be retrieved using theBroadcastGroupControl
attributes (see Section 36.2.1, “Broadcast Groups”) - Discovery groups
- They can be started or stopped using the
start()
orstop()
method on theDiscoveryGroupControl
class (with the ObjectNameorg.hornetq:module=Core,type=DiscoveryGroup,name="<the discovery group name>"
or the resource namecore.discovery.<the discovery group name>
). Discovery groups parameters can be retrieved using theDiscoveryGroupControl
attributes (see Section 36.2.2, “Discovery Groups”) - Cluster connections
- They can be started or stopped using the
start()
orstop()
method on theClusterConnectionControl
class (with the ObjectNameorg.hornetq:module=Core,type=ClusterConnection,name="<the cluster connection name>"
or the resource namecore.clusterconnection.<the cluster connection name>
). Cluster connections parameters can be retrieved using theClusterConnectionControl
attributes (see Section 36.3.1, “Configuring Cluster Connections”)
28.1.2. JMS Management API
HornetQ defines a JMS Management API to manage JMS administrated objects (that is, JMS queues, topics and connection factories).
28.1.2.1. JMS Server Management
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
).
- 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 thecreateConnectionFactory()
methods ordestroyConnectionFactory()
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 (that is,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 firstkey
will be associated to the first transport configuration and the secondkey
will be associated to the second transport configuration (see Chapter 14, Configuring the Transport 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 thecreateQueue()
methods ordestroyQueue()
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 thecreateTopic()
ordestroyTopic()
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 thecloseConnectionsForAddress()
method.Alternatively, connection ids can be listed usinglistConnectionIDs()
and all the sessions for a given connection id can be listed usinglistSessions()
.
28.1.2.2. JMS ConnectionFactory Management
JMS Connection Factories can be managed using the
ConnectionFactoryControl
class (with the ObjectName org.hornetq: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 (that is,getConsumerWindowSize()
to retrieve the consumer window size for flow control,isBlockOnNonDurableSend()
to know whether the producers created from the connection factory will block when sending non-durable messages, and so on).
28.1.2.3. JMS Queue Management
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.
- 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 thesetExpiryAddress()
method.Messages can also be sent to a dead letter address with thesendMessagesToDeadLetterAddress()
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 thesetDeadLetterAddress()
method.Messages can also be moved from a queue to another queue by using themoveMessages()
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 theremoveMessages()
method which returns a boolean for the single message ID variant or the number of removed messages for the filter variant. TheremoveMessages()
method takes afilter
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, thecountMessages()
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()
andlistMessageCounterHistory()
methods (see Section 28.6, “Message Counters”) - Retrieving the queue attributes
- The
JMSQueueControl
exposes JMS queue settings through its attributes (for example,isTemporary()
to know whether the queue is temporary or not,isDurable()
to know whether the queue is durable or not, and so on.) - 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.
28.1.2.4. JMS Topic Management
JMS Topics can be managed using the
TopicControl
class (with the ObjectName org.hornetq: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, and so on). It is also possible to list the JMS messages for a given subscription with thelistMessagesForSubscription()
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 determine the number of messages held for a given subscription (with an optional message selector to determine the number of messages matching the selector).