[jboss-cvs] JBoss Messaging SVN: r2307 - trunk/docs/clustering/en/modules.
jboss-cvs-commits at lists.jboss.org
jboss-cvs-commits at lists.jboss.org
Tue Feb 13 20:04:43 EST 2007
Author: ovidiu.feodorov at jboss.com
Date: 2007-02-13 20:04:43 -0500 (Tue, 13 Feb 2007)
New Revision: 2307
Modified:
trunk/docs/clustering/en/modules/configuration.xml
Log:
more work on http://jira.jboss.org/jira/browse/JBMESSAGING-445
Modified: trunk/docs/clustering/en/modules/configuration.xml
===================================================================
--- trunk/docs/clustering/en/modules/configuration.xml 2007-02-14 01:04:15 UTC (rev 2306)
+++ trunk/docs/clustering/en/modules/configuration.xml 2007-02-14 01:04:43 UTC (rev 2307)
@@ -3,78 +3,109 @@
<title>JBoss Messaging Clustering Configuration</title>
<para>
- This section describes how to configure JBoss Messaging 1.2 Beta clustering.
+ In order to understand JBoss Messaging clustering configuration, we will start with a
+ short clustering architectural overview, where we will identify "configuration areas",
+ meaning architectural elements that have corresponding configuration files, and whose
+ behavior can be changed through configuration.
</para>
- <para>
- Please note that the clustering configuration is likely to change before the 1.2 final release.
+ <section id="clustering_configuration_overview">
+ <title>Clustering Architectural Overview</title>
- In particular we will be adding the ability for JBoss Messaging to use a pre-configured JGroups
- multiplex channel when used inside JBoss Application Server.
+ <para>
+ One of the fundamental Messaging Core building blocks is the "Post Office". A JBoss Messaging
+ Post Office is message routing component, which accepts messages for delivery and synchronously
+ forwards them to their destination queues or topic subscriptions.
+ </para>
- </para>
+ <para>
+ There is a single Post Office instance per JBoss Messaging server (cluster node). Both queues
+ and topics deployed on a JBoss Messaging node are "plugged" into that Post Office instance.
+ Internally JBoss Messaging only deals with the concepts of queues, and considers a topic to
+ just be a set of queues (one for each subscription). Depending on the type of subscription -
+ durable or non-durable - the corresponding queue saves messages to persistent storage or
+ it just holds messages in memory and discards them when the non-durable subscription is closed.
+ </para>
- <section id="config">
+ <para>
+ Therefore, for a JMS queue, the Post Office routes messages to one and only one core queue,
+ depending on the queue name, whereas for a JMS topic, the Post Office routes a message
+ to a set of core queues, one for each topic subscription, depending on the topic name.
+ </para>
- <para>
- JBoss Messaging includes the concept of a "Post Office". Messages are posted at a Post Office and
- the Post Office routes the message to it's destination queues.
- </para>
+ <para>
+ Clustering across multiple address spaces is achieved by clustering Post Office instances. Each
+ JBoss Messaging cluster node runs a Clustered Post Office instance, which is aware of the presence
+ of all other clustered Post Offices in the cluster. There is an one-to-one relationship between cluster
+ nodes and clustered Post Office instances. So, naturally, the most important piece of clustering
+ configuration is the <emphasis>clustered Post Office service configuration</emphasis>,
+ covered in detail below.
+ </para>
- <para>
- Both queues and topics use the same Post Office instance. Internally JBoss Messaging only deals
- with the concepts of queues, and considers a topic to just be a set of queues (one for
- each subscription).
- </para>
+ <para>
+ Clustered Post Office instances connect to each other via JGroups and they heavily rely on JGroups
+ group management and notification mechanisms. <emphasis>JGroups stack configuration</emphasis>
+ is an essential part of JBoss Messaging clustering configuration. JGroups configuration is only
+ briefly addressed in this guide. Detailed information on JGroups can be found in JGroups
+ release documentation or on-line at <ulink url="http://www.jgroups.org">http://www.jgroups.org</ulink>
+ or <ulink url="http://wiki.jboss.org/wiki/Wiki.jsp?page=JGroups">http://wiki.jboss.org/wiki/Wiki.jsp?page=JGroups</ulink>
+ </para>
- <para>
- Therefore, for a JMS queue, the Post Office routes messages to one and only one core queue,
- depending on the queue name, whereas for a JMS topic, the Post Office routes a message
- to a set of core queues (one for each subscription) depending on the topic name.
- </para>
+ <para>
+ When routing messages, a clustered Post Office has a choice of forwarding the message to local
+ queues or remote queues, plugged into remote Post Office instances that are part of the same
+ cluster. Local queues are usually preferred, but if a local queue is part of a distributed queue, has
+ no consumers, and other local queues part of the same distributed queue have consumers, messages
+ can be automatically redistributed, subject of the message redistribution policy in effect. This allows
+ us to create distributed queues and distributed topics. <emphasis>Message redistribution
+ configuration</emphasis> is another subject that we will insist on.
+ </para>
- <para>
- For clustering, we extend the concept of a Post Office to create a Clustered Post Office.
- </para>
+ <para>
+ Please note that the elements of clustering configuration are likely to change before the 1.2 final release.
+ In particular we will try to add the ability for JBoss Messaging to use a pre-configured JGroups
+ multiplex channel when used inside JBoss Application Server, but this is subject to availability of a
+ AS clustering service supporting a multiplexed JGroups channel; such a service is currently being
+ worked on by the AS Clustering team.
+ </para>
- <para>
- Clustered Post Office instances in a cluster connect to each other via JGroups, and when
- routing messages instead of just routing to local queues as is the case with a non-clustered
- Post Office, they can also route messages to queues on other Clustered Post Office instances.
+ </section>
- This allows us to create distributed queues and distributed topics.
- </para>
+ <section id="clustered_postoffice_configuration">
+ <title>Clustered Post Office Configuration</title>
- <para>
- In the current release of JBoss Messaging 1.2, the JGroups configuration for each Clustered
- Post Office is specified in the Post Office configuration.
+ <para>
+ In JBoss Messaging 1.2.0, the JGroups configuration for each clustered Post Office instance
+ is specified in the Post Office MBean service configuration element. The Post Office configuration
+ is present in the persistence configuration file corresponding to the specific database you're using
+ for the cluster instance.
+ </para>
- The details of the JGroups configuration won't be discussed here since it is standard
- JGroups configuration.
+ <para>
+ So, if you are using a MySQL database instance as shared persistent storage for your cluster, the
+ Post Office configuration for a specific node instance is available in
+ <filename>$JBOSS_HOME/server/messaging-nodeX/deploy/jboss-messaging.sar/clustered-mysql-persistence-service.xml</filename>
+ </para>
- For more information on JGroups configuration please consult
- http://wiki.jboss.org/wiki/Wiki.jsp?page=JGroups
- </para>
+ <para>An example of a Clustered Post Office configuration is shown below:</para>
- <para>An example of a Clustered Post Office configuration is shown below</para>
-
- <programlisting>
- <mbean code="org.jboss.messaging.core.plugin.ClusteredPostOfficeService"
+ <programlisting>
+ <mbean code="org.jboss.messaging.core.plugin.ClusteredPostOfficeService"
name="jboss.messaging:service=PostOffice"
xmbean-dd="xmdesc/ClusteredPostOffice-xmbean.xml">
<depends optional-attribute-name="ServerPeer">jboss.messaging:service=ServerPeer</depends>
<depends>jboss.jca:service=DataSourceBinding,name=DefaultDS</depends>
<depends optional-attribute-name="TransactionManager">jboss:service=TransactionManager</depends>
- <attribute name="PostOfficeName">Clustered Queue</attribute>
+ <attribute name="PostOfficeName">Clustered JMS</attribute>
<attribute name="DataSource">java:/DefaultDS</attribute>
<attribute name="CreateTablesOnStartup">true</attribute>
- <attribute name="SqlProperties"><![CDATA[
- CREATE_POSTOFFICE_TABLE=CREATE TABLE JMS_POSTOFFICE (POSTOFFICE_NAME VARCHAR(255), NODE_ID INTEGER, QUEUE_NAME VARCHAR(1023), COND VARCHAR(1023), SELECTOR VARCHAR(1023), CHANNEL_ID BIGINT)
- INSERT_BINDING=INSERT INTO JMS_POSTOFFICE (POSTOFFICE_NAME, NODE_ID, QUEUE_NAME, COND, SELECTOR, CHANNEL_ID) VALUES (?, ?, ?, ?, ?, ?)
- DELETE_BINDING=DELETE FROM JMS_POSTOFFICE WHERE POSTOFFICE_NAME=? AND NODE_ID=? AND QUEUE_NAME=?
- LOAD_BINDINGS=SELECT NODE_ID, QUEUE_NAME, COND, SELECTOR, CHANNEL_ID FROM JMS_POSTOFFICE WHERE POSTOFFICE_NAME = ?
+ <attribute name="SqlProperties"><!![CDATA[
+ CREATE_POSTOFFICE_TABLE=CREATE TABLE JBM_POSTOFFICE (POSTOFFICE_NAME VARCHAR(255), NODE_ID INTEGER, QUEUE_NAME VARCHAR(1023), COND VARCHAR(1023), SELECTOR VARCHAR(1023), CHANNEL_ID BIGINT, IS_FAILED_OVER CHAR(1), FAILED_NODE_ID INTEGER)
+ INSERT_BINDING=INSERT INTO JBM_POSTOFFICE (POSTOFFICE_NAME, NODE_ID, QUEUE_NAME, COND, SELECTOR, CHANNEL_ID, IS_FAILED_OVER, FAILED_NODE_ID) VALUES (?, ?, ?, ?, ?, ?, ?, ?)
+ DELETE_BINDING=DELETE FROM JBM_POSTOFFICE WHERE POSTOFFICE_NAME=? AND NODE_ID=? AND QUEUE_NAME=?
+ LOAD_BINDINGS=SELECT NODE_ID, QUEUE_NAME, COND, SELECTOR, CHANNEL_ID, IS_FAILED_OVER, FAILED_NODE_ID FROM JBM_POSTOFFICE WHERE POSTOFFICE_NAME = ?
]]></attribute>
- <attribute name="GroupName">Queue</attribute>
+ <attribute name="GroupName">DefaultPostOffice</attribute>
<attribute name="StateTimeout">5000</attribute>
<attribute name="CastTimeout">5000</attribute>
<attribute name="StatsSendPeriod">10000</attribute>
@@ -82,99 +113,141 @@
<attribute name="ClusterRouterFactory">org.jboss.messaging.core.plugin.postoffice.cluster.DefaultRouterFactory</attribute>
<attribute name="AsyncChannelConfig">
- <config>
- <UDP mcast_recv_buf_size="500000" down_thread="false" ip_mcast="true" mcast_send_buf_size="32000"
- mcast_port="45567" ucast_recv_buf_size="500000" use_incoming_packet_handler="false"
- mcast_addr="228.8.8.8" use_outgoing_packet_handler="true" loopback="true" ucast_send_buf_size="32000" ip_ttl="32" bind_addr="127.0.0.1"/>
- <AUTOCONF down_thread="false" up_thread="false"/>
- <PING timeout="2000" down_thread="false" num_initial_members="3" up_thread="false"/>
- <MERGE2 max_interval="10000" down_thread="false" min_interval="5000" up_thread="false"/>
- <FD timeout="2000" max_tries="3" down_thread="false" up_thread="false" shun="true"/>
- <VERIFY_SUSPECT timeout="1500" down_thread="false" up_thread="false"/>
- <pbcast.NAKACK max_xmit_size="8192" down_thread="false" use_mcast_xmit="true" gc_lag="50" up_thread="false"
- retransmit_timeout="100,200,600,1200,2400,4800"/>
- <UNICAST timeout="1200,2400,3600" down_thread="false" up_thread="false"/>
- <pbcast.STABLE stability_delay="1000" desired_avg_gossip="20000" down_thread="false" max_bytes="0" up_thread="false"/>
- <FRAG frag_size="8192" down_thread="false" up_thread="false"/>
- <VIEW_SYNC avg_send_interval="60000" down_thread="false" up_thread="false" />
- <pbcast.GMS print_local_addr="true" join_timeout="3000" down_thread="false" join_retry_timeout="2000" up_thread="false" shun="true"/>
- </config>
+ <config>
+ <UDP mcast_recv_buf_size="500000" down_thread="false" ip_mcast="true" mcast_send_buf_size="32000"
+ mcast_port="45567" ucast_recv_buf_size="500000" use_incoming_packet_handler="false"
+ mcast_addr="228.8.8.8" use_outgoing_packet_handler="true" loopback="true" ucast_send_buf_size="32000" ip_ttl="32" bind_addr="127.0.0.1"/>
+ <AUTOCONF down_thread="false" up_thread="false"/>
+ <PING timeout="2000" down_thread="false" num_initial_members="3" up_thread="false"/>
+ <MERGE2 max_interval="10000" down_thread="false" min_interval="5000" up_thread="false"/>
+ <FD timeout="2000" max_tries="3" down_thread="false" up_thread="false" shun="true"/>
+ <VERIFY_SUSPECT timeout="1500" down_thread="false" up_thread="false"/>
+ <pbcast.NAKACK max_xmit_size="8192" down_thread="false" use_mcast_xmit="true" gc_lag="50" up_thread="false"
+ retransmit_timeout="100,200,600,1200,2400,4800"/>
+ <UNICAST timeout="1200,2400,3600" down_thread="false" up_thread="false"/>
+ <pbcast.STABLE stability_delay="1000" desired_avg_gossip="20000" down_thread="false" max_bytes="0" up_thread="false"/>
+ <FRAG frag_size="8192" down_thread="false" up_thread="false"/>
+ <VIEW_SYNC avg_send_interval="60000" down_thread="false" up_thread="false" />
+ <pbcast.GMS print_local_addr="true" join_timeout="3000" down_thread="false" join_retry_timeout="2000" up_thread="false" shun="true"/>
+ </config>
</attribute>
<attribute name="SyncChannelConfig">
- <config>
- <UDP mcast_recv_buf_size="500000" down_thread="false" ip_mcast="true" mcast_send_buf_size="32000"
- mcast_port="45568" ucast_recv_buf_size="500000" use_incoming_packet_handler="false"
- mcast_addr="228.8.8.8" use_outgoing_packet_handler="true" loopback="true" ucast_send_buf_size="32000" ip_ttl="32" bind_addr="127.0.0.1"/>
- <AUTOCONF down_thread="false" up_thread="false"/>
- <PING timeout="2000" down_thread="false" num_initial_members="3" up_thread="false"/>
- <MERGE2 max_interval="10000" down_thread="false" min_interval="5000" up_thread="false"/>
- <FD timeout="2000" max_tries="3" down_thread="false" up_thread="false" shun="true"/>
- <VERIFY_SUSPECT timeout="1500" down_thread="false" up_thread="false"/>
- <pbcast.NAKACK max_xmit_size="8192" down_thread="false" use_mcast_xmit="true" gc_lag="50" up_thread="false"
- retransmit_timeout="100,200,600,1200,2400,4800"/>
- <UNICAST timeout="1200,2400,3600" down_thread="false" up_thread="false"/>
- <pbcast.STABLE stability_delay="1000" desired_avg_gossip="20000" down_thread="false" max_bytes="0" up_thread="false"/>
- <FRAG frag_size="8192" down_thread="false" up_thread="false"/>
- <VIEW_SYNC avg_send_interval="60000" down_thread="false" up_thread="false" />
- <pbcast.GMS print_local_addr="true" join_timeout="3000" down_thread="false" join_retry_timeout="2000" up_thread="false" shun="true"/>
- <pbcast.STATE_TRANSFER down_thread="false" up_thread="false"/>
- </config>
+ <config>
+ <UDP mcast_recv_buf_size="500000" down_thread="false" ip_mcast="true" mcast_send_buf_size="32000"
+ mcast_port="45568" ucast_recv_buf_size="500000" use_incoming_packet_handler="false"
+ mcast_addr="228.8.8.8" use_outgoing_packet_handler="true" loopback="true" ucast_send_buf_size="32000" ip_ttl="32" bind_addr="127.0.0.1"/>
+ <AUTOCONF down_thread="false" up_thread="false"/>
+ <PING timeout="2000" down_thread="false" num_initial_members="3" up_thread="false"/>
+ <MERGE2 max_interval="10000" down_thread="false" min_interval="5000" up_thread="false"/>
+ <FD timeout="2000" max_tries="3" down_thread="false" up_thread="false" shun="true"/>
+ <VERIFY_SUSPECT timeout="1500" down_thread="false" up_thread="false"/>
+ <pbcast.NAKACK max_xmit_size="8192" down_thread="false" use_mcast_xmit="true" gc_lag="50" up_thread="false"
+ retransmit_timeout="100,200,600,1200,2400,4800"/>
+ <UNICAST timeout="1200,2400,3600" down_thread="false" up_thread="false"/>
+ <pbcast.STABLE stability_delay="1000" desired_avg_gossip="20000" down_thread="false" max_bytes="0" up_thread="false"/>
+ <FRAG frag_size="8192" down_thread="false" up_thread="false"/>
+ <VIEW_SYNC avg_send_interval="60000" down_thread="false" up_thread="false" />
+ <pbcast.GMS print_local_addr="true" join_timeout="3000" down_thread="false" join_retry_timeout="2000" up_thread="false" shun="true"/>
+ <pbcast.STATE_TRANSFER down_thread="false" up_thread="false"/>
+ </config>
</attribute>
- </mbean>
- </programlisting>
+ </mbean>
+ </programlisting>
- <section id="conf.groupname">
- <title>GroupName</title>
- <para>
- This identifies the JGroups group the Clustered Post Office will connect to. All Clustered Post Office instances with the same
- group name will connect to that group.
- </para>
- </section>
+ <para>Relevant clustered Post Office configuration attributes are discussed below:</para>
- <section id="conf.statetimeout">
- <title>StateTimeout</title>
- <para>
- The maximum amount of time in milliseconds to wait when making a request to get the group state and waiting for the result.
- You will not normally need to change this value. Default is 5000 ms.
- </para>
- </section>
+ <section id="conf.groupname">
+ <title><literal>GroupName</literal></title>
+ <para>
+ This identifies the JGroups group the clustered Post Office will connect to.
+ All clustered Post Office instances with the same group name will connect to that group.
+ </para>
+ </section>
- <section id="conf.casttimeout">
- <title>CastTimeout</title>
- <para>
- The maximum amount of time in milliseconds to wait when casting a message and waiting for a result.
- You will not normally need to change this value. Default is 5000 ms.
- </para>
- </section>
+ <section id="conf.statetimeout">
+ <title><literal>StateTimeout</literal></title>
+ <para>
+ The maximum amount of time in milliseconds to wait when making a request
+ to get the group state and waiting for the result. You will not normally need
+ to change this value. Default is 5000 ms.
+ </para>
+ </section>
- <section id="conf.statssend">
- <title>StatsSendPeriod</title>
- <para>
- The period in milliseconds between much statistics for each queue will be cast across the cluster.
- </para>
- </section>
+ <section id="conf.casttimeout">
+ <title><literal>CastTimeout</literal></title>
+ <para>
+ The maximum amount of time in milliseconds to wait when casting a message
+ and waiting for a result. You will not normally need to change this value.
+ Default is 5000 ms.
+ </para>
+ </section>
- <section id="conf.messagepullpolicy">
- <title>MessagePullPolicy</title>
- <para>
- The fully qualified class name of the class that implements the MessagePullPolicy.
- To specify different message pull policies this can be changed.
- To disable message redistribution specify org.jboss.messaging.core.plugin.postoffice.cluster.NullMessagePullPolicy.
- To enable default message redistribution specify org.jboss.messaging.core.plugin.postoffice.cluster.DefaultMessagePullPolicy.
- </para>
- </section>
+ <section id="conf.statssend">
+ <title><literal>StatsSendPeriod</literal></title>
+ <para>
+ The period in milliseconds between much statistics for each queue will be cast
+ across the cluster.
+ </para>
+ </section>
- <section id="conf.clusterrouterfactory">
- <title>ClusterRouterFactory</title>
- <para>
- The fully qualified class name of the class that implements a factory for creating message routers. For different message routing policies
- this can be changed.
- </para>
+ <section id="conf.clusterrouterfactory">
+ <title><literal>ClusterRouterFactory</literal></title>
+ <para>
+ The fully qualified class name of the class that implements a factory for creating
+ message routers. For different message routing policies this can be changed.
+ Default is <literal>org.jboss.messaging.core.plugin.postoffice.cluster.DefaultRouterFactory</literal>.
+ This factory creates routers that always favor local queues.
+ </para>
+ </section>
+
+ <section id="conf.messagepullpolicy">
+ <title><literal>MessagePullPolicy</literal></title>
+ <para>
+ The fully qualified class name of the class that implements the MessagePullPolicy.
+ The message pull policy specifies how messages are redistributed after they leave
+ the Post Office and are delivered to queues. You can find more on message redistribution
+ policy in the dedicated section below. By default, the message redistribution policy
+ is <literal>org.jboss.messaging.core.plugin.postoffice.cluster.DefaultMessagePullPolicy</literal>.
+ </para>
+ </section>
+
</section>
+ <section id="jgroups_configuration">
+ <title>JGroups Stack Configuration</title>
+ <para>
+ The details of the JGroups configuration won't be discussed here since it is standard JGroups configuration.
+ Detailed information on JGroups can be found in JGroups release documentation or on-line at
+ <ulink url="http://www.jgroups.org">http://www.jgroups.org</ulink> or
+ <ulink url="http://wiki.jboss.org/wiki/Wiki.jsp?page=JGroups">http://wiki.jboss.org/wiki/Wiki.jsp?page=JGroups</ulink>
+ </para>
</section>
+ <section id="message_redistribution_configuration">
+ <title>Message Redistribution Configuration</title>
+ <para>
+ Each clustered Post Office instance can be configured to use a customizable
+ <emphasis>message redistribution policy</emphasis>. The message redistribution
+ policy dictates what happens with messages that are delivered to a local queue
+ that is part of a distributed queue or a distributed subscription. In order to use
+ a specific message redistribution policy, use the fully qualified class name of the
+ class that implements the MessagePullPolicy.
+ </para>
+ <para>
+ By default, the message redistribution policy is
+ <literal>org.jboss.messaging.core.plugin.postoffice.cluster.DefaultMessagePullPolicy</literal>
+ which tries to redistribute messages depending on receivers's consumption speed.
+ </para>
-</chapter>
+ <para>
+ To disable message redistribution completely, specify
+ <literal>org.jboss.messaging.core.plugin.postoffice.cluster.NullMessagePullPolicy</literal>
+ as the value of <literal>MessagePullPolicy</literal> attribute. In this case, a message is
+ not redistributed, even if the local queue that has been delivered to has no consumers.
+ </para>
+
+ </section>
+
+</chapter>
\ No newline at end of file
More information about the jboss-cvs-commits
mailing list