[jboss-cvs] JBoss Messaging SVN: r6845 - trunk/docs/user-manual/en/modules.
jboss-cvs-commits at lists.jboss.org
jboss-cvs-commits at lists.jboss.org
Mon May 18 11:00:41 EDT 2009
Author: jmesnil
Date: 2009-05-18 11:00:41 -0400 (Mon, 18 May 2009)
New Revision: 6845
Modified:
trunk/docs/user-manual/en/modules/clusters.xml
trunk/docs/user-manual/en/modules/configuring-transports.xml
trunk/docs/user-manual/en/modules/management.xml
Log:
user manual
* more explanation of message counters
* description of the Core management API
* xrefs to other relevant chapters
Modified: trunk/docs/user-manual/en/modules/clusters.xml
===================================================================
--- trunk/docs/user-manual/en/modules/clusters.xml 2009-05-18 14:59:49 UTC (rev 6844)
+++ trunk/docs/user-manual/en/modules/clusters.xml 2009-05-18 15:00:41 UTC (rev 6845)
@@ -48,7 +48,7 @@
>UDP</ulink> multicast to broadcast server connection settings. If UDP is disabled
on your network you won't be able to use this, and will have to specify servers
explicitly when setting up a cluster or using a messaging client.</para>
- <section>
+ <section id="clusters.broadcast-groups">
<title>Broadcast Groups</title>
<para>A broadcast group is the means by which a server broadcasts connectors over the
network. A connector defines a way in which a client (or other server) can make
@@ -119,7 +119,7 @@
</listitem>
</itemizedlist>
</section>
- <section>
+ <section id="clusters.discovery-groups">
<title>Discovery Groups</title>
<para>While the broadcast group defines who connector information is broadcast from a
server, a discovery group defines how connector information is received from a
@@ -282,7 +282,7 @@
configured to only distribute to other nodes if they have matching consumers. We'll look
at both these cases in turn with some examples, but first we'll discuss configuring
cluster connections in general.</para>
- <section>
+ <section id="clusters.cluster-connections">
<title>Configuring Cluster Connections</title>
<para>Cluster Connections group servers into clusters so that messages can be load
balanced between the nodes of the cluster. Let's take a look at a typical cluster
Modified: trunk/docs/user-manual/en/modules/configuring-transports.xml
===================================================================
--- trunk/docs/user-manual/en/modules/configuring-transports.xml 2009-05-18 14:59:49 UTC (rev 6844)
+++ trunk/docs/user-manual/en/modules/configuring-transports.xml 2009-05-18 15:00:41 UTC (rev 6845)
@@ -6,7 +6,7 @@
straightforward.</para>
<para>In this chapter we'll describe the concepts required for understanding JBoss Messaging
transports and where and how they're configured.</para>
- <section>
+ <section id="configuring-transports.acceptors">
<title>Understanding Acceptors</title>
<para>One of the most important concepts in JBoss Messaging transports is the
<emphasis>acceptor</emphasis>. Let's dive straight in and take a look at an acceptor
Modified: trunk/docs/user-manual/en/modules/management.xml
===================================================================
--- trunk/docs/user-manual/en/modules/management.xml 2009-05-18 14:59:49 UTC (rev 6844)
+++ trunk/docs/user-manual/en/modules/management.xml 2009-05-18 15:00:41 UTC (rev 6845)
@@ -34,10 +34,172 @@
<listitem><para><emphasis>JMS</emphasis> resources are located in the
<literal>org.jboss.messaging.jms.server.management</literal> package</para></listitem>
</itemizedlist>
- <para>Please refer to the API javadoc for a complete description on the management API.</para>
+ <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 wether 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>
+ <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>
+ </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>
+ </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>
+ </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>
+ </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>
+ </listitem>
+ <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 on 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>). You can list all the roles
+ associated to the queue with the <literal>getRoles()</literal> method</para>
+ </listitem>
+ </itemizedlist>
+
+ <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>
+ </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>
+ </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
+ 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>
+ </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>
+ 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>
+ </itemizedlist>
+
+ <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>
+ </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>
+ </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>
+ </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>
+ </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>
+ </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>
+ </listitem>
+ </itemizedlist>
+
+
+
+ </section>
+
+ <section>
+ <title>JMS Management API</title>
+ <para>JBoss Messaging defines a JMS Management API to manage JMS resources.</para>
+
+ <para>TODO</para>
+ </section>
+
</section>
<section id="management.jmx">
@@ -347,7 +509,44 @@
<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>
+ 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>
+ </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>
+ </listitem>
+ <listitem>
+ <para><literal>depth</literal></para>
+ <para>The <emphasis>current</emphasis> number of messages in the queue</para>
+ </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>
+ </listitem>
+ <listitem>
+ <para><literal>lastAddTimestamp</literal></para>
+ <para>The timestamp of the last time a message was added to the queue</para>
+ </listitem>
+ <listitem>
+ <para><literal>udpateTimestamp</literal></para>
+ <para>The timestamp of the last message counter update</para>
+ </listitem>
+ </itemizedlist>
<section>
<title>Configuring Message Counters</title>
More information about the jboss-cvs-commits
mailing list