[jboss-cvs] JBoss Messaging SVN: r6974 - trunk/docs/user-manual/en.
jboss-cvs-commits at lists.jboss.org
jboss-cvs-commits at lists.jboss.org
Fri May 22 01:41:23 EDT 2009
Author: ataylor
Date: 2009-05-22 01:41:22 -0400 (Fri, 22 May 2009)
New Revision: 6974
Modified:
trunk/docs/user-manual/en/management.xml
Log:
more proof reading updates
Modified: trunk/docs/user-manual/en/management.xml
===================================================================
--- trunk/docs/user-manual/en/management.xml 2009-05-22 05:34:00 UTC (rev 6973)
+++ trunk/docs/user-manual/en/management.xml 2009-05-22 05:41:22 UTC (rev 6974)
@@ -1,369 +1,443 @@
<?xml version="1.0" encoding="UTF-8"?>
<chapter id="management">
<title>Management</title>
-
- <para>While JBoss Messaging servers are up and running, it is possible to interact with it
- to modify its settings, 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 to
- <emphasis>manage</emphasis> JBoss Messaging.</para>
- <para>There are 3 ways to manage JBoss Messaging:</para>
- <itemizedlist>
- <listitem><para>Using JMX -- JMX is the standard way to manage Java applications</para></listitem>
- <listitem><para>Using Core API -- management operations are sent to JBoss Messaging server
- using <emphasis>Core messages</emphasis></para></listitem>
- <listitem><para>Using JMS API -- management operations are sent to JBoss Messaging server
- using <emphasis>JMS messages</emphasis></para></listitem>
- </itemizedlist>
- <para>There are 3 ways to manage JBoss Messaging but they all allow the same set of operations.
- 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.</para>
- <para>This choice depends on your requirements, your application settings and your environment to
- decide which way suits you best.</para>
-
+ <para>JBoss Messaging has a 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 <emphasis>manage</emphasis> JBoss
+ Messaging.</para>
+ <para>There are 3 ways to manage JBoss Messaging:</para>
+ <itemizedlist>
+ <listitem>
+ <para>Using JMX -- JMX is the standard way to manage Java applications</para>
+ </listitem>
+ <listitem>
+ <para>Using Core API -- management operations are sent to JBoss Messaging server using
+ <emphasis>Core messages</emphasis></para>
+ </listitem>
+ <listitem>
+ <para>Using JMS API -- management operations are sent to JBoss Messaging server using
+ <emphasis>JMS messages</emphasis></para>
+ </listitem>
+ </itemizedlist>
+ <para>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.</para>
+ <para>This choice depends on your requirements, your application settings and your environment to
+ decide which way suits you best.</para>
<section>
<title>The Management API</title>
- <para>Regardless of the way you <emphasis>invoke</emphasis> management operations, the management API
- is the same.</para>
+ <para>Regardless of the way you <emphasis>invoke</emphasis> management operations, the
+ management API is the same.</para>
<para>For each <emphasis>managed resource</emphasis>, there exists a Java interface describing
- what can be invoked for this type of resource.</para>
+ what can be invoked for this type of resource.</para>
<para>JBoss Messaging exposes its managed resources in 2 packages:</para>
<itemizedlist>
- <listitem><para><emphasis>Core</emphasis> resources are located in the
- <literal>org.jboss.messaging.core.management</literal> package</para></listitem>
- <listitem><para><emphasis>JMS</emphasis> resources are located in the
- <literal>org.jboss.messaging.jms.server.management</literal> package</para></listitem>
+ <listitem>
+ <para><emphasis>Core</emphasis> resources are located in the <literal
+ >org.jboss.messaging.core.management</literal> package</para>
+ </listitem>
+ <listitem>
+ <para><emphasis>JMS</emphasis> resources are located in the <literal
+ >org.jboss.messaging.jms.server.management</literal> package</para>
+ </listitem>
</itemizedlist>
- <para>The way to invoke a <emphasis>management operations</emphasis> depends wether JMX, Core messages, or JMS Messages are used.</para>
-
+ <para>The way to invoke a <emphasis>management operations</emphasis> depends whether JMX, Core
+ messages, or JMS Messages are used.</para>
<section>
<title>Core Management API</title>
<para>JBoss Messaging defines a Core Management API to manage Core resources.</para>
-
<section>
<title>Core Server Management</title>
-
<itemizedlist>
<listitem>
<para>Creating and destroying queues</para>
<para>Core queues can be created (resp. destroyed) using the management operations
- <literal>createQueue()</literal> or <literal>deployQueue()</literal> (resp. <literal>destroyQueue()</literal>)
- on the <literal>MessagingServerControlMBean</literal> (with the ObjectName <literal>org.jboss.messaging:module=Core,type=Server</literal>
- or the resource name <literal>core.server</literal>)</para>
- <para><literal>deployQueue</literal> will fail if the queue already exists while <literal>createQueue</literal> will do nothing.</para>
+ <literal>createQueue()</literal> or <literal>deployQueue()</literal> (resp.
+ <literal>destroyQueue()</literal>) on the <literal
+ >MessagingServerControlMBean</literal> (with the ObjectName <literal
+ >org.jboss.messaging:module=Core,type=Server</literal> or the resource name
+ <literal>core.server</literal>)</para>
+ <para><literal>deployQueue</literal> will fail if the queue already exists while
+ <literal>createQueue</literal> will do nothing.</para>
</listitem>
<listitem>
<para>Listing and closing remote connections</para>
- <para>Client's remote addresses can be retrieved using <literal>listRemoteAddresses()</literal>. It is also possible
- to close the connections associated with a remote address using the <literal>closeConnectionsForAddress()</literal> method.</para>
- <para>Alternatively, connection IDs can be listed using <literal>listConnectionIDs()</literal> and all the
- sessions for a given connection ID can be listed using <literal>listSessions()</literal>.</para>
+ <para>Client's remote addresses can be retrieved using <literal
+ >listRemoteAddresses()</literal>. It is also possible to close the
+ connections associated with a remote address using the <literal
+ >closeConnectionsForAddress()</literal> method.</para>
+ <para>Alternatively, connection IDs can be listed using <literal
+ >listConnectionIDs()</literal> and all the sessions for a given connection
+ ID can be listed using <literal>listSessions()</literal>.</para>
</listitem>
<listitem>
<para>Transaction heuristic operations</para>
- <para>In case of a server crash, when the server restarts, it it possible that some transaction
- requires an manual intervention. The <literal>listPreparedTransactions()</literal> method
- lists the transactions which are in the prepared states (the transactions are represented as opaque
- Base64 Strings.) To commit (resp. rollback) a given prepared transaction,
- the <literal>commitPreparedTransaction</literal>() (resp. <literal>rollbackPreparedTransaction()</literal>)
- method can be used to resolve heuristic transactions.</para>
+ <para>In case of a server crash, when the server restarts, it it possible that
+ some transaction requires an manual intervention. The <literal
+ >listPreparedTransactions()</literal> method lists the transactions which
+ are in the prepared states (the transactions are represented as opaque Base64
+ Strings.) To commit (resp. rollback) a given prepared transaction, the <literal
+ >commitPreparedTransaction</literal>() (resp. <literal
+ >rollbackPreparedTransaction()</literal>) method can be used to resolve
+ heuristic transactions.</para>
</listitem>
<listitem>
<para>Enabling and resetting Message counters</para>
- <para>Message counters can be enabled (resp. disabled) using the <literal>enableMessageCounters()</literal>
- (resp. <literal>disableMessageCounters()</literal>) method. To reset message counters, it is possible to invoke
- <literal>resetAllMessageCounters()</literal> and <literal>resetAllMessageCounterHistories()</literal> methods.</para>
+ <para>Message counters can be enabled (resp. disabled) using the <literal
+ >enableMessageCounters()</literal> (resp. <literal
+ >disableMessageCounters()</literal>) method. To reset message counters, it
+ is possible to invoke <literal>resetAllMessageCounters()</literal> and <literal
+ >resetAllMessageCounterHistories()</literal> methods.</para>
</listitem>
<listitem>
<para>Retrieving the server configuration and attributes</para>
- <para>The <literal>MessagingServerControlMBean</literal> exposes JBoss Messaging server configuration
- through all its attributes (e.g. <literal>getVersion()</literal> method to retrieve the server's version, etc.)</para>
+ <para>The <literal>MessagingServerControlMBean</literal> exposes JBoss Messaging
+ server configuration through all its attributes (e.g. <literal
+ >getVersion()</literal> method to retrieve the server's version,
+ etc.)</para>
</listitem>
</itemizedlist>
</section>
-
<section>
<title>Core Address Management</title>
- <para><para>Core addresses can be managed using the
- <literal>AddressControlMBean</literal> class (with the ObjectName <literal>org.jboss.messaging:module=Core,type=Address,name="<the address name>"</literal>
- or the resource name <literal>core.address.<the address name></literal>).</para>
- </para>
-
+ <para>Core addresses can be managed using the <literal>AddressControlMBean</literal>
+ class (with the ObjectName <literal
+ >org.jboss.messaging:module=Core,type=Address,name="<the address
+ name>"</literal> or the resource name <literal>core.address.<the address
+ name></literal>). </para>
<itemizedlist>
<listitem>
<para>Modifying roles and permissions for an address</para>
- <para>You can add (resp. remove) roles associated to a queue using the
- <literal>addRole()</literal> (resp. <literal>removeRole()</literal>) method.
- You can list all the roles
- associated to the queue with the <literal>getRoles()</literal> method</para>
- </listitem>
+ <para>You can add (resp. remove) roles associated to a queue using the <literal
+ >addRole()</literal> (resp. <literal>removeRole()</literal>) method. You can
+ list all the roles associated to the queue with the <literal
+ >getRoles()</literal> method</para>
+ </listitem>
</itemizedlist>
</section>
-
<section>
<title>Core Queue Management</title>
-
- <para>The bulk of the Core management API deals with Core queues. The <literal>QueueControlMBean</literal> class
- defines the Core queue management operations (with the ObjectName <literal>org.jboss.messaging:module=Core,type=Queue,address="<the bound address>",name="<the queue name>"</literal>
- or the resource name <literal>core.queue.<the queue name></literal>).</para>
- <para>Most of the management operations on the queues
- takes 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.)</para>
-
+ <para>The bulk of the Core management API deals with Core queues. The <literal
+ >QueueControlMBean</literal> class defines the Core queue management operations
+ (with the ObjectName <literal
+ >org.jboss.messaging:module=Core,type=Queue,address="<the bound
+ address>",name="<the queue name>"</literal> or the resource name <literal
+ >core.queue.<the queue name></literal>).</para>
+ <para>Most of the management operations on the queues takes 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.)</para>
<itemizedlist>
<listitem>
<para>Expiring, sending to a dead letter address and moving messages</para>
- <para>Messages can be expired from a queue by using the <literal>expireMessages()</literal> 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 <literal>setExpiryAddress()</literal> method.</para>
- <para>Messages can also be sent to a dead letter address with the <literal>sendMessagesToDeadLetterAddress()</literal> 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 <literal>setDeadLetterAddress()</literal> method.</para>
- <para>Messages can also be moved from a queue to another queue by using the <literal>moveMatchingMessages()</literal> method.</para>
+ <para>Messages can be expired from a queue by using the <literal
+ >expireMessages()</literal> 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 <literal>setExpiryAddress()</literal>
+ method.</para>
+ <para>Messages can also be sent to a dead letter address with the <literal
+ >sendMessagesToDeadLetterAddress()</literal> 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 <literal
+ >setDeadLetterAddress()</literal> method.</para>
+ <para>Messages can also be moved from a queue to another queue by using the
+ <literal>moveMatchingMessages()</literal> method.</para>
</listitem>
<listitem>
<para>Listing and removing messages</para>
- <para>Messages can be listed from a queue by using the <literal>listMessages()</literal> method which
- returns an array of <literal>Map</literal>, one <literal>Map</literal> for each message.</para>
- <para>Messages can also be removed from the queue by using the <literal>removeMatchingMessages()</literal> method
- which returns a <literal>boolean</literal> for the single message ID variant or the number of removed
- messages for the filter variant.</para>
+ <para>Messages can be listed from a queue by using the <literal
+ >listMessages()</literal> method which returns an array of <literal
+ >Map</literal>, one <literal>Map</literal> for each message.</para>
+ <para>Messages can also be removed from the queue by using the <literal
+ >removeMatchingMessages()</literal> method which returns a <literal
+ >boolean</literal> for the single message ID variant or the number of
+ removed messages for the filter variant.</para>
</listitem>
<listitem>
<para>Counting messages</para>
- <para>The number of messages in a queue is returned by the <literal>getMessageCount()</literal> method.
- Alternatively, the <literal>countMessages()</literal> will return the number of messages in the queue
+ <para>The number of messages in a queue is returned by the <literal
+ >getMessageCount()</literal> method. Alternatively, the <literal
+ >countMessages()</literal> will return the number of messages in the queue
which <emphasis>match a given filter</emphasis></para>
</listitem>
<listitem>
<para>Changing message priority</para>
- <para>The message priority can be changed by using the <literal>changeMessagesPriority()</literal> method
- which returns a <literal>boolean</literal> for the single message ID variant or the number of updated
- messages for the filter variant.</para>
+ <para>The message priority can be changed by using the <literal
+ >changeMessagesPriority()</literal> method which returns a <literal
+ >boolean</literal> for the single message ID variant or the number of
+ updated messages for the filter variant.</para>
</listitem>
<listitem>
<para>Message counters</para>
- <para>Message counters can be listed for a queue with the <literal>listMessageCounter()</literal>
- and <literal>listMessageCounterHistory()</literal> methods (see <xref linkend="management.message-counters" />).
- The message counters can also be reset for a single queue using the <literal>resetMessageCounter()</literal>
+ <para>Message counters can be listed for a queue with the <literal
+ >listMessageCounter()</literal> and <literal
+ >listMessageCounterHistory()</literal> methods (see <xref
+ linkend="management.message-counters"/>). The message counters can also be
+ reset for a single queue using the <literal>resetMessageCounter()</literal>
method.</para>
</listitem>
<listitem>
<para>Retrieving the queue attributes</para>
- <para>The <literal>QueueControlMBean</literal> exposes Core queue settings
- through its attributes (e.g. <literal>getFilter()</literal> to retrieve the queue's filter
- if it was created with one, <literal>isDurable()</literal> to know wether the queue is durable or not, etc.)</para>
- </listitem>
+ <para>The <literal>QueueControlMBean</literal> exposes Core queue settings through
+ its attributes (e.g. <literal>getFilter()</literal> to retrieve the queue's
+ filter if it was created with one, <literal>isDurable()</literal> to know
+ wether the queue is durable or not, etc.)</para>
+ </listitem>
</itemizedlist>
</section>
-
<section>
<title>Other Core Resources Management</title>
-
- <para>JBoss Messaging allow to start and stop its remote resources (acceptors, diverts, bridges, etc.)
- so that a server can be made 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:</para>
-
+ <para>JBoss Messaging allow to start and stop its remote resources (acceptors, diverts,
+ bridges, etc.) so that a server can be made 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:</para>
<itemizedlist>
<listitem>
<para>Acceptors</para>
- <para>They can be started (resp. stopped) using the <literal>start()</literal> (resp. <literal>stop()</literal>) method
- on the <literal>AcceptorControlMBean</literal> class (with the ObjectName <literal>org.jboss.messaging:module=Core,type=Acceptor,name="<the acceptor name>"</literal>
- or the resource name <literal>core.acceptor.<the address name></literal>). Acceptor's parameters can be retrieved
- using the <literal>AcceptorControlMBean</literal> attributes (see <xref linkend="configuring-transports.acceptors" />)</para>
+ <para>They can be started (resp. stopped) using the <literal>start()</literal>
+ (resp. <literal>stop()</literal>) method on the <literal
+ >AcceptorControlMBean</literal> class (with the ObjectName <literal
+ >org.jboss.messaging:module=Core,type=Acceptor,name="<the acceptor
+ name>"</literal> or the resource name <literal>core.acceptor.<the
+ address name></literal>). Acceptor's parameters can be retrieved using
+ the <literal>AcceptorControlMBean</literal> attributes (see <xref
+ linkend="configuring-transports.acceptors"/>)</para>
</listitem>
<listitem>
<para>Diverts</para>
- <para>They can be started (resp. stopped) using the <literal>start()</literal> (resp. <literal>stop()</literal>) method
- on the <literal>DivertControlMBean</literal> class (with the ObjectName <literal>org.jboss.messaging:module=Core,type=Divert,name=<the divert name></literal>
- or the resource name <literal>core.divert.<the divert name></literal>). Divert's parameters can be retrieved
- using the <literal>DivertControlMBean</literal> attributes (see <xref linkend="diverts" />)</para>
+ <para>They can be started (resp. stopped) using the <literal>start()</literal>
+ (resp. <literal>stop()</literal>) method on the <literal
+ >DivertControlMBean</literal> class (with the ObjectName <literal
+ >org.jboss.messaging:module=Core,type=Divert,name=<the divert
+ name></literal> or the resource name <literal>core.divert.<the divert
+ name></literal>). Divert's parameters can be retrieved using the <literal
+ >DivertControlMBean</literal> attributes (see <xref linkend="diverts"
+ />)</para>
</listitem>
<listitem>
<para>Bridges</para>
- <para>They can be started (resp. stopped) using the <literal>start()</literal> (resp. <literal>stop()</literal>) method
- on the <literal>BridgeControlMBean</literal> class (with the ObjectName <literal>org.jboss.messaging:module=Core,type=Bridge,name="<the bridge name>"</literal>
- or the resource name <literal>core.bridge.<the bridge name></literal>). Bridge's parameters can be retrieved
- using the <literal>BridgeControlMBean</literal> attributes (see <xref linkend="core-bridges" />)</para>
+ <para>They can be started (resp. stopped) using the <literal>start()</literal>
+ (resp. <literal>stop()</literal>) method on the <literal
+ >BridgeControlMBean</literal> class (with the ObjectName <literal
+ >org.jboss.messaging:module=Core,type=Bridge,name="<the bridge
+ name>"</literal> or the resource name <literal>core.bridge.<the bridge
+ name></literal>). Bridge's parameters can be retrieved using the <literal
+ >BridgeControlMBean</literal> attributes (see <xref linkend="core-bridges"
+ />)</para>
</listitem>
<listitem>
<para>Broadcast groups</para>
- <para>They can be started (resp. stopped) using the <literal>start()</literal> (resp. <literal>stop()</literal>) method
- on the <literal>BroadcastGroupControlMBean</literal> class (with the ObjectName <literal>org.jboss.messaging:module=Core,type=BroadcastGroup,name="<the broadcast group name>"</literal>
- or the resource name <literal>core.broadcastgroup.<the broadcast group name></literal>). Broadcast group's parameters can be retrieved
- using the <literal>BroadcastGroupControlMBean</literal> attributes (see <xref linkend="clusters.broadcast-groups" />)</para>
+ <para>They can be started (resp. stopped) using the <literal>start()</literal>
+ (resp. <literal>stop()</literal>) method on the <literal
+ >BroadcastGroupControlMBean</literal> class (with the ObjectName <literal
+ >org.jboss.messaging:module=Core,type=BroadcastGroup,name="<the broadcast
+ group name>"</literal> or the resource name <literal
+ >core.broadcastgroup.<the broadcast group name></literal>). Broadcast
+ group's parameters can be retrieved using the <literal
+ >BroadcastGroupControlMBean</literal> attributes (see <xref
+ linkend="clusters.broadcast-groups"/>)</para>
</listitem>
<listitem>
<para>Discovery groups</para>
- <para>They can be started (resp. stopped) using the <literal>start()</literal> (resp. <literal>stop()</literal>) method
- on the <literal>DiscoveryGroupControlMBean</literal> class (with the ObjectName <literal>org.jboss.messaging:module=Core,type=DiscoveryGroup,name="<the discovery group name>"</literal>
- or the resource name <literal>core.discovery.<the discovery group name></literal>). Discovery group's parameters can be retrieved
- using the <literal>DiscoveryGroupControlMBean</literal> attributes (see <xref linkend="clusters.discovery-groups" />)</para>
+ <para>They can be started (resp. stopped) using the <literal>start()</literal>
+ (resp. <literal>stop()</literal>) method on the <literal
+ >DiscoveryGroupControlMBean</literal> class (with the ObjectName <literal
+ >org.jboss.messaging:module=Core,type=DiscoveryGroup,name="<the discovery
+ group name>"</literal> or the resource name <literal
+ >core.discovery.<the discovery group name></literal>). Discovery
+ group's parameters can be retrieved using the <literal
+ >DiscoveryGroupControlMBean</literal> attributes (see <xref
+ linkend="clusters.discovery-groups"/>)</para>
</listitem>
<listitem>
<para>Cluster connections</para>
- <para>They can be started (resp. stopped) using the <literal>start()</literal> (resp. <literal>stop()</literal>) method
- on the <literal>ClusterConnectionControlMBean</literal> class (with the ObjectName <literal>org.jboss.messaging:module=Core,type=ClusterConnection,name="<the cluster connection name>"</literal>
- or the resource name <literal>core.clusterconnection.<the cluster connection name></literal>). Cluster connection's parameters can be retrieved
- using the <literal>ClusterConnectionControlMBean</literal> attributes (see <xref linkend="clusters.cluster-connections" />)</para>
+ <para>They can be started (resp. stopped) using the <literal>start()</literal>
+ (resp. <literal>stop()</literal>) method on the <literal
+ >ClusterConnectionControlMBean</literal> class (with the ObjectName <literal
+ >org.jboss.messaging:module=Core,type=ClusterConnection,name="<the
+ cluster connection name>"</literal> or the resource name <literal
+ >core.clusterconnection.<the cluster connection name></literal>).
+ Cluster connection's parameters can be retrieved using the <literal
+ >ClusterConnectionControlMBean</literal> attributes (see <xref
+ linkend="clusters.cluster-connections"/>)</para>
</listitem>
</itemizedlist>
- </section>
+ </section>
</section>
-
<section>
<title>JMS Management API</title>
- <para>JBoss Messaging defines a JMS Management API to manage JMS <emphasis>administrated objects</emphasis>.</para>
-
+ <para>JBoss Messaging defines a JMS Management API to manage JMS <emphasis>administrated
+ objects</emphasis>.</para>
<section>
<title>JMS Server Management</title>
- <para>JMS Resources (connection factories and destinations) can be created using the
- <literal>JMSServerControlMBean</literal> class (with the ObjectName <literal>org.jboss.messaging:module=JMS,type=Server</literal>
- or the resource name <literal>jms.server</literal>).</para>
-
+ <para>JMS Resources (connection factories and destinations) can be created using the
+ <literal>JMSServerControlMBean</literal> class (with the ObjectName <literal
+ >org.jboss.messaging:module=JMS,type=Server</literal> or the resource name
+ <literal>jms.server</literal>).</para>
<itemizedlist>
<listitem>
<para>Creating/destroying connection factories</para>
- <para>JMS connection factories can be created (resp. destroyed) using the <literal>createConnectionFactory()</literal>
- methods (resp. <literal>destroyConnectionFactory()</literal>) methods.
- These connection factories are bound to JNDI so that JMS clients can look them up</para>
- </listitem>
+ <para>JMS connection factories can be created (resp. destroyed) using the <literal
+ >createConnectionFactory()</literal> methods (resp. <literal
+ >destroyConnectionFactory()</literal>) methods. These connection factories
+ are bound to JNDI so that JMS clients can look them up</para>
+ </listitem>
<listitem>
<para>Creating/destroying queues</para>
- <para>JMS queues can be created (resp. destroyed) using the <literal>createQueue()</literal>
- methods (resp. <literal>destroyQueue()</literal>) methods.
- These queues are bound to JNDI so that JMS clients can look them up</para>
- </listitem>
+ <para>JMS queues can be created (resp. destroyed) using the <literal
+ >createQueue()</literal> methods (resp. <literal>destroyQueue()</literal>)
+ methods. These queues are bound to JNDI so that JMS clients can look them
+ up</para>
+ </listitem>
<listitem>
<para>Creating/destroying topics</para>
- <para>JMS topics can be created (resp. destroyed) using the <literal>createTopic()</literal>
- methods (resp. <literal>destroyTopic()</literal>) methods.
- These topics are bound to JNDI so that JMS clients can look them up</para>
- </listitem>
+ <para>JMS topics can be created (resp. destroyed) using the <literal
+ >createTopic()</literal> methods (resp. <literal>destroyTopic()</literal>)
+ methods. These topics are bound to JNDI so that JMS clients can look them
+ up</para>
+ </listitem>
<listitem>
<para>Listing and closing remote connections</para>
- <para>JMS Client's remote addresses can be retrieved using <literal>listRemoteAddresses()</literal>. It is also possible
- to close the connections associated with a remote address using the <literal>closeConnectionsForAddress()</literal> method.</para>
- <para>Alternatively, connection IDs can be listed using <literal>listConnectionIDs()</literal> and all the
- sessions for a given connection ID can be listed using <literal>listSessions()</literal>.</para>
- </listitem>
+ <para>JMS Client's remote addresses can be retrieved using <literal
+ >listRemoteAddresses()</literal>. It is also possible to close the
+ connections associated with a remote address using the <literal
+ >closeConnectionsForAddress()</literal> method.</para>
+ <para>Alternatively, connection IDs can be listed using <literal
+ >listConnectionIDs()</literal> and all the sessions for a given connection
+ ID can be listed using <literal>listSessions()</literal>.</para>
+ </listitem>
</itemizedlist>
</section>
-
<section>
<title>JMS ConnectionFactory Management</title>
-
- <para>JMS Connection Factories can be managed using the
- <literal>ConnectionFactoryControlMBean</literal> class (with the ObjectName <literal>org.jboss.messaging:module=JMS,type=ConnectionFactory,name="<the connection factory name>"</literal>
- or the resource name <literal>jms.connectionfactory.<the connection factory name></literal>).</para>
-
+ <para>JMS Connection Factories can be managed using the <literal
+ >ConnectionFactoryControlMBean</literal> class (with the ObjectName <literal
+ >org.jboss.messaging:module=JMS,type=ConnectionFactory,name="<the connection
+ factory name>"</literal> or the resource name <literal
+ >jms.connectionfactory.<the connection factory name></literal>).</para>
<itemizedlist>
<listitem>
<para>Retrieving connection factory attributes</para>
- <para>The <literal>ConnectionFactoryControlMBean</literal> exposes JMS ConnectionFactory
- configuration through its attributes (e.g. <literal>getConsumerWindowSize()</literal> to retrieve the
- consumer window size for flow control, <literal>isBlockOnNonPersistentSend()</literal> to know wether the
- producers created from the connection factory will block or not when sending non-persistent messages, etc.)</para>
- </listitem>
+ <para>The <literal>ConnectionFactoryControlMBean</literal> exposes JMS
+ ConnectionFactory configuration through its attributes (e.g. <literal
+ >getConsumerWindowSize()</literal> to retrieve the consumer window size for
+ flow control, <literal>isBlockOnNonPersistentSend()</literal> to know wether
+ the producers created from the connection factory will block or not when
+ sending non-persistent messages, etc.)</para>
+ </listitem>
</itemizedlist>
</section>
-
<section>
<title>JMS Queue Management</title>
-
- <para>JMS Queues can be managed using the
- <literal>JMSQueueControlMBean</literal> class (with the ObjectName <literal>org.jboss.messaging:module=JMS,type=Queue,name="<the queue name>"</literal>
- or the resource name <literal>jms.queue.<the queue name></literal>).</para>
- <literal>The management operations on a JMS queue are very similar to the operations on a Core queue.</literal>
-
+ <para>JMS Queues can be managed using the <literal>JMSQueueControlMBean</literal> class
+ (with the ObjectName <literal>org.jboss.messaging:module=JMS,type=Queue,name="<the
+ queue name>"</literal> or the resource name <literal>jms.queue.<the queue
+ name></literal>). </para>
+ <para>
+ <literal>The management operations on a JMS queue are very similar to the operations
+ on a Core queue.</literal>
+ </para>
<itemizedlist>
<listitem>
<para>Expiring, sending to a dead letter address and moving messages</para>
- <para>Messages can be expired from a queue by using the <literal>expireMessages()</literal> 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 <literal>setExpiryAddress()</literal> method.</para>
- <para>Messages can also be sent to a dead letter address with the <literal>sendMessagesToDeadLetterAddress()</literal> 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 <literal>setDeadLetterAddress()</literal> method.</para>
- <para>Messages can also be moved from a queue to another queue by using the <literal>moveMatchingMessages()</literal> method.</para>
+ <para>Messages can be expired from a queue by using the <literal
+ >expireMessages()</literal> 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 <literal>setExpiryAddress()</literal>
+ method.</para>
+ <para>Messages can also be sent to a dead letter address with the <literal
+ >sendMessagesToDeadLetterAddress()</literal> 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 <literal
+ >setDeadLetterAddress()</literal> method.</para>
+ <para>Messages can also be moved from a queue to another queue by using the
+ <literal>moveMatchingMessages()</literal> method.</para>
</listitem>
<listitem>
<para>Listing and removing messages</para>
- <para>Messages can be listed from a queue by using the <literal>listMessages()</literal> method which
- returns an array of <literal>Map</literal>, one <literal>Map</literal> for each message.</para>
- <para>Messages can also be removed from the queue by using the <literal>removeMatchingMessages()</literal> method
- which returns a <literal>boolean</literal> for the single message ID variant or the number of removed
- messages for the filter variant.</para>
+ <para>Messages can be listed from a queue by using the <literal
+ >listMessages()</literal> method which returns an array of <literal
+ >Map</literal>, one <literal>Map</literal> for each message.</para>
+ <para>Messages can also be removed from the queue by using the <literal
+ >removeMatchingMessages()</literal> method which returns a <literal
+ >boolean</literal> for the single message ID variant or the number of
+ removed messages for the filter variant.</para>
</listitem>
<listitem>
<para>Counting messages</para>
- <para>The number of messages in a queue is returned by the <literal>getMessageCount()</literal> method.
- Alternatively, the <literal>countMessages()</literal> will return the number of messages in the queue
+ <para>The number of messages in a queue is returned by the <literal
+ >getMessageCount()</literal> method. Alternatively, the <literal
+ >countMessages()</literal> will return the number of messages in the queue
which <emphasis>match a given filter</emphasis></para>
</listitem>
<listitem>
<para>Changing message priority</para>
- <para>The message priority can be changed by using the <literal>changeMessagesPriority()</literal> method
- which returns a <literal>boolean</literal> for the single message ID variant or the number of updated
- messages for the filter variant.</para>
+ <para>The message priority can be changed by using the <literal
+ >changeMessagesPriority()</literal> method which returns a <literal
+ >boolean</literal> for the single message ID variant or the number of
+ updated messages for the filter variant.</para>
</listitem>
<listitem>
<para>Message counters</para>
- <para>Message counters can be listed for a queue with the <literal>listMessageCounter()</literal>
- and <literal>listMessageCounterHistory()</literal> methods (see <xref linkend="management.message-counters" />)</para>
+ <para>Message counters can be listed for a queue with the <literal
+ >listMessageCounter()</literal> and <literal
+ >listMessageCounterHistory()</literal> methods (see <xref
+ linkend="management.message-counters"/>)</para>
</listitem>
<listitem>
<para>Retrieving the queue attributes</para>
<para>The <literal>JMSQueueControlMBean</literal> exposes JMS queue settings
- through its attributes (e.g. <literal>isTemporary()</literal> to know wether the queue is temporary or not,
- <literal>isDurable()</literal> to know wether the queue is durable or not, etc.)</para>
- </listitem>
+ through its attributes (e.g. <literal>isTemporary()</literal> to know wether
+ the queue is temporary or not, <literal>isDurable()</literal> to know wether
+ the queue is durable or not, etc.)</para>
+ </listitem>
</itemizedlist>
</section>
-
<section>
- <title>JMS Topic Management</title>
-
- <para>JMS Topics can be managed using the
- <literal>TopicControlMBean</literal> class (with the ObjectName <literal>org.jboss.messaging:module=JMS,type=Topic,name="<the topic name>"</literal>
- or the resource name <literal>jms.topic.<the topic name></literal>).</para>
-
+ <title>JMS Topic Management</title>
+ <para>JMS Topics can be managed using the <literal>TopicControlMBean</literal> class
+ (with the ObjectName <literal>org.jboss.messaging:module=JMS,type=Topic,name="<the
+ topic name>"</literal> or the resource name <literal>jms.topic.<the topic
+ name></literal>).</para>
<itemizedlist>
<listitem>
<para>Listing subscriptions and messages</para>
- <para>JMS topic's subscriptions can be listed using the <literal>listAllSubscriptions()</literal>,
- <literal>listDurableSubscriptions()</literal>, <literal>listNonDurableSubscriptions()</literal> methods.
- These methods return arrays of <literal>Object</literal> 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 <literal>listMessagesForSubscription()</literal> method.</para>
+ <para>JMS topic's subscriptions can be listed using the <literal
+ >listAllSubscriptions()</literal>, <literal
+ >listDurableSubscriptions()</literal>, <literal
+ >listNonDurableSubscriptions()</literal> methods. These methods return
+ arrays of <literal>Object</literal> 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 <literal
+ >listMessagesForSubscription()</literal> method.</para>
</listitem>
<listitem>
<para>Dropping subscriptions</para>
- <para>Durable subscriptions can be dropped from the topic using the <literal>dropDurableSubscription()</literal> method.</para>
- </listitem>
+ <para>Durable subscriptions can be dropped from the topic using the <literal
+ >dropDurableSubscription()</literal> method.</para>
+ </listitem>
<listitem>
<para>Counting subscription's messages</para>
- <para>The <literal>countMessagesForSubscription()</literal> 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)</para>
- </listitem>
+ <para>The <literal>countMessagesForSubscription()</literal> 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)</para>
+ </listitem>
</itemizedlist>
</section>
</section>
-
</section>
-
<section id="management.jmx">
<title>Using Management Via JMX</title>
- <para>JBoss Messaging can be managed using
- <ulink url="http://java.sun.com/javase/technologies/core/mntr-mgmt/javamanagement/">JMX</ulink>.
- </para>
+ <para>JBoss Messaging can be managed using <ulink
+ url="http://java.sun.com/javase/technologies/core/mntr-mgmt/javamanagement/"
+ >JMX</ulink>. </para>
<para>The management API is exposed by JBoss Messaging using MBeans interfaces. JBoss
- Messaging registers its resources with the domain <literal>org.jboss.messaging</literal>.</para>
- <para>For example, the <literal>ObjectName</literal> to manage a JMS Queue <literal>exampleQueue</literal> is:</para>
+ Messaging registers its resources with the domain <literal
+ >org.jboss.messaging</literal>.</para>
+ <para>For example, the <literal>ObjectName</literal> to manage a JMS Queue <literal
+ >exampleQueue</literal> is:</para>
<programlisting>
org.jboss.messaging:module=JMS,type=Queue,name="exampleQueue"
</programlisting>
@@ -371,33 +445,32 @@
<programlisting>
org.jboss.messaging.jms.server.management.JMSQueueControlMBean
</programlisting>
-
- <para>The MBean's <literal>ObjectName</literal> are built using the helper class
- <literal>org.jboss.messaging.core.management.ObjectNames</literal>. You can also use
- <literal>jconsole</literal> to find the <literal>ObjectName</literal> of the MBeans you want to manage.
- </para>
-
+ <para>The MBean's <literal>ObjectName</literal> are built using the helper class <literal
+ >org.jboss.messaging.core.management.ObjectNames</literal>. You can also use <literal
+ >jconsole</literal> to find the <literal>ObjectName</literal> of the MBeans you want to
+ manage. </para>
<para>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.</para>
-
<section id="management.jmx.configuration">
<title>Configuring JMX</title>
- <para>By default, JMX is enabled to manage JBoss Messaging. It can be disabled by
- setting <literal>jmx-management-enabled</literal> to <literal>false</literal> in <literal>jbm-configuration.xml</literal>:</para>
+ <para>By default, JMX is enabled to manage JBoss Messaging. It can be disabled by setting
+ <literal>jmx-management-enabled</literal> to <literal>false</literal> in <literal
+ >jbm-configuration.xml</literal>:</para>
<programlisting>
<!-- false to disable JMX management for JBoss Messaging -->
<jmx-management-enabled>false</jmx-management-enabled>
</programlisting>
-
- <para>If JMX is enabled, JBoss Messaging can be managed locally using <literal>jconsole</literal>.
- Remote connections to JMX are not enabled by default for security reasons. Please refer to
- <ulink url="http://java.sun.com/j2se/1.5.0/docs/guide/management/agent.html#remote">Java Management guide</ulink>
- to configure the server for remote management (system properties must be set in <literal>run.sh</literal>
- or <literal>run.bat</literal> scripts).</para>
-
- <para>By default, JBoss Messaging uses the Java Virtual Machine's <literal>Platform MBeanServer</literal>
- to register its MBeans. This is configured in JBoss Microcontainer Beans file
- (see <xref linkend="server.microcontainer.configuration" />):</para>
+ <para>If JMX is enabled, JBoss Messaging can be managed locally using <literal
+ >jconsole</literal>. Remote connections to JMX are not enabled by default for
+ security reasons. Please refer to <ulink
+ url="http://java.sun.com/j2se/1.5.0/docs/guide/management/agent.html#remote">Java
+ Management guide</ulink> to configure the server for remote management (system
+ properties must be set in <literal>run.sh</literal> or <literal>run.bat</literal>
+ scripts).</para>
+ <para>By default, JBoss Messaging uses the Java Virtual Machine's <literal>Platform
+ MBeanServer</literal> to register its MBeans. This is configured in JBoss
+ Microcontainer Beans file (see <xref linkend="server.microcontainer.configuration"
+ />):</para>
<programlisting>
<!-- MBeanServer -->
<bean name="MBeanServer" class="javax.management.MBeanServer">
@@ -406,50 +479,66 @@
</bean>
</programlisting>
</section>
-
<section>
<title>Example</title>
- <para>The <ulink url="../../../../examples/jms/jmx/readme.html"><literal>jmx</literal> example</ulink> shows
- how to use a remote connection to JMX and MBean proxies to manage JBoss Messaging.</para>
- </section>
+ <para>The <ulink url="../../../../examples/jms/jmx/readme.html"><literal>jmx</literal>
+ example</ulink> shows how to use a remote connection to JMX and MBean proxies to
+ manage JBoss Messaging.</para>
+ </section>
</section>
-
<section>
<title>Using Management Via Core API</title>
- <para>Another way to manage JBoss Messaging is by sending Core messages to a special
- address, the <emphasis>management address</emphasis>.</para>
- <para><emphasis>Management messages</emphasis> are regular Core messages with well-known
+ <para>The core management API in JBoss Messaging is called by sending Core messages to a
+ special address, the <emphasis>management address</emphasis>.</para>
+ <para><emphasis>Management messages</emphasis> are regular Core messages with well-known
properties that the server needs to understand to interact with the management API:</para>
<itemizedlist>
- <listitem><para>The name of the managed resource</para></listitem>
- <listitem><para>The name of the management operation</para></listitem>
- <listitem><para>The parameters of the management operation</para></listitem>
+ <listitem>
+ <para>The name of the managed resource</para>
+ </listitem>
+ <listitem>
+ <para>The name of the management operation</para>
+ </listitem>
+ <listitem>
+ <para>The parameters of the management operation</para>
+ </listitem>
</itemizedlist>
- <para>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 <emphasis>management reply</emphasis> to the management message's
- reply-to address (specified by <literal>ClientMessageImpl.REPLYTO_HEADER_NAME</literal>).
- </para>
- <para>A <literal>ClientConsumer</literal> can be used to consumed 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 <ulink url="http://json.org">JSON</ulink> String rather than Java Serialization
- (the <literal>org.jboss.messaging.core.client.management.impl.ManagementHelper</literal> can be used
+ <para>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 <emphasis>management reply</emphasis> to the management message's reply-to address
+ (specified by <literal>ClientMessageImpl.REPLYTO_HEADER_NAME</literal>). </para>
+ <para>A <literal>ClientConsumer</literal> can be used to consumed 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 <ulink url="http://json.org">JSON</ulink> String rather than Java
+ Serialization (the <literal
+ >org.jboss.messaging.core.client.management.impl.ManagementHelper</literal> can be used
to convert the JSON string to Java objects).</para>
- <para>These steps can be simplified to make it easier to invoke management operations
- using Core messages:</para>
+ <para>These steps can be simplified to make it easier to invoke management operations using
+ Core messages:</para>
<orderedlist>
- <listitem><para>create a <literal>ClientRequestor</literal> to send messages to the management
- address and receive replies</para></listitem>
- <listitem><para>create a <literal>ClientMessage</literal></para></listitem>
- <listitem><para>use the helper class <literal>org.jboss.messaging.core.client.management.impl.ManagementHelper</literal>
- to fill the message with the management properties</para>
+ <listitem>
+ <para>create a <literal>ClientRequestor</literal> to send messages to the management
+ address and receive replies</para>
</listitem>
- <listitem><para>send the message using the <literal>ClientRequestor</literal></para></listitem>
- <listitem><para>use the helper class <literal>org.jboss.messaging.core.client.management.impl.ManagementHelper</literal>
- to retrieve the operation result from the management reply</para>
- </listitem>
+ <listitem>
+ <para>create a <literal>ClientMessage</literal></para>
+ </listitem>
+ <listitem>
+ <para>use the helper class <literal
+ >org.jboss.messaging.core.client.management.impl.ManagementHelper</literal> to
+ fill the message with the management properties</para>
+ </listitem>
+ <listitem>
+ <para>send the message using the <literal>ClientRequestor</literal></para>
+ </listitem>
+ <listitem>
+ <para>use the helper class <literal
+ >org.jboss.messaging.core.client.management.impl.ManagementHelper</literal> to
+ retrieve the operation result from the management reply</para>
+ </listitem>
</orderedlist>
- <para>For example, to know the number of messages in the Core queue <literal>exampleQueue</literal>:</para>
+ <para>For example, to know the number of messages in the Core queue <literal
+ >exampleQueue</literal>:</para>
<programlisting>
ClientSession session = ...
ClientRequestor requestor = new ClientRequestor(session, "jbm.management");
@@ -459,22 +548,24 @@
int count = (Integer) ManagementHelper.getResult(reply);
System.out.println("There are " + count + " messages in exampleQueue");
</programlisting>
- <para>Management operation name and parameters must conform to the Java interfaces defined
- in the <literal>management</literal> packages.</para>
- <para>Name of the resources are built using the helper class <literal>org.jboss.messaging.core.management.ResourceNames</literal> and are straightforward
- (<literal>core.queue.exampleQueue</literal> for the Core Queue <literal>exampleQueue</literal>,
- <literal>jms.topic.exampleTopic</literal> for the JMS Topic <literal>exampleTopic</literal>, etc.).</para>
-
+ <para>Management operation name and parameters must conform to the Java interfaces defined in
+ the <literal>management</literal> packages.</para>
+ <para>Name of the resources are built using the helper class <literal
+ >org.jboss.messaging.core.management.ResourceNames</literal> and are straightforward
+ (<literal>core.queue.exampleQueue</literal> for the Core Queue <literal
+ >exampleQueue</literal>, <literal>jms.topic.exampleTopic</literal> for the JMS Topic
+ <literal>exampleTopic</literal>, etc.).</para>
<section id="management.core.configuration">
<title>Configuring Core Management</title>
- <para>the management address to send management messages is configured in <literal>jbm-configuration.xml</literal>:</para>
+ <para>the management address to send management messages is configured in <literal
+ >jbm-configuration.xml</literal>:</para>
<programlisting>
<management-address>jbm.management</management-address>
</programlisting>
<para>By default, the address is <literal>jbm.management</literal>.</para>
- <para>The management address requires a <emphasis>special</emphasis> user permission
- <literal>manage</literal> to be able to receive and handle management messages.
- This is also configured in jbm-configuration.xml:</para>
+ <para>The management address requires a <emphasis>special</emphasis> user permission
+ <literal>manage</literal> to be able to receive and handle management messages. This
+ is also configured in jbm-configuration.xml:</para>
<programlisting>
<!-- users with the admin role will be allowed to manage -->
<!-- JBoss Messaging using management messages -->
@@ -482,34 +573,44 @@
<permission type="manage" roles="admin" />
</security-setting>
</programlisting>
- </section>
-
+ </section>
</section>
-
<section id="management.jms">
<title>Using Management Via JMS</title>
<para>Using JMS messages to manage JBoss Messaging is very similar to using Core API.</para>
- <para>An important difference is that JMS requires to create a JMS Queue to send the messages
- (instead of an address for the Core API).</para>
- <para>The <emphasis>management queue</emphasis> is a special queue and needs to be instantiated
- directly by the client:</para>
+ <para>An important difference is that JMS requires a JMS Queue to send the messages to(instead
+ of an address for the Core API).</para>
+ <para>The <emphasis>management queue</emphasis> is a special queue and needs to be
+ instantiated directly by the client:</para>
<programlisting>
Queue managementQueue = new JBossQueue("jbm.management", "jbm.management");
</programlisting>
- <para>All the other steps are the same than for the Core API but they use JMS API instead:</para>
+ <para>All the other steps are the same than for the Core API but they use JMS API
+ instead:</para>
<orderedlist>
- <listitem><para>create a <literal>QueueRequestor</literal> to send messages to the management
- address and receive replies</para></listitem>
- <listitem><para>create a <literal>Message</literal></para></listitem>
- <listitem><para>use the helper class <literal>org.jboss.messaging.jms.server.management.impl.JMSManagementHelper</literal>
- to fill the message with the management properties</para>
+ <listitem>
+ <para>create a <literal>QueueRequestor</literal> to send messages to the management
+ address and receive replies</para>
</listitem>
- <listitem><para>send the message using the <literal>QueueRequestor</literal></para></listitem>
- <listitem><para>use the helper class <literal>org.jboss.messaging.jms.server.management.impl.JMSManagementHelper</literal>
- to retrieve the operation result from the management reply</para>
- </listitem>
+ <listitem>
+ <para>create a <literal>Message</literal></para>
+ </listitem>
+ <listitem>
+ <para>use the helper class <literal
+ >org.jboss.messaging.jms.server.management.impl.JMSManagementHelper</literal> to
+ fill the message with the management properties</para>
+ </listitem>
+ <listitem>
+ <para>send the message using the <literal>QueueRequestor</literal></para>
+ </listitem>
+ <listitem>
+ <para>use the helper class <literal
+ >org.jboss.messaging.jms.server.management.impl.JMSManagementHelper</literal> to
+ retrieve the operation result from the management reply</para>
+ </listitem>
</orderedlist>
- <para>For example, to know the number of messages in the JMS queue <literal>exampleQueue</literal>:</para>
+ <para>For example, to know the number of messages in the JMS queue <literal
+ >exampleQueue</literal>:</para>
<programlisting>
Queue managementQueue = new JBossQueue("jbm.management", "jbm.management");
@@ -522,110 +623,119 @@
int count = (Integer)JMSManagementHelper.getResult(reply);
System.out.println("There are " + count + " messages in exampleQueue");
</programlisting>
-
<section>
<title>Configuring JMS Management</title>
- <para>Wether JMS or Core API is used for management, the configuration
- steps are the same (see <xref linkend="management.core.configuration" />).</para>
- </section>
-
+ <para>Whether JMS or Core API is used for management, the configuration steps are the same
+ (see <xref linkend="management.core.configuration"/>).</para>
+ </section>
<section>
<title>Example</title>
- <para>The <ulink url="../../../../examples/jms/management/readme.html"><literal>management</literal> example</ulink> shows
- how to use JMS messages to manage JBoss Messaging server.</para>
- </section>
+ <para>The <ulink url="../../../../examples/jms/management/readme.html"><literal
+ >management</literal> example</ulink> shows how to use JMS messages to manage
+ JBoss Messaging server.</para>
+ </section>
</section>
-
<section id="management.replication">
<title>Management Replication</title>
- <para>JBoss Messaging allows to <emphasis>replicate</emphasis> a live server on 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.</para>
- <para>JBoss Message <emphasis>replicate management operation</emphasis> regardless
- of the way used to manage (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.</para>
- <para>If Core messages or JMS messages are used to invoke management operations, replication is handled
- automatically by JBoss Messaging.</para>
- <para>To allow this management replication with JMX, JBoss Messaging defines a <emphasis>management cluster password</emphasis>:
- this special password <emphasis>must be shared by all nodes</emphasis>. To configure it, change the value
- in <literal>jbm-configuration.xml</literal>:</para>
+ <para>JBoss Messaging allows <emphasis>replication</emphasis> 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.</para>
+ <para>JBoss Messaging <emphasis>replicates management operations</emphasis> 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.</para>
+ <para>If Core messages or JMS messages are used to invoke management operations, replication
+ is handled automatically by JBoss Messaging.</para>
+ <para>To allow this management replication with JMX, JBoss Messaging defines a
+ <emphasis>management cluster password</emphasis>: this special password <emphasis>must
+ be shared by all nodes</emphasis>. To configure it, change the value in <literal
+ >jbm-configuration.xml</literal>:</para>
<programlisting>
<management-cluster-password>CHANGE ME!!</management-cluster-password>
</programlisting>
- <para>By default, its value is <literal>CHANGE ME!!</literal>. It is strongly suggested to change it
- to a safer value (this password is never sent on the network).</para>
- <para>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 <literal>jbm-configuration.xml</literal>:</para>
+ <para>By default, its value is <literal>CHANGE ME!!</literal>. It is strongly suggested to
+ change it to a safer value (this password is never sent on the network).</para>
+ <para>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 <literal
+ >jbm-configuration.xml</literal>:</para>
<programlisting>
<management-request-timeout>5000</management-request-timeout>
</programlisting>
</section>
-
<section id="management.notifications">
<title>Management Notifications</title>
- <para>JBoss Messaging emits <emphasis>notifications</emphasis> to inform listeners of potentially
- interesting events (creation of new resources, security violation, etc.).</para>
+ <para>JBoss Messaging emits <emphasis>notifications</emphasis> to inform listeners of
+ potentially interesting events (creation of new resources, security violation,
+ etc.).</para>
<para>These notifications can be received by 3 different ways:</para>
<itemizedlist>
- <listitem><para>JMX notifications</para></listitem>
- <listitem><para>Core messages</para></listitem>
- <listitem><para>JMS messages</para></listitem>
+ <listitem>
+ <para>JMX notifications</para>
+ </listitem>
+ <listitem>
+ <para>Core messages</para>
+ </listitem>
+ <listitem>
+ <para>JMS messages</para>
+ </listitem>
</itemizedlist>
-
-
<section>
<title>JMX Notifications</title>
- <para>If JMX is enabled (see <xref linkend="management.jmx.configuration"/>), JMX notifications
- can be received by subscribing to 2 MBeans:</para>
+ <para>If JMX is enabled (see <xref linkend="management.jmx.configuration"/>), JMX
+ notifications can be received by subscribing to 2 MBeans:</para>
<itemizedlist>
- <listitem><para><literal>org.jboss.messaging:module=Core,type=Server</literal> for notifications on <emphasis>Core</emphasis> resources</para></listitem>
- <listitem><para><literal>org.jboss.messaging:module=JMS,type=Server</literal> for notifications on <emphasis>JMS</emphasis> resources</para></listitem>
- </itemizedlist>
+ <listitem>
+ <para><literal>org.jboss.messaging:module=Core,type=Server</literal> for
+ notifications on <emphasis>Core</emphasis> resources</para>
+ </listitem>
+ <listitem>
+ <para><literal>org.jboss.messaging:module=JMS,type=Server</literal> for notifications
+ on <emphasis>JMS</emphasis> resources</para>
+ </listitem>
+ </itemizedlist>
</section>
-
<section>
- <title>Core Messages Notifications</title>
- <para>JBoss Messaging defines a special <emphasis>management notification address</emphasis>.
- Core queues can be bound to this address so that clients will receive management notifications
- as Core messages</para>
-
+ <title>Core Messages Notifications</title>
+ <para>JBoss Messaging defines a special <emphasis>management notification
+ address</emphasis>. Core queues can be bound to this address so that clients will
+ receive management notifications as Core messages</para>
+ <para>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.</para>
+ <para>Notifications messages are regular Core messages with additional properties
+ corresponding to the notification (its type, when it occurred, the resources which were
+ concerned, etc.).</para>
+ <para>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.</para>
<section id="management.notifications.core.configuration">
<title>Configuring The Core Management Notification Address</title>
- <para>the management notification address to receive management notifications is configured in <literal>jbm-configuration.xml</literal>:</para>
+ <para>the management notification address to receive management notifications is
+ configured in <literal>jbm-configuration.xml</literal>:</para>
<programlisting>
- <management-notification-address>jbm.notifications</management-notification-address>
+ <management-notification-address>jbm.notifications</management-notification-address>
</programlisting>
<para>By default, the address is <literal>jbm.notifications</literal>.</para>
</section>
-
- <para>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.</para>
- <para>Notifications messages are regular Core messages with additional properties corresponding
- to the notification (its type, when it occurred, the resources which were concerned, etc.).</para>
- <para>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.</para>
- </section>
-
+ </section>
<section>
- <title>JMS Messages Notifications</title>
+ <title>JMS Messages Notifications</title>
<para>JBoss Messaging's notifications can also be received using JMS messages.</para>
- <para>It is similar to receiving notifications using Core API but an important difference
- is that JMS requires to create a JMS Destination to receive the messages (preferably
- a Topic):</para>
+ <para>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):</para>
<programlisting>
Topic notificationsTopic = new JBossTopic("jbm.notifications", "jbm.notifications");
</programlisting>
- <para>Once the notification topic is created, you can receive messages from it
- or set a <literal>MessageListener</literal>:</para>
+ <para>Once the notification topic is created, you can receive messages from it or set a
+ <literal>MessageListener</literal>:</para>
<programlisting>
Topic notificationsTopic = new JBossTopic("jbm.notifications", "jbm.notifications");
@@ -654,35 +764,36 @@
});
</programlisting>
</section>
-
<section>
<title>Example</title>
- <para>The <ulink url="../../../../examples/jms/management-notifications/readme.html"><literal>management-notifications</literal> example</ulink> shows
- how to use a JMS <literal>MessageListener</literal> to receive management notifications
- from JBoss Messaging server.</para>
- </section>
+ <para>The <ulink url="../../../../examples/jms/management-notifications/readme.html"
+ ><literal>management-notifications</literal> example</ulink> shows how to use a
+ JMS <literal>MessageListener</literal> to receive management notifications from JBoss
+ Messaging server.</para>
+ </section>
</section>
-
<section id="management.message-counters">
<title>Message Counters</title>
- <para>Message counters can be used to have informations on queue <emphasis>over time</emphasis>
- as JBoss Messaging keeps a history on queue metrics.</para>
- <para>They can be used to show <emphasis>trends</emphasis> 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.</para>
+ <para>Message counters can be used to have informations on queue <emphasis>over
+ time</emphasis> as JBoss Messaging keeps a history on queue metrics.</para>
+ <para>They can be used to show <emphasis>trends</emphasis> 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.</para>
<para>Message counters gives additional information about the queues:</para>
<itemizedlist>
<listitem>
<para><literal>count</literal></para>
- <para>The <emphasis>total</emphasis> number of messages added to the queue since the server
- was started</para>
+ <para>The <emphasis>total</emphasis> number of messages added to the queue since the
+ server was started</para>
</listitem>
<listitem>
<para><literal>countDelta</literal></para>
- <para>the number of messages added to the queue <emphasis>since the last message counter update</emphasis></para>
+ <para>the number of messages added to the queue <emphasis>since the last message counter
+ update</emphasis></para>
</listitem>
<listitem>
<para><literal>depth</literal></para>
@@ -690,10 +801,12 @@
</listitem>
<listitem>
<para><literal>depthDelta</literal></para>
- <para>The <emphasis>overall</emphasis> number of messages added/removed from the queue <emphasis>since the last message counter update</emphasis>.
- For example, if <literal>depthDelta</literal> is equal to <literal>-10</literal> this means that overall 10 messages
- have been removed from the queue (e.g. 2 messages were added and 12 were removed)</para>
- <para></para>
+ <para>The <emphasis>overall</emphasis> number of messages added/removed from the queue
+ <emphasis>since the last message counter update</emphasis>. For example, if
+ <literal>depthDelta</literal> is equal to <literal>-10</literal> this means that
+ overall 10 messages have been removed from the queue (e.g. 2 messages were added and
+ 12 were removed)</para>
+ <para/>
</listitem>
<listitem>
<para><literal>lastAddTimestamp</literal></para>
@@ -704,48 +817,49 @@
<para>The timestamp of the last message counter update</para>
</listitem>
</itemizedlist>
-
<section id="configuring.message.counters">
<title>Configuring Message Counters</title>
- <para>By default, message counters are disabled has it consumes memory (the metrics are kept in memory)
- and CPU (the queues are sampled at regular interval).</para>
- <para>To enable message counters, you can set it to <literal>true</literal> in <literal>jbm-configuration.xml</literal>:</para>
+ <para>By default, message counters are disabled as it has a negative effect on performance,
+ memory (the metrics are kept in memory) and CPU (the queues are sampled at regular
+ interval).</para>
+ <para>To enable message counters, you can set it to <literal>true</literal> in <literal
+ >jbm-configuration.xml</literal>:</para>
<programlisting>
<message-counter-enabled>true</message-counter-enabled>
</programlisting>
- <para>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 <literal>jbm-configuration.xml</literal>:</para>
+ <para>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
+ <literal>jbm-configuration.xml</literal>:</para>
<programlisting>
<!-- 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>
</programlisting>
- </section>
-
- <para>Message counters can be retrieved using the Management API. For example, to retrieve message counters on a JMS Queue using JMX:</para>
- <programlisting>
- // retrieve a connection to JBoss Messaging's MBeanServer
- MBeanServerConnection mbsc = ...
- JMSQueueControlMBean queueControl = (JMSQueueControlMBean)MBeanServerInvocationHandler.newProxyInstance(mbsc,
- on,
- JMSQueueControlMBean.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());
- </programlisting>
-
+ <para>Message counters can be retrieved using the Management API. For example, to retrieve
+ message counters on a JMS Queue using JMX:</para>
+ <programlisting>
+ // retrieve a connection to JBoss Messaging's MBeanServer
+ MBeanServerConnection mbsc = ...
+ JMSQueueControlMBean queueControl = (JMSQueueControlMBean)MBeanServerInvocationHandler.newProxyInstance(mbsc,
+ on,
+ JMSQueueControlMBean.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());
+ </programlisting>
+ </section>
<section>
<title>Example</title>
- <para>The <ulink url="../../../../examples/jms/message-counters/readme.html"><literal>message-counters</literal> example</ulink> shows
- how to use message counters to retrieve information on a JMS <literal>Queue</literal>.</para>
- </section>
+ <para>The <ulink url="../../../../examples/jms/message-counters/readme.html"><literal
+ >message-counters</literal> example</ulink> shows how to use message counters to
+ retrieve information on a JMS <literal>Queue</literal>.</para>
+ </section>
</section>
-
</chapter>
More information about the jboss-cvs-commits
mailing list