[jboss-cvs] JBoss Messaging SVN: r2518 - in trunk/docs: userguide-1.2 and 3 other directories.
jboss-cvs-commits at lists.jboss.org
jboss-cvs-commits at lists.jboss.org
Thu Mar 1 00:24:11 EST 2007
Author: ovidiu.feodorov at jboss.com
Date: 2007-03-01 00:24:11 -0500 (Thu, 01 Mar 2007)
New Revision: 2518
Added:
trunk/docs/userguide-1.2/
trunk/docs/userguide-1.2/build.xml
trunk/docs/userguide-1.2/en/
trunk/docs/userguide-1.2/en/images/
trunk/docs/userguide-1.2/en/images/drawings.odt
trunk/docs/userguide-1.2/en/master.xml
trunk/docs/userguide-1.2/en/modules/
trunk/docs/userguide-1.2/en/modules/CLUST_about.xml
trunk/docs/userguide-1.2/en/modules/CLUST_configuration.xml
trunk/docs/userguide-1.2/en/modules/CLUST_installation.xml
trunk/docs/userguide-1.2/en/modules/CLUST_introduction.xml
trunk/docs/userguide-1.2/en/modules/CLUST_overview.xml
trunk/docs/userguide-1.2/en/modules/UG2_about.xml
trunk/docs/userguide-1.2/en/modules/UG2_configuration.xml
trunk/docs/userguide-1.2/en/modules/UG2_gettingstarted.xml
trunk/docs/userguide-1.2/en/modules/UG2_installation.xml
trunk/docs/userguide-1.2/en/modules/UG2_introduction.xml
trunk/docs/userguide-1.2/en/modules/UG2_performance.xml
trunk/docs/userguide-1.2/en/modules/UG2_runningexamples.xml
Removed:
trunk/docs/userguide-2/
Log:
cleaning up documentation a bit
Added: trunk/docs/userguide-1.2/build.xml
===================================================================
--- trunk/docs/userguide-1.2/build.xml (rev 0)
+++ trunk/docs/userguide-1.2/build.xml 2007-03-01 05:24:11 UTC (rev 2518)
@@ -0,0 +1,17 @@
+<project name="jbmessaging.documentation" default="all" basedir=".">
+
+ <property name="build.dir" value="${basedir}/../../output/docs/userguide-2"/>
+ <property name="pdf.name" value="JBossMessagingUsersGuide-2.pdf"/>
+ <import file="${basedir}/../../lib/docbook-support/support.xml"/>
+
+ <target name="all" depends="clean">
+ <mkdir dir="en/images" />
+ <antcall target="lang.all"><param name="lang" value="en"/></antcall>
+ </target>
+
+ <target name="html.doc" description="creates the html docs only and opens a browser">
+ <mkdir dir="en/images" />
+ <antcall target="lang.dochtml"><param name="lang" value="en"/></antcall>
+ </target>
+
+</project>
Added: trunk/docs/userguide-1.2/en/images/drawings.odt
===================================================================
(Binary files differ)
Property changes on: trunk/docs/userguide-1.2/en/images/drawings.odt
___________________________________________________________________
Name: svn:mime-type
+ application/octet-stream
Added: trunk/docs/userguide-1.2/en/master.xml
===================================================================
--- trunk/docs/userguide-1.2/en/master.xml (rev 0)
+++ trunk/docs/userguide-1.2/en/master.xml 2007-03-01 05:24:11 UTC (rev 2518)
@@ -0,0 +1,50 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.3CR3//EN"
+"../../../lib/docbook-support/support/docbook-dtd/docbookx.dtd" [
+<!ENTITY UG2_about SYSTEM "modules/UG2_about.xml">
+<!ENTITY UG2_introduction SYSTEM "modules/UG2_introduction.xml">
+<!ENTITY UG2_gettingstarted SYSTEM "modules/UG2_gettingstarted.xml">
+<!ENTITY UG2_installation SYSTEM "modules/UG2_installation.xml">
+<!ENTITY UG2_runningexamples SYSTEM "modules/UG2_runningexamples.xml">
+<!ENTITY UG2_configuration SYSTEM "modules/UG2_configuration.xml">
+<!ENTITY UG2_performance SYSTEM "modules/UG2_performance.xml">
+<!ENTITY C_about SYSTEM "modules/CLUST_about.xml">
+<!ENTITY C_introduction SYSTEM "modules/CLUST_introduction.xml">
+<!ENTITY C_overview SYSTEM "modules/CLUST_overview.xml">
+<!ENTITY C_installation SYSTEM "modules/CLUST_installation.xml">
+<!ENTITY C_configuration SYSTEM "modules/CLUST_configuration.xml">
+]>
+<book lang="en">
+ <bookinfo>
+ <title>JBoss Messaging User's Guide 2.0</title>
+
+ <subtitle>A high performance JMS server for JBoss</subtitle>
+ </bookinfo>
+
+ <toc></toc>
+
+ &UG2_about;
+
+ &UG2_introduction;
+
+ &UG2_gettingstarted;
+
+ &UG2_runningexamples;
+
+ &UG2_installation;
+
+ &UG2_configuration;
+
+ &UG2_performance;
+
+ &C_about;
+
+ <!-- &C_introduction; -->
+
+ &C_overview;
+
+ &C_installation;
+
+ &C_configuration;
+
+</book>
Added: trunk/docs/userguide-1.2/en/modules/CLUST_about.xml
===================================================================
--- trunk/docs/userguide-1.2/en/modules/CLUST_about.xml (rev 0)
+++ trunk/docs/userguide-1.2/en/modules/CLUST_about.xml 2007-03-01 05:24:11 UTC (rev 2518)
@@ -0,0 +1,19 @@
+<chapter id="CLUST_about">
+
+<title>JBoss Messaging Clustering</title>
+
+ <para>
+ This section of the userguide gives a brief overview of the features available in JBoss Messaging Clustering 1.2.0.GA
+ </para>
+
+ <para>
+ It gives a high level explanation of how clustering works and shows you how to set up a simple
+ cluster of JBoss Messaging servers.
+ </para>
+
+ <para>
+ Please send your suggestions, updates or comments to the
+ <ulink url="http://www.jboss.org/index.html?module=bb&op=viewforum&f=238">JBoss Messaging user forum</ulink>.
+ </para>
+
+</chapter>
Added: trunk/docs/userguide-1.2/en/modules/CLUST_configuration.xml
===================================================================
--- trunk/docs/userguide-1.2/en/modules/CLUST_configuration.xml (rev 0)
+++ trunk/docs/userguide-1.2/en/modules/CLUST_configuration.xml 2007-03-01 05:24:11 UTC (rev 2518)
@@ -0,0 +1,269 @@
+<chapter id="CLUST_configuration">
+
+ <title>JBoss Messaging Clustering Configuration</title>
+
+ <para>
+ 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>
+
+ <section id="clustering_configuration_overview">
+ <title>Clustering Architectural Overview</title>
+
+ <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>
+ 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>
+
+ <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>
+ 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>
+ 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>
+ 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>
+ Please note that some 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>
+
+ </section>
+
+ <section id="clustered_postoffice_configuration">
+ <title>Clustered Post Office Configuration</title>
+
+ <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>
+
+ <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>
+
+ <para>An example of a Clustered Post Office configuration is shown below:</para>
+
+ <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 JMS</attribute>
+<attribute name="DataSource">java:/DefaultDS</attribute>
+<attribute name="CreateTablesOnStartup">true</attribute>
+<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">DefaultPostOffice</attribute>
+<attribute name="StateTimeout">5000</attribute>
+<attribute name="CastTimeout">5000</attribute>
+<attribute name="StatsSendPeriod">10000</attribute>
+<attribute name="MessagePullPolicy">
+ org.jboss.messaging.core.plugin.postoffice.cluster.NullMessagePullPolicy</attribute>
+<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>
+</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>
+</attribute>
+</mbean>
+ </programlisting>
+
+ <para>Relevant clustered Post Office configuration attributes are discussed below:</para>
+
+ <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.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.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.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><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>
+
+ <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
Added: trunk/docs/userguide-1.2/en/modules/CLUST_installation.xml
===================================================================
--- trunk/docs/userguide-1.2/en/modules/CLUST_installation.xml (rev 0)
+++ trunk/docs/userguide-1.2/en/modules/CLUST_installation.xml 2007-03-01 05:24:11 UTC (rev 2518)
@@ -0,0 +1,252 @@
+<chapter id="CLUST_installation">
+
+ <title>JBoss Messaging Clustering Installation</title>
+
+ <para>
+ Use the <filename>release-admin.xml</filename> ant script shipped with the release to
+ create individual cluster node configurations.
+ </para>
+
+ <para>
+ The typical usage is:
+ </para>
+
+ <programlisting>
+ ant -f release-admin.xml [-Did=node-id] [-Dports=port-config-label] cluster-node
+ </programlisting>
+
+ <para>
+ where:
+ <itemizedlist>
+ <listitem>
+ <filename>node-id</filename> is the unique node ID, an integer that must be unique per
+ cluster. If not specified, it defaults to 0.
+ </listitem>
+ <listitem>
+ <filename>port-config-label</filename> is a binding manager server configuration label.
+
+ The short story behind this parameter is the following: multiple application servers
+ running on the same physical machine need to use different service port ranges to avoid
+ port conflicts. You can configure the whole port range used by a server instance
+ by enabling a special service, the binding management service, and specifiying a
+ "server" configuration in the binding manager's configuration file, which will determine
+ specific port values to use when starting that instance.
+
+ The Messaging installation script can enable the service binding manager and performs
+ all configuration changes automatically. You only need to specify the "server"
+ configuration you want to use, as 'port-config-label'.
+
+ If you plan to run your clustering nodes on different physical machines, this parameter
+ is irrelevant, and you should not use it. However, if you install two (or more) nodes of
+ your cluster on the same physical machine, you need to give the value corresponding to
+ a specific "server" configurations in the binding manager configuration file. JBoss AS
+ ships "out-of-the-box" with several pre-configured port ranges: 'ports-default',
+ 'ports-01', 'ports-02', 'ports-03'. Use one of these.
+
+ If -Dports is not specified, the clustered instance created this way will fall over to
+ the default port range for a JBoss instace.
+
+ More details about the binding management service can be found in the Application Server
+ documentation, at the following address
+ <ulink url="http://docs.jboss.com/jbossas/guides/j2eeguide/r2/en/html_single/#ch10.bindingmanager">http://docs.jboss.com/jbossas/guides/j2eeguide/r2/en/html_single/#ch10.bindingmanager</ulink>
+ </listitem>
+ </itemizedlist>
+ </para>
+
+ <para>
+ For example, in order to create the configuration for a four-node cluster intended to run
+ on the same physical machine, use the following sequence:
+ </para>
+
+ <programlisting>
+ant -f release-admin.xml cluster-node
+ant -f release-admin.xml -Did=1 -Dports=ports-01 cluster-node
+ant -f release-admin.xml -Did=2 -Dports=ports-02 cluster-node
+ant -f release-admin.xml -Did=3 -Dports=ports-03 cluster-node
+ </programlisting>
+
+ <para>
+ The sequence will create four cluster node configurations ("messaging-node0",
+ "messaging-node1", "messaging-node2" and "messaging-node3").
+ </para>
+
+ <para>
+ The first command will create a cluster node with ID equals to '0' and using the
+ default JBoss AS port assignments.
+ </para>
+
+ <para>
+ <warning>
+ The configuration that has just been created uses a generic mysql service descriptor.
+
+ Check <filename>$JBOSS_HOME/server/messaging-node<id>/deploy/mysql-ds.xml</filename>
+ and verify that that:
+ <itemizedlist>
+ <listitem>1. Your database is indeed mysql.</listitem>
+ <listitem>2. It is accessible from every physical node you installed Messaging on.</listitem>
+ <listitem>3. Contains a schema (database/tablespace) named 'messaging'.</listitem>
+ <listitem>4. The URL (hostname and port), username and password are correct.</listitem>
+ <listitem>5. The installed mysql-driver.jar's version maches your database.</listitem>
+ </itemizedlist>
+ </warning>
+ </para>
+
+
+ <para>
+ To start the cluster, from four different terminals, run:
+ </para>
+
+ <programlisting>
+cd $JBOSS_HOME/bin
+./run.sh -c messaging-node0
+
+cd $JBOSS_HOME/bin
+./run.sh -c messaging-node1
+
+cd $JBOSS_HOME/bin
+./run.sh -c messaging-node2
+
+cd $JBOSS_HOME/bin
+./run.sh -c messaging-node3
+ </programlisting>
+
+
+ <para>
+ A successful two node cluster startup produces a log similar to:
+ </para>
+
+
+ <para>
+ Node 0:
+ </para>
+
+
+ <programlisting>
+...
+
+00:24:04,796 WARN [JDBCPersistenceManager]
+
+JBoss Messaging Warning: DataSource connection transaction isolation should be READ_COMMITTED, but it is currently REPEATABLE_READ.
+ Using an isolation level less strict than READ_COMMITTED may lead to data consistency problems.
+ Using an isolation level more strict than READ_COMMITTED may lead to deadlock.
+
+00:24:05,718 INFO [ServerPeer] JBoss Messaging 1.2.0.CR1 server [0] started
+00:24:06,328 INFO [STDOUT]
+-------------------------------------------------------
+GMS: address is 127.0.0.1:2452
+-------------------------------------------------------
+00:24:08,406 INFO [DefaultClusteredPostOffice] ClusteredPostOffice[0:Clustered JMS:127.0.0.1:2452] got new view [127.0.0.1:2452|0] [127.0.0.1:2452]
+00:24:08,468 INFO [STDOUT]
+-------------------------------------------------------
+GMS: address is 127.0.0.1:2455
+-------------------------------------------------------
+00:24:10,906 INFO [ConnectionFactory] Connector socket://10.11.14.105:4457 has leasing enabled, lease period 10000 milliseconds
+00:24:10,921 INFO [ConnectionFactory] [/ConnectionFactory, /XAConnectionFactory, java:/ConnectionFactory, java:/XAConnectionFactory] started
+00:24:10,953 INFO [QueueService] Queue[/queue/DLQ] started, fullSize=75000, pageSize=2000, downCacheSize=2000
+00:24:10,953 INFO [QueueService] Queue[/queue/ExpiryQueue] started, fullSize=75000, pageSize=2000, downCacheSize=2000
+00:24:10,953 INFO [TopicService] Topic[/topic/testTopic] started, fullSize=75000, pageSize=2000, downCacheSize=2000
+00:24:10,953 INFO [TopicService] Topic[/topic/securedTopic] started, fullSize=75000, pageSize=2000, downCacheSize=2000
+00:24:10,968 INFO [TopicService] Topic[/topic/testDurableTopic] started, fullSize=75000, pageSize=2000, downCacheSize=2000
+00:24:10,968 INFO [QueueService] Queue[/queue/testQueue] started, fullSize=75000, pageSize=2000, downCacheSize=2000
+00:24:10,968 INFO [QueueService] Queue[/queue/A] started, fullSize=75000, pageSize=2000, downCacheSize=2000
+00:24:10,968 INFO [QueueService] Queue[/queue/B] started, fullSize=75000, pageSize=2000, downCacheSize=2000
+00:24:10,968 INFO [QueueService] Queue[/queue/C] started, fullSize=75000, pageSize=2000, downCacheSize=2000
+00:24:10,968 INFO [QueueService] Queue[/queue/D] started, fullSize=75000, pageSize=2000, downCacheSize=2000
+00:24:10,968 INFO [QueueService] Queue[/queue/ex] started, fullSize=75000, pageSize=2000, downCacheSize=2000
+00:24:10,984 INFO [QueueService] Queue[/queue/PrivateDLQ] started, fullSize=75000, pageSize=2000, downCacheSize=2000
+00:24:10,984 INFO [QueueService] Queue[/queue/PrivateExpiryQueue] started, fullSize=75000, pageSize=2000, downCacheSize=2000
+00:24:10,984 INFO [QueueService] Queue[/queue/QueueWithOwnDLQAndExpiryQueue] started, fullSize=75000, pageSize=2000, downCacheSize=2000
+00:24:10,984 INFO [TopicService] Topic[/topic/TopicWithOwnDLQAndExpiryQueue] started, fullSize=75000, pageSize=2000, downCacheSize=2000
+00:24:10,984 INFO [QueueService] Queue[/queue/QueueWithOwnRedeliveryDelay] started, fullSize=75000, pageSize=2000, downCacheSize=2000
+00:24:10,984 INFO [TopicService] Topic[/topic/TopicWithOwnRedeliveryDelay] started, fullSize=75000, pageSize=2000, downCacheSize=2000
+00:24:11,000 INFO [QueueService] Queue[/queue/testDistributedQueue] started, fullSize=75000, pageSize=2000, downCacheSize=2000
+00:24:11,000 INFO [TopicService] Topic[/topic/testDistributedTopic] started, fullSize=75000, pageSize=2000, downCacheSize=2000
+00:24:11,093 INFO [ConnectionFactoryBindingService] Bound ConnectionManager 'jboss.jca:name=JmsXA,service=ConnectionFactoryBinding' to JNDI name 'java:JmsXA'
+00:24:11,375 INFO [TomcatDeployer] deploy, ctxPath=/jmx-console, warUrl=.../deploy/jmx-console.war/
+00:24:12,171 INFO [Http11BaseProtocol] Starting Coyote HTTP/1.1 on http-0.0.0.0-8080
+00:24:12,421 INFO [ChannelSocket] JK: ajp13 listening on /0.0.0.0:8009
+00:24:12,453 INFO [JkMain] Jk running ID=0 time=0/47 config=null
+00:24:12,515 INFO [Server] JBoss (MX MicroKernel) [4.0.5.GA (build: CVSTag=Branch_4_0 date=200611221632)] Started in 30s:375ms
+
+00:27:21,343 INFO [DefaultClusteredPostOffice] ClusteredPostOffice[0:Clustered JMS:127.0.0.1:2452] got new view [127.0.0.1:2452|1] [127.0.0.1:2452, 127.0.0.1:2474]
+
+</programlisting>
+
+ <para>
+ Node 1:
+ </para>
+
+ <programlisting>
+
+...
+
+00:33:54,468 WARN [JDBCPersistenceManager]
+
+JBoss Messaging Warning:
+ DataSource connection transaction isolation should be READ_COMMITTED, but it is
+ currently REPEATABLE_READ.
+ Using an isolation level less strict than READ_COMMITTED may lead to data consistency
+ problems.
+ Using an isolation level more strict than READ_COMMITTED may lead to deadlock.
+
+00:33:55,062 INFO [ServerPeer] JBoss Messaging 1.2.0.CR1 server [1] started
+00:33:55,609 INFO [STDOUT]
+-------------------------------------------------------
+GMS: address is 127.0.0.1:2514
+-------------------------------------------------------
+00:33:57,734 INFO [DefaultClusteredPostOffice] ClusteredPostOffice[1:Clustered JMS:127.0.0.1:2514] got new view [127.0.0.1:2452|3] [127.0.0.1:2452, 127.0.0.1:2514]
+00:33:57,765 INFO [STDOUT]
+-------------------------------------------------------
+GMS: address is 127.0.0.1:2519
+-------------------------------------------------------
+00:34:00,203 INFO [ConnectionFactory] Connector socket://10.11.14.105:4557 has leasing enabled,
+ lease period 20000 milliseconds
+00:34:00,203 INFO [ConnectionFactory] [/ConnectionFactory, /XAConnectionFactory,
+ java:/ConnectionFactory, java:/XAConnectionFactory] started
+00:34:00,234 INFO [QueueService] Queue[/queue/DLQ] started, fullSize=75000, pageSize=2000,
+ downCacheSize=2000
+00:34:00,234 INFO [QueueService] Queue[/queue/ExpiryQueue] started, fullSize=75000, pageSize=2000,
+ downCacheSize=2000
+00:34:00,234 INFO [TopicService] Topic[/topic/testTopic] started, fullSize=75000, pageSize=2000,
+ downCacheSize=2000
+00:34:00,250 INFO [TopicService] Topic[/topic/securedTopic] started, fullSize=75000, pageSize=2000,
+ downCacheSize=2000
+00:34:00,250 INFO [TopicService] Topic[/topic/testDurableTopic] started, fullSize=75000, pageSize=2000,
+ downCacheSize=2000
+00:34:00,250 INFO [QueueService] Queue[/queue/testQueue] started, fullSize=75000, pageSize=2000,
+ downCacheSize=2000
+00:34:00,250 INFO [QueueService] Queue[/queue/A] started, fullSize=75000, pageSize=2000, downCacheSize=2000
+00:34:00,250 INFO [QueueService] Queue[/queue/B] started, fullSize=75000, pageSize=2000, downCacheSize=2000
+00:34:00,250 INFO [QueueService] Queue[/queue/C] started, fullSize=75000, pageSize=2000, downCacheSize=2000
+00:34:00,250 INFO [QueueService] Queue[/queue/D] started, fullSize=75000, pageSize=2000, downCacheSize=2000
+00:34:00,250 INFO [QueueService] Queue[/queue/ex] started, fullSize=75000, pageSize=2000, downCacheSize=2000
+00:34:00,265 INFO [QueueService] Queue[/queue/PrivateDLQ] started, fullSize=75000, pageSize=2000,
+ downCacheSize=2000
+00:34:00,265 INFO [QueueService] Queue[/queue/PrivateExpiryQueue] started, fullSize=75000, pageSize=2000,
+ downCacheSize=2000
+00:34:00,265 INFO [QueueService] Queue[/queue/QueueWithOwnDLQAndExpiryQueue] started, fullSize=75000,
+ pageSize=2000, downCacheSize=2000
+00:34:00,265 INFO [TopicService] Topic[/topic/TopicWithOwnDLQAndExpiryQueue] started, fullSize=75000,
+ pageSize=2000, downCacheSize=2000
+00:34:00,265 INFO [QueueService] Queue[/queue/QueueWithOwnRedeliveryDelay] started, fullSize=75000,
+ pageSize=2000, downCacheSize=2000
+00:34:00,265 INFO [TopicService] Topic[/topic/TopicWithOwnRedeliveryDelay] started, fullSize=75000,
+ pageSize=2000, downCacheSize=2000
+00:34:00,296 INFO [QueueService] Queue[/queue/testDistributedQueue] started, fullSize=75000, pageSize=2000,
+ downCacheSize=2000
+00:34:00,296 INFO [TopicService] Topic[/topic/testDistributedTopic] started, fullSize=75000, pageSize=2000,
+ downCacheSize=2000
+00:34:00,343 INFO [ConnectionFactoryBindingService] Bound ConnectionManager 'jboss.jca:name=JmsXA,
+ service=ConnectionFactoryBinding' to JNDI name 'java:JmsXA'
+00:34:00,453 INFO [TomcatDeployer] deploy, ctxPath=/jmx-console, warUrl=.../deploy/jmx-console.war/
+00:34:00,796 INFO [Http11BaseProtocol] Starting Coyote HTTP/1.1 on http-0.0.0.0-8180
+00:34:01,078 INFO [ChannelSocket] JK: ajp13 listening on /0.0.0.0:8109
+00:34:01,125 INFO [JkMain] Jk running ID=0 time=0/125 config=null
+00:34:01,125 INFO [Server] JBoss (MX MicroKernel) [4.0.5.GA (build: CVSTag=Branch_4_0 date=200611221632)]
+ Started in 22s:547ms
+
+
+ </programlisting>
+
+
+</chapter>
Added: trunk/docs/userguide-1.2/en/modules/CLUST_introduction.xml
===================================================================
--- trunk/docs/userguide-1.2/en/modules/CLUST_introduction.xml (rev 0)
+++ trunk/docs/userguide-1.2/en/modules/CLUST_introduction.xml 2007-03-01 05:24:11 UTC (rev 2518)
@@ -0,0 +1,125 @@
+<chapter id="CLUST_introduction">
+
+ <title>Introduction</title>
+
+ <para>
+ JBoss Messaging 1.2 GA will provide a highly sophisticated clustering implementation, far
+ more sophisticated than you'll find in the vast majority of other messaging systems.
+ </para>
+ <para>
+ It will allow you to smoothly distribute your application load across your cluster,
+ intelligently balancing and utilizing each nodes CPU cycles, with no single point of failure,
+ providing a highly scalable and performant clustering implementation.
+ </para>
+
+ <section id="c_features">
+ <title>JBoss Messaging 1.2 GA features:</title>
+
+ <para>
+ JBoss Messaging 1.2 GA Clustering will provide the following features:
+ </para>
+
+ <itemizedlist>
+ <listitem>
+ <para>
+ Distributed queues. Messages sent to a distributed queue while attached to a
+ particular node will be routed to a queue instance on a particular node according
+ to a routing policy.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ Distributed topics. Messages sent to a distributed topic while attached at a
+ particular node will be received by subscriptions on other nodes.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ Fully reliable message distribution. Once and only once delivery is fully guaranteed.
+ When sending messages to a topic with multiple durable subscriptions
+ across a cluster we guarantee that message reaches all the subscriptions
+ (or none of them in case of failure).
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ Persistent level reliability guarantee without persistence! By replicating persistent messages between nodes in memory,
+ we can obtain comparable reliability levels to persistenting messages to disk, without actually storing them to disk.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ Pluggable routing implementation. The policy for routing messages to a queue is fully pluggable and easily replaceable.
+ The default policy always chooses a queue at the local node if there is one, and if not, it round robins between queues on different nodes.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ Intelligent message redistribution policy. Messages are automatically distributed between nodes depending on how fast or slow consumers are on certain nodes.
+ If there are no or slow consumers on a particular queue node, messages will be pulled from that queue to a queue with faster consumers on a different node.
+ The policy is fully pluggable.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ Shared durable subscriptions. Consumers can connect to the same durable subscription while attached to different nodes.
+ This allows processing load from durable subscriptions to be distributed across the cluster in a similar way to queues.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ High availability and seamless failover.
+ If the node you are connected to fails, you will automatically fail over to another node and will not lose any
+ persistent messages.
+ You can carry on with your session seamlessly where you left off.
+ Once and only once delivery of persistent messages is respected at all times.
+ </para>
+ </listitem>
+ </itemizedlist>
+
+
+ </section>
+
+ <section id="alphafeatures">
+ <title>JBoss Messaging 1.2.0.CR1 features:</title>
+
+ <para> What's in the CR1 release?</para>
+
+ <para>
+ JBoss Messaging 1.2.0.CR1 contains all features planned for the GA release, with the exception
+ of the "unreliable link scenario" (http://jira.jboss.org/jira/browse/JBMESSAGING-676),
+ whose development is still on-going on a parallel branch.
+ </para>
+
+ <para>
+ Please note that this is a candidate release and it possible to contain bugs!
+ We are releasing it to the community, so you can try it out, get familiar with it
+ and feedback your experiences to us so we can improve it and stabilise it.
+ </para>
+
+ <para>
+ Thanks for your support!
+ </para>
+
+ <para>
+ All the final features are available apart from:
+ </para>
+
+ <itemizedlist>
+ <listitem>
+ <para>
+ Persistent level reliability guarantee without persistence. There is no option for
+ in memory replication of persistent messages in this release.
+ </para>
+ </listitem>
+
+ </itemizedlist>
+
+ <para>
+ Bear in mind you will need to get a bit more "down and dirty" with the configuration in
+ this release, than you would with a GA release.
+ </para>
+
+ </section>
+
+</chapter>
Added: trunk/docs/userguide-1.2/en/modules/CLUST_overview.xml
===================================================================
--- trunk/docs/userguide-1.2/en/modules/CLUST_overview.xml (rev 0)
+++ trunk/docs/userguide-1.2/en/modules/CLUST_overview.xml 2007-03-01 05:24:11 UTC (rev 2518)
@@ -0,0 +1,135 @@
+<chapter id="CLUST_overview">
+
+ <title>Clustering overview</title>
+
+ <section id="description">
+ <title>JBoss Messaging Clustering Overview</title>
+
+ <para>
+ Here's a brief overview of how clustering works in JBoss Messaging 2.0.
+ </para>
+
+ <para>As mentioned in the previous chapter, please note that not all this functionality is
+ available in this release.
+ </para>
+
+ <para>
+ Clustered destinations (queues and topics) can be deployed at all or none of the nodes of
+ the cluster.
+ </para>
+
+ <para>
+ A JMS client uses HA JNDI to lookup the connection factory. A client side load balancing
+ policy will automatically chose a node to connect to (This is similar to
+ how EJB clustering chooses a node).
+ </para>
+
+ <para>
+ The JMS client has now made a connection to a node where it can create sessions, message
+ producers and message consumers and browsers and send or consume messages,
+ using the standard JMS api.
+ </para>
+
+ <para>
+ When a distributed queue is deployed across the cluster, individual partial queues are
+ deployed on each node.
+ </para>
+
+ <para>
+ When a message is sent from a message producer attached to a particular node to a
+ distributed quueue, a routing policy determines which partial queue will receive
+ the message.
+ </para>
+
+ <para>
+ By default the router will always pass the message to a local queue, if there is one,
+ this is so we avoid unnecessary network traffic.
+ </para>
+
+ <para>
+ If there is no local queue then a partial queue on a different node will be chosen by the
+ router, by default this will be round robin between remote partial queues.
+ </para>
+
+ <para>
+ When a message is sent to a distributed topic while attached to a node, there may be
+ multiple subscriptions on different nodes that need to receive the
+ message. Depending on the number and location of subscriptions, the message may be multicast
+ or unicast across the cluster so the other nodes can pick it up.
+ </para>
+
+ <para>
+ All group communication, unicast, multicast and group management is handled by JGroups.
+ </para>
+
+ <para>
+ In the case of shared durable subscriptions, if a durable subscription with the same name
+ exists on more than node, then only one of the instances needs to receive the message.
+ </para>
+
+ <para>Which one is determined by the same routing policy used to route messages to partial queues.</para>
+
+ <para>
+ All of this is accomplished without losing the reliability guarantees required by JMS.
+ </para>
+
+ <para>
+ Subscriptions (both durable and non durable) can be created on all nodes and will receive messages sent via any node.
+ </para>
+
+ <para>
+ What happens if the consumers on one queue/subscription are faster/slower than consumers on another?
+ </para>
+
+ <para>
+ Normally this would result in messages building up on that queue and fast consumers being starved of work on another, thus wasting CPU cycles on the node that
+ could be put to good use.
+ </para>
+
+ <para>
+ The most degenerate example is of a queue containing many messages then the consumers being closed on that queue.
+
+ The messages might potentially remain stranded on the queue until another consumer attaches.
+ </para>
+
+ <para>
+ A routing policy is no use here, since the messages have already been routed to the queuee and the consumers closed / slowed down
+ after they were routed there.
+
+ </para>
+
+ <para>
+ JBoss Messaging deals with this problem by intelligently pulling messages from other less
+ busy nodes, if it detects idle consumers on the fast node and slow consumers
+ on another node.
+ </para>
+
+ <para>
+ Another feature (not available in CR1) that will enable very fast, very scalable reliable
+ messaging without using databases is in memory replication of reliable messages.
+ </para>
+
+ <para>
+ Normally, persistent messages are persisted in a shared database which is shared by all nodes
+ in the cluster.
+
+ JBoss Messaging 2.0.GA will contain
+ an option where you can choose to not persist persistent messages in a database, but instead to replicate them between nodes of the cluster.
+ </para>
+
+ <para>
+ The idea here is the network IO on a fast network should be much faster than persisting to disk.
+ </para>
+
+ <para>
+ This solution should also be more scalable since different nodes replicate their messages onto
+ different other nodes - there is no "master node".
+ </para>
+
+ <para>
+ If the messages are replicated onto sufficient nodes and the hardware is set-up with UPS, then we believe a comparable reliability guarantee to persisting messages to disk
+ can be achieved. Of course, this won't be suitable for all situations, but you use the best tool for the job.
+ </para>
+
+ </section>
+</chapter>
Added: trunk/docs/userguide-1.2/en/modules/UG2_about.xml
===================================================================
--- trunk/docs/userguide-1.2/en/modules/UG2_about.xml (rev 0)
+++ trunk/docs/userguide-1.2/en/modules/UG2_about.xml 2007-03-01 05:24:11 UTC (rev 2518)
@@ -0,0 +1,43 @@
+<chapter id="UG2_about">
+
+ <title>Introducing JBoss Messaging Release 1.2.0.GA</title>
+
+ <para>JBoss Messaging is a high performance JMS provider in the JBoss Enterprise Middleware Stack (JEMS). It is a complete rewrite of JBossMQ, which is the current default JMS provider in JBoss AS 4.x. JBoss Messaging will be the default JMS provider in JBoss AS 5.x and later, and it is the backbone of the JBoss ESB infrastructure.</para>
+
+ <para>Compared with JBossMQ, JBoss Messaging offers vastly improved performance in both single node and clustered environments. Please see <ulink url="http://wiki.jboss.org/wiki/Wiki.jsp?page=JBossMessagingPerformanceResultsPre1_0">this wiki page</ulink> for performance benchmarks and <xref linkend="UG2_performance"/> on how to generate your own performance benchmarks. It also features a much better internal architecture that would allow us to add more features in the future.</para>
+
+ <para>While JBoss Messaging only becomes the default JMS provider from JBoss AS 5.x, production users on JBoss AS 4.x can still take advantage of the performance improvements by easily replacing the JBossMQ module with JBoss Messaging.</para>
+
+ <para>In this guide, we discuss how to install and use JBoss Messaging in JBoss 4.x production servers. We cover JBoss Messaging-specific configuration options, as well as how to run the build-in sanity / performance tests.</para>
+
+ <para>
+ This guide is work in progress. Please send your suggestions or comments to the
+ <ulink url="http://www.jboss.org/index.html?module=bb&op=viewforum&f=238">JBoss Messaging user forum</ulink>.
+ </para>
+
+ <para>
+ <emphasis role="bold">Team:</emphasis>
+ </para>
+
+ <para>
+ Ovidiu Feodorov, Project Lead
+ </para>
+
+ <para>
+ Tim Fox, Core Messaging Developer
+ </para>
+
+ <para>
+ Luc Texier, Lead Support EMEA
+ </para>
+
+ <para>
+ Sam Griffith Jr., Docs Team
+ </para>
+
+ <para>
+ Other contributions by: Adrian Brock, Bela Ban, Alex Fu, Aaron Walker
+ </para>
+
+
+</chapter>
Added: trunk/docs/userguide-1.2/en/modules/UG2_configuration.xml
===================================================================
--- trunk/docs/userguide-1.2/en/modules/UG2_configuration.xml (rev 0)
+++ trunk/docs/userguide-1.2/en/modules/UG2_configuration.xml 2007-03-01 05:24:11 UTC (rev 2518)
@@ -0,0 +1,704 @@
+<chapter id="UG2_configuration">
+ <title>Configuration</title>
+
+ <para>The JMS API specifies how a messaging client interacts with a messaging server. The exact definition and implementation of messaging services, such as message destinations and connection factories, are specific to JMS providers. JBoss Messaging has its own configuration files to configure services. If you are migrating services from JBossMQ (or other JMS provider) to JBoss Messaging, you will need to understand those configuration files.</para>
+
+ <para>In this chapter, we discuss how to configure various services inside JBoss Messaging, which work together to provide JMS API level
+ services to client applications.</para>
+
+ <para>
+ Starting with the JBoss Messaging 1.0.1 release, the service configuration is spread among several configuration files.
+ (The 1.0.0 release used to have all configuration information lumped together in the SAR's deployment
+ descriptor <filename>jboss-messaging.sar/META-INF/jboss-service.xml</filename>). Depending
+ on the functionality provided by the services it configures, the configuration data is
+ distributed between
+ <filename>messaging-service.xml</filename>,
+ <filename>remoting-service.xml</filename>,
+ <filename>xxx-persistence-service.xml</filename>,
+ <filename>connection-factories-service.xml</filename> and
+ <filename>destinations-service.xml</filename>.
+ </para>
+
+ <para>
+ The AOP client-side and server-side interceptor stacks are configured in
+ <filename>aop-messaging-client.xml</filename> and <filename>aop-messaging-server.xml</filename>.
+ </para>
+
+ <section id="conf.serverpeer">
+ <title>Configuring the Server</title>
+
+ <para>
+ The Server Peer is the "heart" of the JBoss Messaging JMS facade. The server's configuration,
+ together with the configuration of several core plug-ins (ThreadPool and the
+ MessageStore), resides in <filename>messaging-service.xml</filename> configuration file.
+ </para>
+
+
+ <para>An example of a Server Peer configuration is presented below</para>
+
+ <programlisting>
+
+<mbean code="org.jboss.jms.server.ServerPeer"
+ name="jboss.messaging:service=ServerPeer"
+ xmbean-dd="xmdesc/ServerPeer-xmbean.xml">
+
+ <constructor>
+ <!-- ServerPeerID -->
+ <arg type="java.lang.String" value="server.0"/>
+ <!-- DefaultQueueJNDIContext -->
+ <arg type="java.lang.String" value="/queue"/>
+ <!-- DefaultTopicJNDIContext -->
+ <arg type="java.lang.String" value="/topic"/>
+ </constructor>
+
+ <depends optional-attribute-name="ThreadPool">jboss.messaging:service=ThreadPool</depends>
+ <depends optional-attribute-name="PersistenceManager"
+ >jboss.messaging:service=PersistenceManager</depends>
+ <depends optional-attribute-name="MessageStore">jboss.messaging:service=MessageStore</depends>
+ <depends optional-attribute-name="ChannelMapper">jboss.messaging:service=ChannelMapper</depends>
+
+ <!-- Set to -1 to completely disable client leasing -->
+ <attribute name="SecurityDomain">java:/jaas/messaging</attribute>
+ <attribute name="DefaultSecurityConfig">
+ <security>
+ <role name="guest" read="true" write="true" create="true"/>
+ </security>
+ </attribute>
+ </mbean>
+
+ </programlisting>
+
+ <section id="conf.serverpeer.securitydomain">
+ <title>SecurityDomain</title>
+
+ <para>
+ This identifies the JBoss security domain that will be used when JBoss Messaging
+ authenticates and authorises access to JMS destinations for reading, writing or
+ creating.
+ </para>
+
+ <para>
+ It should correspond to a entry in <filename>login-config.xml</filename> where
+ it is configured in exactly the same way as any other security domain in JBoss.
+ </para>
+ </section>
+
+ <section id="conf.serverpeer.defaultsecurity">
+ <title>DefaultSecurityConfig</title>
+
+ <para>
+ Default security configuration is used when the security configuration for a specific
+ queue or topic has not been overridden in the destination's deployment descriptor.
+ It has exactly the same syntax and semantics as in JBossMQ.
+ </para>
+
+ <para>
+ The <literal>DefaultSecurityConfig</literal> attribute element should contain
+ one <literal><security></literal> element.
+ The <literal><security></literal> element can contain multiple
+ <literal><role></literal> elements. Each <literal><role></literal>
+ element defines the default access for that particular role.
+ </para>
+
+ <para>
+ If the <literal>read</literal> attribute is <literal>true</literal> then that role
+ will be able to read (create consumers, receive messaages or browse) destinations
+ by default.
+ </para>
+
+ <para>
+ If the <literal>write</literal> attribute is <literal>true</literal> then that role
+ will be able to write (create producers or send messages) to destinations by default.
+ </para>
+
+ <para>
+ If the <literal>create</literal> attribute is <literal>true</literal> then that role
+ will be able to create durable subscriptions on topics by default.
+ </para>
+ </section>
+ </section>
+
+
+ <section id="conf.persistence">
+ <title>Configuring Persistence</title>
+
+ <para>
+ JBoss Messaging interacts with a persistent store via two services: the Persistence Manager
+ and the Channel Mapper. The Persistence Manager is used to handle the message-related
+ functions. The Channel Mapper manages destination-related persistent
+ data.
+ </para>
+
+ <para>
+ JBoss Messaging ships with a JDBC Persistence Manager used for handling persistence of
+ message data in a relational database accessed via JDBC. The Persistence Manager
+ implementation is pluggable (the Persistence Manager is a Messaging server plug-in),
+ this making possible to provide other implementations for persisting message data in
+ non relational stores, file stores etc.
+ </para>
+
+ <para>
+ The configuration of "persistent" services is grouped in a
+ <filename>xxx-persistence-service.xml</filename> file, where the actual file prefix is
+ usually inferred from its corresponding database JDBC connection string. By default,
+ Messaging ships with a <filename>hsqldb-persistence-service.xml</filename>, which configures
+ the Messaging server to use the in-VM Hypersonic database instance that comes by default
+ with any JBossAS instance.
+ </para>
+
+ <warning>
+ <para>
+ The default Persistence Manager configuration is works out of the box with Hypersonic,
+ however it must be stressed that Hypersonic should not be used in a production environment
+ mainly due to its limited support for transaction isolation and its propensity to behave
+ erratically under high load.
+ </para>
+ <para>
+ The
+ <ulink url="http://wiki.jboss.org/wiki/Wiki.jsp?page=ConfigJBossMQDB">Critique of Hypersonic</ulink>
+ wiki page outlines some of the well-known issues occuring when using this database.
+ </para>
+ </warning>
+
+ <para>
+ JBoss Messaging also ships with pre-made Persistence Manager configurations for MySQL,
+ Oracle, PostgreSQL and Sybase. The example <filename>mysql-persistence-service.xml</filename>,
+ <filename>oracle-persistence-service.xml</filename>,
+ <filename>postgres-persistence-service.xml</filename> and
+ <filename>sybase-persistence-service.xml</filename> configuration files are available
+ in the <filename>examples/config</filename> directory of the release bundle.
+ </para>
+
+ <para>
+ Configurations for MSSQL and other popular databases should be available soon. Users are
+ encouraged to contribute their own configuration files. The JDBC Persistence Manager has been designed
+ to use standard SQL for the DML so writing a JDBC Persistence Manager configuration for another
+ database is usually only a fairly simple matter of changing DDL in the configuration
+ which is likely to be different for different databases.
+ </para>
+
+ <para>
+ The default Hypersonic persistence configuration file is listed below:
+ </para>
+
+ <programlisting>
+<server>
+ <mbean code="org.jboss.messaging.core.plugin.JDBCPersistenceManager"
+ name="jboss.messaging:service=PersistenceManager"
+ xmbean-dd="xmdesc/JDBCPersistenceManager-xmbean.xml">
+ <depends>jboss.jca:service=DataSourceBinding,name=DefaultDS</depends>
+ <depends optional-attribute-name="TransactionManager">
+ jboss:service=TransactionManager</depends>
+ <depends optional-attribute-name="ChannelMapper">
+ jboss.messaging:service=ChannelMapper</depends>
+ <attribute name="DataSource">java:/DefaultDS</attribute>
+ <attribute name="CreateTablesOnStartup">true</attribute>
+ <attribute name="UsingBatchUpdates">true</attribute>
+ </mbean>
+
+ <mbean code="org.jboss.jms.server.plugin.JDBCChannelMapper"
+ name="jboss.messaging:service=ChannelMapper"
+ xmbean-dd="xmdesc/JDBCChannelMapper-xmbean.xml">
+ <depends>jboss.jca:service=DataSourceBinding,name=DefaultDS</depends>
+ <depends optional-attribute-name="TransactionManager">
+ jboss:service=TransactionManager</depends>
+ <attribute name="DataSource">java:/DefaultDS</attribute>
+ </mbean>
+</server>
+ </programlisting>
+
+ <para>
+ An example of a Persistence Manager configuration for a MySQL database follows:
+ </para>
+
+ <programlisting>
+<server>
+ <mbean code="org.jboss.messaging.core.plugin.JDBCPersistenceManager"
+ name="jboss.messaging:service=PersistenceManager"
+ xmbean-dd="xmdesc/JDBCPersistenceManager-xmbean.xml">
+ <depends>jboss.jca:service=DataSourceBinding,name=DefaultDS</depends>
+ <depends optional-attribute-name="TransactionManager">
+ jboss:service=TransactionManager</depends>
+ <depends optional-attribute-name="ChannelMapper">
+ jboss.messaging:service=ChannelMapper</depends>
+ <attribute name="DataSource">java:/DefaultDS</attribute>
+ <attribute name="CreateTablesOnStartup">true</attribute>
+ <attribute name="UsingBatchUpdates">true</attribute>
+ <attribute name="SqlProperties"><![CDATA[
+CREATE_MESSAGE_REF=CREATE TABLE JMS_MESSAGE_REFERENCE
+ (CHANNELID BIGINT, MESSAGEID BIGINT, TRANSACTIONID BIGINT, STATE CHAR(1),
+ ORD BIGINT, DELIVERYCOUNT INTEGER, RELIABLE CHAR(1), LOADED CHAR(1),
+ PRIMARY KEY(CHANNELID, MESSAGEID))
+CREATE_IDX_MESSAGE_REF_TX=CREATE INDEX JMS_MESSAGE_REF_TX ON
+ JMS_MESSAGE_REFERENCE (TRANSACTIONID)
+CREATE_IDX_MESSAGE_REF_ORD=CREATE INDEX JMS_MESSAGE_REF_ORD ON JMS_MESSAGE_REFERENCE (ORD)
+CREATE_IDX_MESSAGE_REF_MESSAGEID=CREATE INDEX JMS_MESSAGE_REF_MESSAGEID ON
+ JMS_MESSAGE_REFERENCE (MESSAGEID)
+CREATE_IDX_MESSAGE_REF_LOADED=CREATE INDEX JMS_MESSAGE_REF_LOADED ON
+ JMS_MESSAGE_REFERENCE (LOADED)
+CREATE_IDX_MESSAGE_REF_RELIABLE=CREATE INDEX JMS_MESSAGE_REF_RELIABLE ON
+ JMS_MESSAGE_REFERENCE (RELIABLE)
+INSERT_MESSAGE_REF=INSERT INTO JMS_MESSAGE_REFERENCE (CHANNELID, MESSAGEID,
+ TRANSACTIONID, STATE, ORD, DELIVERYCOUNT, RELIABLE, LOADED)
+ VALUES (?, ?, ?, ?, ?, ?, ?, ?)
+.... ]]>
+ </attribute>
+ <attribute name="MaxParams">500</attribute>
+ </mbean>
+
+ <mbean code="org.jboss.jms.server.plugin.JDBCChannelMapper"
+ name="jboss.messaging:service=ChannelMapper"
+ xmbean-dd="xmdesc/JDBCChannelMapper-xmbean.xml">
+ <depends>jboss.jca:service=DataSourceBinding,name=DefaultDS</depends>
+ <depends optional-attribute-name="TransactionManager">
+ jboss:service=TransactionManager</depends>
+ <attribute name="DataSource">java:/DefaultDS</attribute>
+ <attribute name="SqlProperties"><![CDATA[
+CREATE_USER_TABLE=CREATE TABLE JMS_USER (USERID VARCHAR(32) NOT NULL,
+ PASSWD VARCHAR(32) NOT NULL, CLIENTID VARCHAR(128), PRIMARY KEY(USERID))
+CREATE_ROLE_TABLE=CREATE TABLE JMS_ROLE (ROLEID VARCHAR(32) NOT NULL,
+ USERID VARCHAR(32) NOT NULL, PRIMARY KEY(USERID, ROLEID))
+SELECT_PRECONF_CLIENTID=SELECT CLIENTID FROM JMS_USER WHERE USERID=?
+....
+ ]]>
+ </attribute>
+ </mbean>
+</server>
+ </programlisting>
+
+ <section id="conf.changingds">
+ <title>Changing the Database</title>
+
+ <para>
+ If the database you want to switch to is one of MySQL, Oracle or Postgres,
+ persistence configuration files are already available in
+ the <filename>examples/config</filename> directory of the release bundle.
+ </para>
+
+ <para>
+ In order to enable support for one of these databases, just replace the default
+ <filename>hsqldb-persistence-service.xml</filename> configuration file with the
+ database-specific configuration file and restart the server.
+ </para>
+
+ <para>
+ Also, be aware that by default, the Messaging services relying on a datastore
+ are referencing <literal>"java:/DefaultDS"</literal> for the datasource.
+ If you are deploying a datasource with a different JNDI name, you need to update
+ all the <literal>DataSource</literal> attribute in the persistence configuration file.
+ </para>
+
+ </section>
+
+ <section id="conf.persistence.createtables">
+ <title>CreateTablesOnStartup</title>
+
+ <para>
+ Set this to <literal>true</literal> if you wish the Persistence Manager to attempt
+ to create the tables (and indexes) when it starts. If the tables (or indexes)
+ already exist a <literal>SQLException</literal> will be thrown by the JDBC driver and
+ ignored by the Persistence Manager, allowing it to continue.
+ </para>
+ <para>
+ By default the value of <literal>CreateTablesOnStartup</literal> attribute
+ is set to <literal>true</literal>
+ </para>
+ </section>
+
+ <section id="conf.persistence.batchupdates">
+ <title>UsingBatchUpdates</title>
+
+ <para>
+ Set this to <literal>true</literal> if the database supports JDBC batch updates.
+ The JDBC Persistence Manager will then group multiple database updates in batches
+ to aid performance.
+ </para>
+ <para>
+ By default the value of <literal>UsingBatchUpdates</literal> attribute
+ is set to <literal>false</literal>
+ </para>
+ </section>
+
+ <section id="conf.persistence.sqlproperties">
+ <title>SQLProperties</title>
+
+ <para>
+ This is where the DDL and DML for the particular database is specified.
+ If a particular DDL or DML statement is not overridden, the default Hypersonic
+ configuration will be used for that statement.
+ </para>
+ </section>
+
+ </section>
+
+ <section id="conf.destination">
+ <title>Configuring Destinations</title>
+
+ <section id="conf.preconf.destinations">
+ <title>Pre-configured destinations</title>
+
+ <para>
+ JBoss Messaging ships with a default set of pre-configured destinations that will be
+ deployed during the server start up. The file that contains configuration for these
+ destinations is <filename>destinations-service.xml</filename>. A section of
+ this file is listed below:
+ </para>
+
+ <programlisting>
+
+<!-- The Dead Letter Queue. This destination is a dependency of an EJB MDB container -->
+
+<mbean code="org.jboss.jms.server.destination.Queue"
+ name="jboss.messaging.destination:service=Queue,name=DLQ"
+ xmbean-dd="xmdesc/Queue-xmbean.xml">
+ <depends optional-attribute-name="ServerPeer">
+ jboss.messaging:service=ServerPeer</depends>
+</mbean>
+
+....
+
+<mbean code="org.jboss.jms.server.destination.Topic"
+ name="jboss.messaging.destination:service=Topic,name=testTopic"
+ xmbean-dd="xmdesc/Topic-xmbean.xml">
+ <depends optional-attribute-name="ServerPeer">
+ jboss.messaging:service=ServerPeer</depends>
+ <attribute name="SecurityConfig">
+ <security>
+ <role name="guest" read="true" write="true"/>
+ <role name="publisher" read="true" write="true" create="false"/>
+ <role name="durpublisher" read="true" write="true" create="true"/>
+ </security>
+ </attribute>
+</mbean>
+
+....
+
+<mbean code="org.jboss.jms.server.destination.Queue"
+ name="jboss.messaging.destination:service=Queue,name=testQueue"
+ xmbean-dd="xmdesc/Queue-xmbean.xml">
+ <depends optional-attribute-name="ServerPeer">
+ jboss.messaging:service=ServerPeer</depends>
+ <attribute name="SecurityConfig">
+ <security>
+ <role name="guest" read="true" write="true"/>
+ <role name="publisher" read="true" write="true" create="false"/>
+ <role name="noacc" read="false" write="false" create="false"/>
+ </security>
+ </attribute>
+</mbean>
+
+....
+ </programlisting>
+
+ </section>
+
+ <section id="conf.destination.config.paramters">
+ <title>Destination Configuration Parameters</title>
+
+ <section id="conf.destination.security">
+ <title>Destination Security Configuration</title>
+
+ <para>
+ <literal>SecurityConfig</literal> - allows you to determine which roles are allowed
+ to read, write and create on the destination. It has exactly the same syntax and
+ semantics as the security configuration in JBossMQ destinations.
+ </para>
+
+ <para>
+ The <literal>SecurityConfig</literal> element should contain one
+ <literal><security></literal> element. The <literal><security></literal>
+ element can contain multiple <literal><role></literal> elements.
+ Each <literal><role></literal> element defines the access for that
+ particular role.
+ </para>
+
+ <para>
+ If the <literal>read</literal> attribute is <literal>true</literal> then that role
+ will be able to read (create consumers, receive messaages or browse) this destination.
+ </para>
+
+ <para>
+ If the <literal>write</literal> attribute is <literal>true</literal> then that role
+ will be able to write (create producers or send messages) to this destination.
+ </para>
+
+ <para>
+ If the <literal>create</literal> attribute is <literal>true</literal> then that role
+ will be able to create durable subscriptions on this destination.
+ </para>
+
+ <para>
+ Note that the security configuration for a destination is optional. If a
+ <literal>SecurityConfig</literal> element is not specifed then the default
+ security configuration from the Server Peer will be used.
+ </para>
+ </section>
+
+ <section id="conf.destination.paging">
+ <title>Destination paging parameters</title>
+
+ <para>
+ 'Pageable Channels' are a sophisticated new feature available in JBoss Messaging.
+ </para>
+
+ <para>
+ If your application needs to support very large queues or subscriptions containing
+ potentially millions of messages, then it's not possible to store them all in
+ memory at once.
+ </para>
+
+ <para>
+ JBoss Messaging solves this problem but letting you specify the
+ maximum number of messages that can be stored in memory at any one time,
+ on a queue-by-queue, or topic-by-topic basis. JBoss Messaging then pages messages
+ to and from storage transparently in blocks, allowing queues and subscriptions to
+ grow to very large sizes without any performance degradation as channel size increases.
+ </para>
+
+ <para>
+ This has been tested with in excess of 10 million 2K messages on very basic hardware
+ and has the potential to scale to much larger number of messages.
+ </para>
+
+ <para>
+ The individual parameters are:
+ </para>
+
+ <para>
+ <literal>FullSize</literal> - this is the maximum number of messages held by the
+ queue or topic subscriptions in memory at any one time. The actual queue or
+ subscription can hold many more messages than this but these are paged to and
+ from storage as necessary as messages are added or consumed.
+ </para>
+
+ <para>
+ <literal>PageSize</literal> - When loading messages from the queue or subscrition
+ this is the maximum number of messages to pre-load in one operation.
+ </para>
+
+ <para>
+ <literal>DownCacheSize</literal> - When paging messages to storage from the queue
+ they first go into a "Down Cache" before being written to storage. This enables the
+ write to occur as a single operation thus aiding performance. This setting determines
+ the max number of messages that the Down Cache will hold before they are flushed
+ to storage.
+ </para>
+
+ <para>
+ If no values for <literal>FullSize</literal>, <literal>PageSize</literal>,
+ or <literal>DownCacheSize</literal> are specified they will default to values
+ 75000, 2000, 2000 respectively.
+ </para>
+
+ <para>
+ If you want to specify the paging parameters used for temporary queues then you need to specify them
+ on the appropriate connection factory.
+ See connection factory configuration for details.
+ </para>
+ </section>
+ </section>
+
+ <section id="conf.destination.new">
+ <title>Deploying a new destination</title>
+
+ <para>
+ For a JBoss 4.0.x installation, JBoss Messaging is deployed in its own class
+ loading domain. Because of that you need to deploy a new destinations to use
+ with JBoss Messaging within the same class loading domain.
+ </para>
+
+ <para>
+ To deploy a new destination, create a new deployment descriptor named
+ <filename>myqueue-service.xml</filename> (or anything else that ends in
+ <literal>-service.xml</literal>) and copy it to the JBoss instance deployment
+ directory <filename>$JBOSS_HOME/server/messaging/deploy</filename>.
+ </para>
+
+ <para>
+ An example of a scoped destination deployment descriptor is listed below:
+ </para>
+
+ <programlisting>
+<?xml version="1.0" encoding="UTF-8"?>
+<server>
+ <loader-repository>jboss.messaging:loader=ScopedLoaderRepository
+ <loader-repository-config>java2ParentDelegation=false</loader-repository-config>
+ </loader-repository>
+ <mbean code="org.jboss.jms.server.destination.Queue"
+ name="jboss.messaging.destination:service=Queue,name=testQueue"
+ xmbean-dd="xmdesc/Queue-xmbean.xml">
+ <depends optional-attribute-name="ServerPeer">
+ jboss.messaging:service=ServerPeer</depends>
+ <attribute name="SecurityConfig">
+ <security>
+ <role name="guest" read="true"
+ write="true"/>
+ <role name="publisher" read="true"
+ write="true" create="false"/>
+ <role name="noacc" read="false"
+ write="false" create="false"/>
+ </security>
+ </attribute>
+ <attribute name="fullSize">75000</attribute>
+ <attribute name="pageSize">2000</attribute>
+ <attribute name="downCacheSize">2000</attribute>
+ </mbean>
+</server>
+ </programlisting>
+
+ </section>
+ </section>
+
+ <section id="conf.connections">
+ <title>Configuring Connection Factories</title>
+
+ <para>
+ With the default configuration JBoss Messaging binds just one connection factory in
+ JNDI at start-up. This connection factory has no client ID and is bound into the
+ following JNDI contexts:
+ <literal>/ConnectionFactory, /XAConnectionFactory, java:/ConnectionFactory, java:/XAConnectionFactory</literal>
+ </para>
+
+ <para>
+ You may want to configure additional connection factories, for instance if you want to provide
+ a default client id for a connection factory, or if you want to bind it in different places
+ in JNDI, or if you want different connection factories to use different transports. Deploying
+ a new connection factory is equivalent with adding a new ConnectionFactory MBean
+ configuration to <filename>connection-factories-service.xml</filename>.
+ </para>
+ <para>
+ It is also possible to create an entirely
+ new service deployment descriptor <filename>xxx-service.xml</filename> altogether and
+ deploy it in <filename>$JBOSS_HOME/server/messaging/deploy</filename>.
+ </para>
+
+ <para>
+ An example connection factory configuration is presented below:
+ </para>
+
+ <programlisting>
+ <?xml version="1.0" encoding="UTF-8"?>
+ <server>
+ <loader-repository>jboss.messaging:loader=ScopedLoaderRepository
+ <loader-repository-config>java2ParentDelegation=false</loader-repository-config>
+ </loader-repository>
+ <mbean code="org.jboss.jms.server.connectionfactory.ConnectionFactory"
+ name="jboss.messaging.destination:service=ConnectionFactory"
+ xmbean-dd="xmdesc/ConnectionFactory-xmbean.xml">
+ <constructor>
+ <arg type="java.lang.String" value="myClientID"/>
+ </constructor>
+ <depends optional-attribute-name="ServerPeer">
+ jboss.messaging:service=ServerPeer</depends>
+ <depends optional-attribute-name="Connector">
+ jboss.messaging:service=Connector,transport=socket</depends>
+ <attribute name="PrefetchSize">10</attribute>
+ <attribute name="DefaultTempQueueFullSize">1000</attribute>
+ <attribute name="DefaultTempQueuePageSize">50</attribute>
+ <attribute name="DefaultTempQueueDownCacheSize">50</attribute>
+ <attribute name="JNDIBindings">
+ <bindings>
+ <binding>/MyConnectionFactory1</binding>
+ <binding>/factories/cf1</binding>>
+ </bindings>
+ </attribute>
+ </mbean>
+ </server>
+
+ </programlisting>
+
+ <para>
+ The above example would create a connection factory with pre-configured client ID
+ <literal>myClientID</literal> and bind the connection factory in two places in
+ the JNDI tree: <literal>/MyConnectionFactory</literal>
+ and <literal>/factories/cf</literal>. The connection factory will use the default
+ remoting connector. To use a different remoting connector with the connection factory
+ change the <literal>Connector</literal> attribute to specify the service name of the connector you wish to use.
+ </para>
+ <para>prefetchSize is an optional attribute that determines how many messages client side message consumers will buffer locally. Pre-fetching messages prevents
+ the client having to go to the server each time a message is consumed to say it is ready to receive another message.
+ This greatly increases throughput. The default value for prefetchSize is 150. You may want to change this to a smaller value if you are dealing with
+ very large messages, so as not to use too much memory on the client.
+ </para>
+ <para>DefaultTempQueueFullSize, DefaultTempQueuePageSize, DefaultTempQueueDownCacheSize are optional attributes that determine the default paging parameters to be used for
+ any temporary destinations scoped to connections created using this connection factory. See the section on paging channels for more information
+ on what these values mean.
+ They will default to values of 75000, 2000 and 2000 respectively if ommitted.
+ </para>
+ </section>
+
+ <section id="conf.connector">
+ <title>Configuring the remoting connector</title>
+
+ <para>
+ JBoss Messaging uses JBoss Remoting for all client to server communication.
+ For full details of what JBoss Remoting is capable of and how it is configured please
+ consult the JBoss Remoting documentation.
+ </para>
+
+ <para>
+ The default configuration includes a single remoting connector which is used by the
+ single default connection factory. Each connection factory can be configured to use
+ its own connector.
+ </para>
+
+ <para>
+ The default connector is configured to use the remoting socket transport.
+ </para>
+
+ <para>
+ This transport opens TCP connections from client to server for client to server
+ communications (e.g. sending messages) and TCP connections from server to client
+ for server to client communications (e.g. receiving messages). The transport can be
+ configured to use SSL where a higher level of security is required.
+ </para>
+
+ <para>
+ Future releases JBoss Messaging will support a bidirectional socket transport
+ (similar to UIL2 in JBoss MQ) and an HTTP transport, both of which are useful in
+ network environments where TCP connections from server to client are not possible.
+ This means, for example, that you could deploy one connection factory that uses
+ the HTTP transport for all the connections created from it, and another connection
+ factory that uses the socket transport for all connections created from it.
+ </para>
+
+ <para>
+ You can look at remoting configuration under:
+ </para>
+
+ <para>
+ <JBoss>/server/<YourMessagingServer>/deploy/jboss-messaging.sar/remoting-service.xml
+ </para>
+
+ <para>
+ By default JBoss Messaging binds to ${jboss.bind.address} which can be defined by:
+ ./run.sh -c <yourconfig> -b yourIP.
+ </para>
+
+ <para>
+ You can change remoting-service.xml if you want for example use a
+ different communication port, or change any other network behavior.
+ </para>
+ </section>
+
+ <section id="conf.callback">
+ <title>Configuring the callback</title>
+
+ <para>
+ JBoss Messaging uses a callback mechanism from Remoting that needs a Socket for callback operations. These socket properties are passed to the server by a remote call when the connection is being estabilished. As we said before we will support bidirectional protocols in future releases.
+ </para>
+
+ <para>
+ By default JBoss Messaging will execute InetAddress.getLocalHost().getHostAddress() to access your local host IP, but in case you need to setup a different IP, you can define a system property in your java arguments:
+ </para>
+
+ <para>
+ Use java -Djboss.messaging.callback.bind.address=YourHost - That will determine the callBack host in your client.
+ </para>
+
+ <para>
+ The client port will be selected randomly for any non used port. But if you defined -Djboss.messaging.callback.bind.port=NumericPort in your System Properties that number is going to be used for the call back client port.
+ </para>
+
+ </section>
+</chapter>
Added: trunk/docs/userguide-1.2/en/modules/UG2_gettingstarted.xml
===================================================================
--- trunk/docs/userguide-1.2/en/modules/UG2_gettingstarted.xml (rev 0)
+++ trunk/docs/userguide-1.2/en/modules/UG2_gettingstarted.xml 2007-03-01 05:24:11 UTC (rev 2518)
@@ -0,0 +1,100 @@
+<chapter id="UG2_gettingstarted">
+ <title>Download Software</title>
+
+ <para>
+ The official releases of JBoss Messaging are available as a free download from
+ <ulink url="http://www.jboss.com/products/messaging">the JBoss Messaging project landing page</ulink>.
+ </para>
+
+ <section id="releasebundle">
+ <title>The JBoss Messaging Release Bundle</title>
+
+ <para>
+ The JBoss Messaging release bundle (<filename>jboss-messaging-1.0.x.zip</filename>)
+ will expand in a <filename>jboss-messaging-1.0.x</filename> directory that contains:
+ </para>
+
+ <itemizedlist>
+ <listitem>
+ <filename>jboss-messaging-scoped.sar</filename>
+ - the scoped JBoss service archive that contains JBoss Messaging and its
+ dependencies.
+ <warning>
+ Do not simply attempt to copy the archive under a JBoss instance <filename>deploy</filename> directory,
+ since additional steps (such as un-installing JBossMQ and various other configurations
+ tasks) are required for a successful installation. See <xref linkend="installation"/> for
+ more details.
+ </warning>
+ </listitem>
+ <listitem>
+ <filename>jboss-messaging-client.jar</filename>
+ - the client-side library that need to be in the classpath of the client that opens
+ a remote connection to the Messaging server.
+ </listitem>
+ <listitem>
+ <filename>util</filename>
+ - a collection of <literal>ant</literal> configuration files used to automate
+ installation and release
+ management procedures. See the Installation chapter for more details.
+ </listitem>
+ <listitem>
+ <filename>examples</filename>
+ - a collection of examples that should run out of the box and help you validate the
+ installation. Detailed instructions are provided with each example, which range from
+ very simple JMS queue and topic examples to relatively sophisticated use cases in which
+ EJBs and JCA JMS ConnectionFactories are involved.
+ The <filename>examples/config</filename> sub-directory contains various configuration
+ file examples.
+ </listitem>
+ <listitem>
+ <filename>docs</filename>
+ - this user's guide.
+ </listitem>
+ <listitem>
+ <filename>src/jboss-messaging-1.0.x-src.zip</filename>
+ - the zipped source directory. The file can be directly installed into and used
+ with a debugger.
+ <note>
+ JBoss Messaging cannot be built using exclusively this source snapshot, which is
+ provided for reference only.
+ </note>
+ </listitem>
+ <listitem>
+ <filename>src/jboss-messaging-tests-1.0.x-src.zip</filename>
+ - the functional testsuite source archive.
+ </listitem>
+ <listitem>
+ <filename>test-results</filename>
+ - the output of the functional testsuite, stress and smoke test runs for this release.
+ All these files have been generated during the release procedure.
+ </listitem>
+ <listitem>
+ <filename>api</filename>
+ - the Messaging API javadoc.
+ </listitem>
+ <listitem>
+ <filename>README.html</filename>
+ - The release intro document that contains pointers to various other resources,
+ including this Guide.
+ </listitem>
+ </itemizedlist>
+
+ </section>
+
+
+ <section id="CVS">
+ <title>CVS Access</title>
+
+ <para>
+ If you want to experiment with the latest developments you may checkout the latest code
+ from the 5.0 head branch. Be aware that the information provided in this manual might then
+ not be accurate.
+ For the latest instructions, check out the
+ <ulink url="http://wiki.jboss.org/wiki/Wiki.jsp?page=JBossMessagingDevelopment">
+ Messaging Development wiki page
+ </ulink>.
+ </para>
+
+ </section>
+
+</chapter>
\ No newline at end of file
Added: trunk/docs/userguide-1.2/en/modules/UG2_installation.xml
===================================================================
--- trunk/docs/userguide-1.2/en/modules/UG2_installation.xml (rev 0)
+++ trunk/docs/userguide-1.2/en/modules/UG2_installation.xml 2007-03-01 05:24:11 UTC (rev 2518)
@@ -0,0 +1,202 @@
+<chapter id="UG2_installation">
+ <title>Installation</title>
+
+ <para>
+ By default, a JBoss AS 4.0.x instance ships with JBossMQ as default JMS provider.
+ In order to use the JBoss AS instance with JBoss Messaging, you need to perform the installation
+ procedure described below.
+ </para>
+
+ <para>
+ <warning>
+ A JBossMQ and a JBoss Messaging instance cannot coexist, at least not unless special
+ precautions are taken. Do not simply attempt to copy the Messaging release artifact
+ <filename>jboss-messaging-scoped.sar</filename> over to the JBoss instance
+ <filename>deploy</filename> directory. Follow one of the alternate installation procedures
+ outlined below instead.
+ </warning>
+ </para>
+
+
+
+ <section id="install4">
+ <title>Installing JBoss Messaging with JBoss AS 4.x</title>
+
+
+ <section id="install4.automated">
+ <title>Installation procedure</title>
+
+ <para>
+ Set up the <literal>JBOSS_HOME</literal> environment variable to point to
+ the JBoss 4.x installation you
+ want to use JBoss Messaging with. Run the installation script, available in the
+ <filename>util</filename> directory of the release bundle.
+ Note that you need Apache Ant 1.6.x or newer installed and accessible from
+ your current directory.
+ </para>
+
+ <programlisting>
+ cd util
+ ant -f release-admin.xml
+ </programlisting>
+
+ <para>
+ The installation script will create a <filename>$JBOSS_HOME/server/messaging</filename>
+ configuration.
+ </para>
+
+ <note>
+ If you want to create a JBoss Messaging configuration with a different name, modify
+ the <literal>messaging.config.name</literal> system property declared
+ at the beginning of the installation script accordingly.
+ </note>
+ </section>
+
+ </section>
+
+ <section id="startingtheservice">
+ <title>Starting the Server</title>
+
+
+ <para>
+ To run the server,
+ execute the <filename>run.bat</filename> or <filename>run.sh</filename> script as
+ appropriate for your operating system,
+ in the <filename>$JBOSS_HOME/bin</filename> directory.
+ </para>
+
+ <programlisting>
+ cd $JBOSS_HOME/bin
+ ./run.sh -c messaging
+ </programlisting>
+
+ <para>
+ A successful JBoss Messaging deployment generates logging output similar to:
+ </para>
+
+ <programlisting>
+....
+14:23:56,174 WARN [JDBCPersistenceManager]
+
+JBoss Messaging Warning:
+ DataSource connection transaction isolation should be READ_COMMITTED, but it is
+ currently NONE.
+ Using an isolation level less strict than READ_COMMITTED may lead to data consistency
+ problems.
+ Using an isolation level more strict than READ_COMMITTED may lead to deadlock.
+
+14:23:57,276 INFO [ServerPeer] JBoss Messaging 1.0.1.GA server [server.0] started
+14:23:57,937 INFO [ConnectionFactory] Connector has leasing enabled, lease period
+20000 milliseconds
+14:23:57,937 INFO [ConnectionFactory] [/ConnectionFactory, /XAConnectionFactory,
+java:/ConnectionFactory, java:/XAConnectionFactory] deployed
+14:23:57,987 INFO [Queue] Queue[/queue/DLQ] started, fullSize=75000, pageSize=2000,
+downCacheSize=2000
+14:23:57,997 INFO [Topic] Topic[/topic/testTopic] started, fullSize=75000, pageSize=2000,
+downCacheSize=2000
+14:23:58,017 INFO [Topic] Topic[/topic/securedTopic] started, fullSize=75000, pageSize=2000,
+downCacheSize=2000
+14:23:58,017 INFO [Topic] Topic[/topic/testDurableTopic] started, fullSize=75000,
+pageSize=2000, downCacheSize=2000
+14:23:58,027 INFO [Queue] Queue[/queue/testQueue] started, fullSize=75000, pageSize=2000,
+downCacheSize=2000
+14:23:58,027 INFO [Queue] Queue[/queue/A] started, fullSize=75000, pageSize=2000,
+downCacheSize=2000
+14:23:58,037 INFO [Queue] Queue[/queue/B] started, fullSize=75000, pageSize=2000,
+downCacheSize=2000
+14:23:58,057 INFO [Queue] Queue[/queue/C] started, fullSize=75000, pageSize=2000,
+downCacheSize=2000
+14:23:58,067 INFO [Queue] Queue[/queue/D] started, fullSize=75000, pageSize=2000,
+downCacheSize=2000
+14:23:58,077 INFO [Queue] Queue[/queue/ex] started, fullSize=75000, pageSize=2000,
+downCacheSize=2000
+14:23:58,077 INFO [Topic] Topic[/topic/openTopic] started, fullSize=75000, pageSize=2000,
+downCacheSize=2000
+14:23:58,117 INFO [ConnectionFactoryBindingService] Bound ConnectionManager
+'jboss.jca:service=ConnectionFactoryBinding,name=JmsXA' to JNDI name 'java:JmsXA'
+....
+ </programlisting>
+
+ <note>
+ The warning message <literal>DataSource connection transaction isolation should be READ_COMMITTED, but it is currently NONE</literal>
+ is there to remind you that by default JBossAS ships with Hypersonic, an in-memory
+ Java-based database engine, which is apropriate for demo purposes, but not for heavy load
+ production environments. The
+ <ulink url="http://wiki.jboss.org/wiki/Wiki.jsp?page=ConfigJBossMQDB">Critique of Hypersonic</ulink>
+ wiki page outlines some of the well-known issues occuring when using this database.
+ </note>
+
+ <warning>
+ Before using Messaging in production, you <emphasis>must</emphasis> configure
+ the Messaging instance to use an enterprise-class database backend such as MySQL or Oracle,
+ otherwise you risk losing your data.
+ See <xref linkend="conf.changingds"/> for details about replacing Hypersonic.
+ </warning>
+
+
+
+ </section>
+
+
+
+ <section id="inst.validation">
+ <title>Installation Validation</title>
+
+ <para>
+ The release bundle contains a series of examples that should run "out of the box" and
+ could be used to validate a new installation. Such an example sends a persistent JMS message
+ to a queue called <literal>queue/testQueue</literal>.
+ </para>
+
+
+ <para>
+ To run the example and validate the installation,
+ open an new command line window and set the <literal>JBOSS_HOME</literal>
+ environment variable to point to the JBoss AS 4.x installation you've just installed
+ Messaging on. Navigate to the folder where
+ you extracted the release bundle and drill down to <filename>/examples/queue</filename>.
+ Apache Ant must pe present in your path in order to be able to run the example.
+ </para>
+
+ <programlisting>
+
+ setenv JBOSS_HOME=<your_JBoss_installation>
+ cd .../examples/queue
+ $ant
+
+ </programlisting>
+
+ <para>
+ A successfull execution log output looks similar to:
+ </para>
+
+
+ <programlisting>
+Buildfile: build.xml
+identify:
+ [echo] Running the queue example
+ [echo] The queue: testQueue
+sanity-check:
+init:
+compile:
+run:
+ [java] Queue /queue/testQueue exists
+ [java] The message was successfully sent to the testQueue queue
+ [java] Received message: Hello!
+ [java] The example connected to JBoss Messaging version 1.0.0 (1.0)
+ [java] #####################
+ [java] ### SUCCESS! ###
+ [java] #####################
+ </programlisting>
+
+
+ <para>
+ It is recommended to run <literal>all</literal> validation examples available in the
+ <filename>example</filename> directory (<filename>queue</filename>, <filename>topic</filename>,
+ <filename>mdb</filename>, <filename>stateless</filename>, etc.). In <xref linkend="examples"/>, we will have a look at each of those examples.
+ </para>
+
+
+ </section>
+
+</chapter>
Added: trunk/docs/userguide-1.2/en/modules/UG2_introduction.xml
===================================================================
--- trunk/docs/userguide-1.2/en/modules/UG2_introduction.xml (rev 0)
+++ trunk/docs/userguide-1.2/en/modules/UG2_introduction.xml 2007-03-01 05:24:11 UTC (rev 2518)
@@ -0,0 +1,269 @@
+<chapter id="UG2_introduction">
+
+ <title>Introduction</title>
+
+ <para>
+ JBoss Messaging provides an open source and standards-based messaging platform that brings
+ enterprise-class messaging to the mass market.
+ </para>
+
+ <para>
+ JBoss Messaging implements a high performance, robust messaging core that is designed to
+ support the largest and most heavily utilized SOAs, enterprise service buses (ESBs) and other
+ integration needs ranging from the simplest to the highest demand networks.
+ It will allow you to smoothly distribute your application load across your cluster,
+ intelligently balancing and utilizing each nodes CPU cycles, with no single point of failure,
+ providing a highly scalable and perform-ant clustering implementation. JBoss Messaging includes
+ a JMS front-end to deliver messaging in a standards-based format as well as being designed to be
+ able to support other messaging protocols in the future.
+ </para>
+
+ <para>
+ JBoss Messaging will soon become an integral component of the JBoss Enterprise Middleware
+ Suite (JEMS). Currently it
+ is available for embedded use within the JBoss Application Server (JBossAS), and as a
+ JBoss Microkernel-based stand-alone server. Work to integrate JBoss Messaging with the new
+ JBoss Microcontainer is under way.
+ </para>
+
+ <para>
+ The large and vibrant JEMS developer community fosters its continued innovation and
+ enterprise quality. JBoss Messaging enables more agile applications in a wide range of
+ scenarios from simple messaging needs to an enterprise-wide messaging foundation.
+ </para>
+
+ <para>
+ JBoss Messaging adds flexibility to any SOA initiative.
+ </para>
+
+
+
+
+ <section id="features">
+ <title>JBoss Messaging 1.2.0.GA Features</title>
+
+ <para>
+ JBoss Messaging provides:
+ </para>
+
+ <itemizedlist>
+ <listitem>
+ <para>
+ A fully compatible and Sun certified JMS 1.1 implementation, that currently works
+ with a standard JBossAS 4.x installation and also as a JBoss Microkernel-based
+ standalone deployment.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ A strong focus on performance, reliability and scalability with high throughput and
+ low latency. JBoss Messaging already exceeds JBoss MQ in a number of measured
+ performance metrics. Full results will follow.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ A foundation for JBoss ESB for SOA initiatives; JBoss ESB uses
+ JBoss Messaging as its foundation.
+ </para>
+ </listitem>
+ </itemizedlist>
+
+ <para>
+ JBoss Messaging consists of two major parts:
+ </para>
+
+ <itemizedlist>
+ <listitem>
+ <para>
+ JBoss Messaging Core – a transactional, reliable messaging transport system.
+ </para>
+ <itemizedlist>
+ <listitem>
+ <para>
+ Supports generalized messages (not just JMS)
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ Enables other messaging protocol façades to be added
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ Distributed, transactional and reliable
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ Clustering support
+ </para>
+ </listitem>
+ </itemizedlist>
+ </listitem>
+
+ <listitem>
+ <para>
+ JMS Façade – the JMS "personality" of JBoss Messaging.
+ </para>
+ </listitem>
+ </itemizedlist>
+
+ <para>
+ Other JBoss Messaging features include:
+ </para>
+
+ <itemizedlist>
+ <listitem>
+ <para>
+ Publish-subscribe and point-to-point messaging models
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ Topics that feed multiple message queues
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ Persistent and non-persistent messages
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ Guaranteed message delivery that ensures that messages arrive once and only once
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ Transactional and reliable - supporting ACID semantics
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ Customizable security framework based on JAAS
+ </para>
+ </listitem>
+ </itemizedlist>
+
+ <para>
+ JBoss Messaging 1.2.0.GA Clustering provides the following features:
+ </para>
+
+ <itemizedlist>
+ <listitem>
+ <para>
+ Distributed queues. Messages sent to a distributed queue while attached to a
+ particular node will be routed to a queue instance on a particular node according
+ to a routing policy.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ Distributed topics. Messages sent to a distributed topic while attached at a
+ particular node will be received by subscriptions on other nodes.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ Fully reliable message distribution. Once and only once delivery is fully guaranteed.
+ When sending messages to a topic with multiple durable subscriptions
+ across a cluster we guarantee that message reaches all the subscriptions
+ (or none of them in case of failure).
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ Persistent level reliability guarantee without persistence! By replicating persistent
+ messages between nodes in memory, we can obtain comparable reliability levels to persisting
+ messages to disk, without actually storing them to disk.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ Pluggable routing implementation. The policy for routing messages to a queue is fully
+ pluggable and easily replaceable. The default policy always chooses a queue at the local
+ node if there is one, and if not, it round robins between queues on different nodes.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ Intelligent message redistribution policy. Messages are automatically distributed between
+ nodes depending on how fast or slow consumers are on certain nodes. If there are no or slow
+ consumers on a particular queue node, messages will be pulled from that queue to a queue with
+ faster consumers on a different node. The policy is fully pluggable.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ Shared durable subscriptions. Consumers can connect to the same durable subscription while
+ attached to different nodes. This allows processing load from durable subscriptions to be
+ distributed across the cluster in a similar way to queues.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ High availability and seamless fail-over. If the node you are connected to fails, you
+ will automatically fail over to another node and will not lose any persistent messages.
+ You can carry on with your session seamlessly where you left off. Once and only once
+ delivery of persistent messages is respected at all times.
+ </para>
+ </listitem>
+ </itemizedlist>
+
+
+ </section>
+
+
+ <section id="compatibility">
+ <title>Compatibility with JBossMQ</title>
+
+ <para>
+ JBossMQ is the JMS implementation currently shipped within JBossAS.
+ Since JBoss Messaging is JMS 1.1 and JMS 1.0.2b compatible, the JMS code written against
+ JBossMQ will run with JBoss Messaging without any changes.
+ </para>
+
+ <important>
+ Even if JBoss Messaging deployment descriptors are very similar to JBoss MQ
+ deployment descriptors, they are <emphasis>not</emphasis> identical, so they will require
+ some simple adjustments to get them to work with JBoss Messaging.
+ </important>
+ </section>
+
+ <section id="missingfeatures">
+ <title>
+ Features that didn't make it into the 1.2.0.GA release
+ </title>
+
+ <para>
+ All the final features are available apart from:
+ </para>
+
+ <itemizedlist>
+ <listitem>
+ <para>
+ Persistent level reliability guarantee without persistence. There is no option for in
+ memory replication of persistent messages in this release. It will be scheduled ASAP.
+ The JIRA issue link is:
+
+ <ulink url="http://jira.jboss.org/jira/browse/JBMESSAGING-574">
+ </ulink>
+
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ JBoss Messaging 1.2.0.GA contains all features planned for the GA release, with the
+ exception of the "unreliable link scenario"
+ <ulink url="http://jira.jboss.org/jira/browse/JBMESSAGING-676">
+ </ulink>
+ whose development is still on-going on a parallel branch.
+ </para>
+ </listitem>
+
+ </itemizedlist>
+ </section>
+
+</chapter>
Added: trunk/docs/userguide-1.2/en/modules/UG2_performance.xml
===================================================================
--- trunk/docs/userguide-1.2/en/modules/UG2_performance.xml (rev 0)
+++ trunk/docs/userguide-1.2/en/modules/UG2_performance.xml 2007-03-01 05:24:11 UTC (rev 2518)
@@ -0,0 +1,160 @@
+<chapter id="UG2_performance">
+
+ <title>Generating Performance Benchmark Results</title>
+
+ <para>As we discussed in <xref linkend="about"/>, the key advantage of JBoss Messaging is its superior performance. In fact, the JBoss Messaging comes with a set of standard performance test. You can run them on your server and generate your own performance benchmark results. In this chapter, we will show you how to run a JBoss Messaging server and a JBossMQ server side-by-side on a single machine, and compare their performance. To get the performance tests, you have to obtain the JBoss Messaging source code from CVS as described in <xref linkend="gettingstarted"/>.</para>
+
+ <para>The test consists in sending bursts of 1000 0 Kilobytes non-persistent messages to both JBoss Messaging and JBossMQ instances while gradually increasing the send rate (200 messages/sec, 400 messages/sec, etc) and measuring the receive rate. At the end, the framework generates the graph representing the receive rate as function of the send rate for two executions (JBoss Messaging and JBossMQ).</para>
+
+ <section>
+ <title>Run JBoss Messaging and JBossMQ Side-by-side</title>
+
+ <para>To run performance tests side-by-side on the same machine, we assume that you create two JBoss AS configurations with the JBoss Messaging and JBossMQ modules respectively. We assume that the JBoss Messaging module is installed in the <literal>server/messaging</literal> directory (see <xref linkend="installation"/>), and the default JBossMQ module is installed in <literal>server/jbossmq</literal> directory (just copy the original <literal>default</literal> directory that comes with the server).</para>
+
+ <para>Now, if you run the two configurations on the same server, there will be port conflicts. To avoid that, we use the JBoss <literal>ServiceBindingManager</literal> to increase the port numbers in the <literal>jbossmq</literal> configuration by 100 (i.e., the JNDI service will be available at port 1199 instead of 1099). To do that, un-comment the following line in <literal>server/jbossmq/conf/jboss-service.xml</literal></para>
+
+ <programlisting>
+<mbean code="org.jboss.services.binding.ServiceBindingManager"
+ name="jboss.system:service=ServiceBindingManager">
+
+ <attribute name="ServerName">ports-01</attribute>
+ <attribute name="StoreURL">
+ ../docs/examples/binding-manager/sample-bindings.xml
+ </attribute>
+ <attribute name="StoreFactoryClassName">
+ org.jboss.services.binding.XMLServicesStoreFactory
+ </attribute>
+</mbean>
+ </programlisting>
+
+ <para>Now, you can start the <literal>messaging</literal> and <literal>jbossmq</literal> configurations side-by-side for testing.</para>
+
+ <programlisting>
+run -c messaging
+run -c jbossmq
+ </programlisting>
+
+ </section>
+
+ <section>
+ <title>Setup the Tests</title>
+
+ <para>The performance framework relies on distributed executors to send messages into the providers being tested. The executors can run standalone in their own VM and act as "remote" JMS connections, or colocated, in which case they are deployed as JBoss services and simulate "colocated" JMS connections.</para>
+
+ <para>In order to correctly deploy the colocated executors, the framework relies on the <literal>JBOSS_HOME</literal> environment variable. It assumes directories <literal>$JBOSS_HOME/server/messaging</literal> and <literal>$JBOSS_HOME/server/jbossmq</literal> exist.</para>
+
+ <programlisting>
+cd perf
+ant sar
+ant start-executors
+ </programlisting>
+
+ <para>Next, we need to deploy test message destinations. They are in the <literal>messaging-destinations-service.xml</literal>, <literal>jbossmq-destinations-service.xml</literal> files. Feel free to add your own destinations (must add equivalent ones in both files) and then deploy them via the following command.</para>
+
+ <programlisting>
+ant deploy-destinations
+ </programlisting>
+
+ </section>
+
+ <section>
+ <title>Configure Test Runs</title>
+
+ <para>The <literal>perf/perf.xml</literal> file is used to configure tests. In our setting (i.e., <literal>jbossmq</literal> runs in +100 port range from default), the <literal><providers></literal> section should look like the following. We can easily run the two JMS server configurations on different machines or in other port ranges. You just need to change the host and port numbers here for tests.</para>
+
+ <programlisting>
+<provider name="JBossMessaging">
+ <factory>org.jnp.interfaces.NamingContextFactory</factory>
+ <url>jnp://localhost:1099</url>
+ <pkg>org.jboss.naming:org.jnp.interfaces</pkg>
+ <executor name="REMOTE" url="rmi://localhost:7777/standalone"/>
+ <executor name="REMOTE2" url="rmi://localhost:7777/standalone2"/>
+ <executor name="COLOCATED" url="rmi://localhost:7777/colocated-messaging"/>
+ <executor name="COLOCATED2" url="rmi://localhost:7777/colocated-messaging2"/>
+</provider>
+
+<provider name="JBossMQ">
+ <factory>org.jnp.interfaces.NamingContextFactory</factory>
+ <url>jnp://localhost:1199</url>
+ <pkg>org.jboss.naming:org.jnp.interfaces</pkg>
+ <executor name="REMOTE" url="rmi://localhost:7777/standalone"/>
+ <executor name="REMOTE2" url="rmi://localhost:7777/standalone2"/>
+ <executor name="COLOCATED" url="rmi://localhost:7777/colocated-jbossmq"/>
+ <executor name="COLOCATED2" url="rmi://localhost:7777/colocated-jbossmq2"/>
+</provider>
+ </programlisting>
+
+ <para>The performance configuration section configures how to ramp up the load from 200 messages / sec to 3000 message / sec. We will gather statistics on the number of processed messages versus the number of sent messages.</para>
+
+ <programlisting>
+<performance-test name="Throughput O KB Message
+ Non-Persistent Non-Transactional, 1 sender, 1 receiver">
+
+ <message-size>0</message-size>
+ <messages>10000</messages>
+
+ <drain/>
+
+ <parallel>
+ <send rate="200" executor="COLOCATED"/>
+ <receive executor="COLOCATED2"/>
+ </parallel>
+
+ <parallel>
+ <send rate="400" executor="COLOCATED"/>
+ <receive executor="COLOCATED2"/>
+ </parallel>
+
+ <parallel>
+ <send rate="800" executor="COLOCATED"/>
+ <receive executor="COLOCATED2"/>
+ </parallel>
+
+ <parallel>
+ <send rate="1000" executor="COLOCATED"/>
+ <receive executor="COLOCATED2"/>
+ </parallel>
+
+ <parallel>
+ <send rate="1500" executor="COLOCATED"/>
+ <receive executor="COLOCATED2"/>
+ </parallel>
+
+ <parallel>
+ <send rate="2000" executor="COLOCATED"/>
+ <receive executor="COLOCATED2"/>
+ </parallel>
+
+ <parallel>
+ <send rate="2500" executor="COLOCATED"/>
+ <receive executor="COLOCATED2"/>
+ </parallel>
+
+ <parallel>
+ <send rate="3000" executor="COLOCATED"/>
+ <receive executor="COLOCATED2"/>
+ </parallel>
+
+ <execution provider="JBossMessaging"/>
+ <execution provider="JBossMQ"/>
+
+</performance-test>
+ </programlisting>
+
+ </section>
+
+ <section>
+ <title>Run the Tests</title>
+
+ <para>To run the tests, simply executes <literal>ant</literal> from the command line. You can access the benchmark result graphs from <literal>output/results/benchmark-results.html</literal>.</para>
+
+ <para>After running the test, you can clean up the executors and test destinations using the following commands.</para>
+
+ <programlisting>
+ant kill-executors
+ant undeploy-destinations
+ </programlisting>
+
+ </section>
+
+</chapter>
\ No newline at end of file
Added: trunk/docs/userguide-1.2/en/modules/UG2_runningexamples.xml
===================================================================
--- trunk/docs/userguide-1.2/en/modules/UG2_runningexamples.xml (rev 0)
+++ trunk/docs/userguide-1.2/en/modules/UG2_runningexamples.xml 2007-03-01 05:24:11 UTC (rev 2518)
@@ -0,0 +1,645 @@
+<chapter id="UG2_examples">
+
+ <title>Running the Examples</title>
+
+ <para>Since JBoss Messaging is a full JMS provider, it supports all JMS APIs. So, all JMS applications should work without modification. Integrated inside a JBoss AS, we should also access the JMS system from EJBs and write message-driven beans against JMS destinations.</para>
+
+
+ <para>In the following sections, we will look at examples of the various JMS messaging models and message-driven beans. They make use of pre-configured JMS destinations and connection factories that come default with the server. So, no extra configuration is needed to run those examples. Just set JBOSS_HOME and run ANT in each example directory, as we described in <xref linkend="inst.validation"/>. The example source directories are located in the distribution under <literal>docs/examples</literal>.
+ </para>
+
+ <section id="examples.queue">
+ <title>Sending messages to a queue</title>
+
+ <para>
+ Open an new command line. Set the JBOSS_HOME environment variable to point at a JBossAS 4.x installation. Navigate to the folder where you exploded the main archive and drill down to <literal>/examples/queue</literal>. You need to use Apache Ant to execute the build.xml file.
+ Make sure the JBoss server reference by the JBOSS_HOME is started.
+ </para>
+
+ <programlisting>
+public class QueueExample extends ExampleSupport
+{
+
+ public void example() throws Exception
+ {
+ String destinationName = getDestinationJNDIName();
+
+ InitialContext ic = null;
+ ConnectionFactory cf = null;
+ Connection connection = null;
+ Connection connection2 = null;
+
+ try {
+
+ ic = new InitialContext();
+
+ cf = (ConnectionFactory)ic.lookup("/ConnectionFactory");
+ Queue queue = (Queue)ic.lookup(destinationName);
+ log("Queue " + destinationName + " exists");
+
+ connection = cf.createConnection();
+ Session session = connection.createSession(false, Session.AUTO_ACKNOWLEDGE);
+ MessageProducer sender = session.createProducer(queue);
+
+ TextMessage message = session.createTextMessage("Hello!");
+ sender.send(message);
+ log("The message was successfully sent to the " + queue.getQueueName() + " queue");
+
+ connection2 = cf.createConnection();
+ Session session2 = connection2.createSession(false, Session.AUTO_ACKNOWLEDGE);
+ MessageConsumer consumer = session2.createConsumer(queue);
+
+ connection2.start();
+
+ message = (TextMessage)consumer.receive(2000);
+ log("Received message: " + message.getText());
+ assertEquals("Hello!", message.getText());
+
+ displayProviderInfo(connection2.getMetaData());
+
+ }catch(NamingException ne){
+ ne.printStackTrace();
+
+ }catch(JMSException jmse){
+ jmse.printStackTrace();
+
+ }catch(Exception e){
+ e.printStackTrace();
+
+ }finally{
+
+ if(ic != null) {
+ try {
+ ic.close();
+ }catch(Exception ignore){ }
+ }
+
+ closeConnection(connection);
+
+ closeConnection(connection2);
+ }
+
+ }
+
+ private void closeConnection(Connection con){
+
+ try {
+ if (con != null) {
+ con.close();
+ }
+
+ }catch(JMSException jmse) {
+ log("Could not close connection " + con +" exception was " +jmse);
+ }
+ }
+
+
+ protected boolean isQueueExample()
+ {
+ return true;
+ }
+
+ public static void main(String[] args)
+ {
+ new QueueExample().run();
+ }
+
+}
+ </programlisting>
+
+ </section>
+
+
+ <section id="examples.topic">
+ <title>Sending messages to a topic</title>
+ <para>In this example, a standalone Java client publishes a text-based JMS message to a topic and a single subscriber pulls the message off the queue.
+ </para>
+
+ <para>
+ Open an new command line. Set the JBOSS_HOME environment variable to point at a JBossAS 4.x installation. Navigate to the folder where you exploded the main archive and drill down to <literal>/examples/queue</literal>. You need to use Apache Ant to execute the build.xml file
+ Make sure the JBoss server reference by the JBOSS_HOME is started.
+ </para>
+
+ <programlisting>
+public class TopicExample extends ExampleSupport
+{
+ public void example() throws Exception
+ {
+ String destinationName = getDestinationJNDIName();
+
+ InitialContext ic = null;
+ Connection connection = null;
+
+ try {
+
+ ic = new InitialContext();
+
+ ConnectionFactory cf = (ConnectionFactory)ic.lookup("/ConnectionFactory");
+ Topic topic = (Topic)ic.lookup(destinationName);
+ log("Topic " + destinationName + " exists");
+
+ connection = cf.createConnection();
+ Session session = connection.createSession(false, Session.AUTO_ACKNOWLEDGE);
+ MessageProducer publisher = session.createProducer(topic);
+ MessageConsumer subscriber = session.createConsumer(topic);
+
+ ExampleListener messageListener = new ExampleListener();
+ subscriber.setMessageListener(messageListener);
+ connection.start();
+
+ TextMessage message = session.createTextMessage("Hello!");
+ publisher.send(message);
+ log("The message was successfully published on the topic");
+
+ messageListener.waitForMessage();
+
+ message = (TextMessage)messageListener.getMessage();
+ log("Received message: " + message.getText());
+ assertEquals("Hello!", message.getText());
+
+ displayProviderInfo(connection.getMetaData());
+
+ }finally{
+
+ if(ic != null) {
+ try {
+ ic.close();
+ }catch(Exception e){
+ throw e;
+ }
+ }
+
+ //ALWAYS close your connection in a finally block to avoid leaks
+ //Closing connection also takes care of closing its related objects e.g. sessions
+ closeConnection(connection);
+ }
+ }
+
+ private void closeConnection(Connection con) throws JMSException {
+
+ try {
+ if (con != null) {
+ con.close();
+ }
+
+ }catch(JMSException jmse) {
+ log("Could not close connection " + con +" exception was " +jmse);
+ throw jmse;
+ }
+ }
+
+
+ protected boolean isQueueExample()
+ {
+ return false;
+ }
+
+ public static void main(String[] args)
+ {
+ new TopicExample().run();
+ }
+
+}
+ </programlisting>
+
+ </section>
+
+ <section id="examples.stateless">
+ <title>Using JMS from an EJB</title>
+ <para>This example deploys a simple Stateless Session Bean that is used as a proxy to send and receive JMS messages in a managed environment.
+ </para>
+
+ <programlisting>
+public class StatelessSessionExampleBean implements SessionBean
+{
+
+ private SessionContext ctx;
+
+ private ConnectionFactory cf = null;
+
+ public void drain(String queueName) throws Exception
+ {
+ InitialContext ic = new InitialContext();
+ Queue queue = (Queue)ic.lookup(queueName);
+ ic.close();
+
+ Session session = null;
+ Connection conn = null;
+
+ try
+ {
+ conn = getConnection();
+ session = conn.createSession(false, Session.AUTO_ACKNOWLEDGE);
+ MessageConsumer consumer = session.createConsumer(queue);
+ Message m = null;
+ do
+ {
+ m = consumer.receiveNoWait();
+ }
+ while(m != null);
+ }
+ finally
+ {
+ closeConnection(conn);
+ }
+ }
+
+ public void send(String txt, String queueName) throws Exception
+ {
+ InitialContext ic = new InitialContext();
+ Queue queue = (Queue)ic.lookup(queueName);
+ ic.close();
+
+ Session session = null;
+ Connection conn = null;
+
+ try
+ {
+ conn = getConnection();
+ session = conn.createSession(false, Session.AUTO_ACKNOWLEDGE);
+
+ MessageProducer producer = session.createProducer(queue);
+
+ TextMessage tm = session.createTextMessage(txt);
+
+ producer.send(tm);
+ System.out.println("message " + txt + " sent to " + queueName);
+
+ }
+ finally
+ {
+ closeConnection(conn);
+ }
+ }
+
+ public List browse(String queueName) throws Exception
+ {
+ InitialContext ic = new InitialContext();
+ Queue queue = (Queue)ic.lookup(queueName);
+ ic.close();
+
+ Session session = null;
+ Connection conn = null;
+
+ try
+ {
+ conn = getConnection();
+ session = conn.createSession(false, Session.AUTO_ACKNOWLEDGE);
+ QueueBrowser browser = session.createBrowser(queue);
+
+ ArrayList list = new ArrayList();
+ for(Enumeration e = browser.getEnumeration(); e.hasMoreElements(); )
+ {
+ list.add(e.nextElement());
+ }
+
+ return list;
+ }
+ finally
+ {
+ closeConnection(conn);
+ }
+ }
+
+ public String receive(String queueName) throws Exception
+ {
+ InitialContext ic = new InitialContext();
+ Queue queue = (Queue)ic.lookup(queueName);
+ ic.close();
+
+ Session session = null;
+ Connection conn = null;
+
+ try
+ {
+ conn = getConnection();
+ session = conn.createSession(false, Session.AUTO_ACKNOWLEDGE);
+
+ MessageConsumer consumer = session.createConsumer(queue);
+
+ System.out.println("blocking to receive message from queue " + queueName + " ...");
+ TextMessage tm = (TextMessage)consumer.receive(5000);
+
+ if (tm == null)
+ {
+ throw new Exception("No message!");
+ }
+
+ System.out.println("Message " + tm.getText() + " received");
+
+ return tm.getText();
+
+ }
+ finally
+ {
+ closeConnection(conn);
+ }
+ }
+
+ public Connection getConnection() throws Exception {
+
+ Connection connection = null;
+
+ try {
+ connection = cf.createConnection();
+ connection.start();
+
+ }catch(Exception e ){
+ if(connection != null)
+ closeConnection(connection);
+ System.out.println("Failed to get connection...exception is " +e);
+ throw e;
+ }
+
+ return connection;
+ }
+
+ public void closeConnection(Connection con) throws Exception {
+
+ try {
+ if (con != null) {
+ con.close();
+ }
+
+ }catch(JMSException jmse) {
+ System.out.println("Could not close connection " + con +" exception was " +jmse);
+ throw jmse;
+
+ }
+ }
+
+ .......
+ </programlisting>
+
+ </section>
+
+ <section id="examples.mdb.ejb21">
+ <title>Using EJB2.1 Message Driven Beans</title>
+ <para>This example deploys a simple Message Driven Bean that processes messages sent to a test queue. Once it receives a message and "processes" it, the MDB sends an acknowledgment message to a temporary destination created by the sender for this purpose. The example is considered successful if the sender receives the acknowledgment message.
+ </para>
+
+ <para>The MDB ejb-jar.xml descriptor
+ </para>
+ <programlisting>
+<ejb-jar>
+ <enterprise-beans>
+ <message-driven>
+ <ejb-name>MDBExample</ejb-name>
+ <ejb-class>org.jboss.example.jms.mdb.MDBExample</ejb-class>
+ <transaction-type>Container</transaction-type>
+ </message-driven>
+ </enterprise-beans>
+</ejb-jar>
+ </programlisting>
+
+ <para>The MDB jboss.xml descriptor
+ </para>
+ <programlisting>
+<enterprise-beans>
+ <message-driven>
+ <ejb-name>MDBExample</ejb-name>
+ <destination-jndi-name>queue/@QUEUE_NAME@</destination-jndi-name>
+ </message-driven>
+</enterprise-beans>
+ </programlisting>
+
+ <programlisting>
+public class MDBExample implements MessageDrivenBean, MessageListener
+{
+
+ private MessageDrivenContext ctx;
+
+ private ConnectionFactory cf = null;
+
+ public void onMessage(Message m)
+ {
+ Session session = null;
+ Connection conn = null;
+
+ try
+ {
+ TextMessage tm = (TextMessage)m;
+
+ String text = tm.getText();
+ System.out.println("message " + text + " received");
+ String result = process(text);
+ System.out.println("message processed, result: " + result);
+
+ conn = getConnection();
+ session = conn.createSession(false, Session.AUTO_ACKNOWLEDGE);
+
+ Destination replyTo = m.getJMSReplyTo();
+ MessageProducer producer = session.createProducer(replyTo);
+ TextMessage reply = session.createTextMessage(result);
+
+ producer.send(reply);
+ producer.close();
+
+ }
+ catch(Exception e)
+ {
+ ctx.setRollbackOnly();
+ e.printStackTrace();
+ System.out.println("The Message Driven Bean failed!");
+ }
+ finally
+ {
+ if (conn != null)
+ {
+ try {
+ closeConnection(conn);
+ }catch(Exception e){
+ System.out.println("Could not close the connection!" +e);
+ }
+ }
+ }
+ }
+
+ private String process(String text)
+ {
+ // flip the string
+
+ String result = ";
+
+ for(int i = 0; i < text.length(); i++)
+ {
+ result = text.charAt(i) + result;
+ }
+ return result;
+ }
+
+ public Connection getConnection() throws Exception {
+
+ Connection connection = null;
+
+ try {
+ connection = cf.createConnection();
+ connection.start();
+
+ }catch(Exception e ){
+ if(connection != null)
+ closeConnection(connection);
+ System.out.println("Failed to get connection...exception is " +e);
+ throw e;
+ }
+
+ return connection;
+ }
+
+ public void closeConnection(Connection con) throws Exception {
+
+ try {
+ if (con = null) {
+ con.close();
+ }
+
+ }catch(JMSException jmse) {
+ System.out.println("Could not close connection " + con +" exception was " +jmse);
+ throw jmse;
+ }
+ }
+
+ ......
+ </programlisting>
+
+
+ </section>
+
+
+ <section id="examples.mdb.ejb3">
+ <title>Using EJB3 Message Driven Beans</title>
+
+ <para>
+ This example deploys a simple EJB3 Message Driven Bean that processes messages sent to a
+ test queue. Once it receives a message and "processes" it, the MDB sends an
+ acknowledgment message to a temporary destination created by the sender for this purpose.
+ The example is considered successful if the sender receives the acknowledgment message.
+ </para>
+
+ <para>
+ This example relies on having access to a running JBoss Messaging instance.
+ The JBoss Messaging instance must be installed and started according to the
+ "Installation" chapter of this document. The example will automatically deploy
+ its own queue, unless a queue with the same name is already deployed.
+ </para>
+
+ <para>
+ This example also relies on having access to the
+ <filename>jboss-messaging-client.jar</filename> archive that comes with the release bundle.
+ If you run this example from an unzipped installation bundle, the example run script
+ is correctly configured to find the client jar. Otherwise, you must modify example's
+ <filename>build.xml</filename> accordingly.
+ </para>
+
+ <para>
+ The example was designed to deploy its server-side artifacts under a JBoss'
+ <literal>messaging</literal> configuration. If you intend to use the script with
+ a JBoss configuration that is named differently, please modify the example's
+ <filename>build.xml</filename> accordingly.
+ </para>
+
+ <important>
+ The JBoss instance that runs the Messaging server must also have EJB3 support
+ previously installed. If the EJB3 support is not installed, the example will fail
+ with an error message similar to:
+
+ <programlisting>
+C:\work\src\cvs\jboss-head\jms\docs\examples\ejb3mdb\build.xml:60: EJB3 does not seem
+to be installed in C:\work\src\jboss-4.0.3-src\build\output\jboss-4.0.3/server/messaging!
+Install it and try again.
+ </programlisting>
+
+ <para>
+ For instructions on how to install EJB3 support,
+ please go to <ulink url="http://docs.jboss.org/ejb3">JBoss EJB3 documentation page</ulink>
+ or use the JBoss Installer.
+ </para>
+ </important>
+
+ <para>
+ The EJB3 Message Driven Bean source code:
+ </para>
+ <programlisting>
+ at MessageDriven(activateConfig =
+{
+ @ActivationConfigProperty(propertyName="destinationType",
+ propertyValue="javax.jms.Queue"),
+ @ActivationConfigProperty(propertyName="destination",
+ propertyValue="queue/testQueue")
+})
+public class EJB3MDBExample implements MessageListener
+{
+ public void onMessage(Message m)
+ {
+ businessLogic(m);
+ }
+
+
+ private void businessLogic(Message m)
+ {
+ Connection conn = null;
+ Session session = null;
+
+ try
+ {
+ TextMessage tm = (TextMessage)m;
+
+ String text = tm.getText();
+ System.out.println("message " + text + " received");
+
+ // flip the string
+ String result = "";
+ for(int i = 0; i < text.length(); i++)
+ {
+ result = text.charAt(i) + result;
+ }
+
+ System.out.println("message processed, result: " + result);
+
+
+ InitialContext ic = new InitialContext();
+ ConnectionFactory cf = (ConnectionFactory)ic.lookup("java:/JmsXA");
+ ic.close();
+
+ conn = cf.createConnection();
+ conn.start();
+ session = conn.createSession(false, Session.AUTO_ACKNOWLEDGE);
+
+ Destination replyTo = m.getJMSReplyTo();
+ MessageProducer producer = session.createProducer(replyTo);
+ TextMessage reply = session.createTextMessage(result);
+
+ producer.send(reply);
+ producer.close();
+
+ }
+ catch(Exception e)
+ {
+ e.printStackTrace();
+ System.out.println("The Message Driven Bean failed!");
+ }
+ finally
+ {
+ if (conn != null)
+ {
+ try
+ {
+ conn.close();
+ }
+ catch(Exception e)
+ {
+ System.out.println("Could not close the connection!" +e);
+ }
+ }
+ }
+ }
+}
+ </programlisting>
+
+ <para>The basic test examples in this chapter serve as the sanity check for your JBoss Messaging installation. They also provide basic programming examples. To develop your own JMS services, you probably need to configure JBoss Messaging to setup your own destinations and connection factories etc. In <xref linkend="configuration"/>, we will discuss JBoss Messaging configuration files and options.</para>
+
+ </section>
+
+
+
+</chapter>
More information about the jboss-cvs-commits
mailing list