[jboss-cvs] JBossAS SVN: r93305 - in projects/docs/enterprise/5.0: JBoss_Messaging_1.4.3 and 1 other directories.
jboss-cvs-commits at lists.jboss.org
jboss-cvs-commits at lists.jboss.org
Tue Sep 8 23:35:50 EDT 2009
Author: laubai
Date: 2009-09-08 23:35:49 -0400 (Tue, 08 Sep 2009)
New Revision: 93305
Added:
projects/docs/enterprise/5.0/JBoss_Messaging_1.4.3/
projects/docs/enterprise/5.0/JBoss_Messaging_1.4.3/Makefile
projects/docs/enterprise/5.0/JBoss_Messaging_1.4.3/en-US/
projects/docs/enterprise/5.0/JBoss_Messaging_1.4.3/en-US/About.xml
projects/docs/enterprise/5.0/JBoss_Messaging_1.4.3/en-US/Author_Group.xml
projects/docs/enterprise/5.0/JBoss_Messaging_1.4.3/en-US/Book_Info.xml
projects/docs/enterprise/5.0/JBoss_Messaging_1.4.3/en-US/Bridge.xml
projects/docs/enterprise/5.0/JBoss_Messaging_1.4.3/en-US/C_Configuration.xml
projects/docs/enterprise/5.0/JBoss_Messaging_1.4.3/en-US/Configuration.xml
projects/docs/enterprise/5.0/JBoss_Messaging_1.4.3/en-US/Getting_Started.xml
projects/docs/enterprise/5.0/JBoss_Messaging_1.4.3/en-US/Installation.xml
projects/docs/enterprise/5.0/JBoss_Messaging_1.4.3/en-US/Introduction.xml
projects/docs/enterprise/5.0/JBoss_Messaging_1.4.3/en-US/JBoss_Messaging_User_Guide.ent
projects/docs/enterprise/5.0/JBoss_Messaging_1.4.3/en-US/JBoss_Messaging_User_Guide.xml
projects/docs/enterprise/5.0/JBoss_Messaging_1.4.3/en-US/Preface.xml
projects/docs/enterprise/5.0/JBoss_Messaging_1.4.3/en-US/Recovery_Configuration.xml
projects/docs/enterprise/5.0/JBoss_Messaging_1.4.3/en-US/Revision_History.xml
projects/docs/enterprise/5.0/JBoss_Messaging_1.4.3/en-US/Running_Examples.xml
projects/docs/enterprise/5.0/JBoss_Messaging_1.4.3/en-US/images/
Log:
JBoss Messaging 1.4.3 docs added.
Added: projects/docs/enterprise/5.0/JBoss_Messaging_1.4.3/Makefile
===================================================================
--- projects/docs/enterprise/5.0/JBoss_Messaging_1.4.3/Makefile (rev 0)
+++ projects/docs/enterprise/5.0/JBoss_Messaging_1.4.3/Makefile 2009-09-09 03:35:49 UTC (rev 93305)
@@ -0,0 +1,13 @@
+#Makefile for JBoss_Messaging_User_Guide
+
+XML_LANG = en-US
+BRAND = JBoss
+
+#OTHER_LANGS = as-IN bn-IN de-DE es-ES fr-FR gu-IN hi-IN it-IT ja-JP kn-IN ko-KR ml-IN mr-IN or-IN pa-IN pt-BR ru-RU si-LK ta-IN te-IN zh-CN zh-TW
+
+# Extra Parameters start here
+
+# Extra Parameters stop here
+COMMON_CONFIG = /usr/share/publican
+include $(COMMON_CONFIG)/make/Makefile.common
+
Added: projects/docs/enterprise/5.0/JBoss_Messaging_1.4.3/en-US/About.xml
===================================================================
--- projects/docs/enterprise/5.0/JBoss_Messaging_1.4.3/en-US/About.xml (rev 0)
+++ projects/docs/enterprise/5.0/JBoss_Messaging_1.4.3/en-US/About.xml 2009-09-09 03:35:49 UTC (rev 93305)
@@ -0,0 +1,24 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<chapter id="about">
+ <title>About JBoss Messaging 1.4</title>
+
+ <para>
+ JBoss Messaging is the new enterprise messaging system from JBoss. It is a complete rewrite of JBossMQ, the legacy JBoss Java Message Service (JMS) provider.
+ </para>
+
+ <para>
+ JBoss Messaging is the default JMS provider in JBoss Enterprise Application Platform version 4.3 or later.
+ </para>
+
+ <para>
+ JBoss Messaging is integral to Red Hat's messaging strategy. It offers improvements to performance in both single node and clustered environments, and features a modular architecture so that we can easily add more features in the future.
+ </para>
+
+ <para>
+ This guide shows you how to install, set up, and configure JBoss Messaging for JBoss Enterprise Application Platform.
+ </para>
+
+<!-- <para>Permanent Team: Tim Fox (Project Lead), Jeff Mesnil (Core Developer),
+ Andy Taylor (Core Developer), Clebert Suconic (Core Developer), Howard Gao (Core Developer)</para>-->
+
+</chapter>
Added: projects/docs/enterprise/5.0/JBoss_Messaging_1.4.3/en-US/Author_Group.xml
===================================================================
--- projects/docs/enterprise/5.0/JBoss_Messaging_1.4.3/en-US/Author_Group.xml (rev 0)
+++ projects/docs/enterprise/5.0/JBoss_Messaging_1.4.3/en-US/Author_Group.xml 2009-09-09 03:35:49 UTC (rev 93305)
@@ -0,0 +1,10 @@
+<?xml version='1.0'?>
+<!DOCTYPE authorgroup PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [
+]>
+
+<authorgroup>
+<author>
+ <firstname>Red Hat Documentation Group</firstname>
+ <surname></surname>
+ </author>
+</authorgroup>
Added: projects/docs/enterprise/5.0/JBoss_Messaging_1.4.3/en-US/Book_Info.xml
===================================================================
--- projects/docs/enterprise/5.0/JBoss_Messaging_1.4.3/en-US/Book_Info.xml (rev 0)
+++ projects/docs/enterprise/5.0/JBoss_Messaging_1.4.3/en-US/Book_Info.xml 2009-09-09 03:35:49 UTC (rev 93305)
@@ -0,0 +1,35 @@
+<?xml version='1.0'?>
+<!DOCTYPE bookinfo PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [
+]>
+
+<bookinfo>
+ <title>JBoss Messaging User Guide</title>
+ <subtitle>for Use with JBoss Enterprise Application Platform 5.0</subtitle>
+ <edition>1</edition>
+ <pubsnumber>0</pubsnumber>
+ <productname>JBoss Enterprise Application Platform</productname>
+ <productnumber>5.0</productnumber>
+ <pubdate>September, 2009</pubdate>
+ <abstract>
+ <para>
+ The JBoss Enterprise Application Platform Edition of the JBoss Messaging version 1.4.3 User Guide.
+ </para>
+ </abstract>
+ <corpauthor>
+ <inlinemediaobject>
+ <imageobject>
+ <imagedata format='SVG' fileref="Common_Content/images/title_logo.svg" />
+ </imageobject>
+ <textobject><phrase>Logo</phrase></textobject>
+ </inlinemediaobject>
+ </corpauthor>
+ <copyright>
+ <year>&YEAR;</year>
+ <holder>&HOLDER;</holder>
+ </copyright>
+ <xi:include href="Common_Content/Legal_Notice.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
+ <xi:include href="Author_Group.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
+</bookinfo>
+
+
+
Added: projects/docs/enterprise/5.0/JBoss_Messaging_1.4.3/en-US/Bridge.xml
===================================================================
--- projects/docs/enterprise/5.0/JBoss_Messaging_1.4.3/en-US/Bridge.xml (rev 0)
+++ projects/docs/enterprise/5.0/JBoss_Messaging_1.4.3/en-US/Bridge.xml 2009-09-09 03:35:49 UTC (rev 93305)
@@ -0,0 +1,354 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<chapter id="bridge">
+ <title>JBoss Messaging Message Bridge Configuration</title>
+
+ <section id="bridge.overview">
+ <title>Message Bridge Overview</title>
+
+ <para>
+ JBoss Messaging includes a fully functional message bridge.
+ </para>
+
+ <para>
+ The bridge consumes messages from a source queue or topic and sends them to a target queue or topic, typically on a different server. The source and target servers need not be in the same cluster, so bridging is a reliable method of sending messages from one cluster to another (across a WAN, for example) and where the connection may be unreliable.
+ </para>
+
+ <para>
+ A bridge is deployed as a managed bean within any JBoss Application Server instance. To deploy, simply add the managed bean descriptor into the <filename>deploy</filename> directory of an Enterprise Application Platform configuration that contains JBoss Messaging.
+ </para>
+
+ <para>
+ The example in <filename>docs/example/bridge</filename> demonstrates a simple bridge deployed in JBoss Application Server and moving messages from the source to the target destination.
+ </para>
+
+ <para>
+ The bridge can also be used to retrieve messages from other non-JBoss Messaging JMS servers as long as they are JMS 1.1 compliant.
+ </para>
+
+ <para>
+ The bridge has built-in resistence to failure, so if the source or target server connection is lost, the bridge will attempt to reconnect to the source or target until it comes back online, at which point normal operation will resume.
+ </para>
+
+ <para>
+ The bridge can be configured to consume messages matching a particular JMS selector.
+ </para>
+
+ <para>
+ It can be configured to consume from a queue or a topic. When the bridge consumes from a topic, it can be configured to consume with a non-durable or a durable subscription.
+ </para>
+
+ <para>
+ The bridge can be configured to bridge messages with one of three <emphasis>quality of service</emphasis> levels:
+ </para>
+
+ <itemizedlist>
+ <listitem>
+ <para><literal>QOS_AT_MOST_ONCE</literal></para>
+
+ <para>
+ This mode specifies that messages will arrive at the destination once at the most. Messages are consumed from the source and acknowledged before they are sent to the destination. Therefore, if failure occurs between the message leaving the source and arriving at the destination, messages can be lost. Messages will therefore be delivered once at most. This mode is available for both persistent and non-persistent messages.
+ </para>
+ </listitem>
+<!--hajime-->
+ <listitem>
+ <para><literal>QOS_DUPLICATES_OK</literal></para>
+
+ <para>
+ This mode specifies that messages are consumed from the source and acknowledged after they have been successfully sent to the destination. Therefore, if failure occurs between a message arriving at the destination and being acknowledged by the destination, that message may be sent a second time when the system recovers, so the destination may receive duplicate messages. This mode is available for both persistent and non-persistent messages.
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>QOS_ONCE_AND_ONLY_ONCE</para>
+
+ <para>
+ This mode specifies that messages will arrive exactly once. When the message source and destination are on the same JBoss Messaging server instance, the message can be sent and received in the same local transaction. If the source and destination are on different servers, you can enlist the sending and consuming sessions in a JTA transaction controlled by JBoss Transactions JTA implementation, which provides high durability. If JTA is required, both connection factories must be <literal>XAConnectionFactory</literal> implementations.
+ </para>
+ <para>
+ This mode is only available for persistent messages.
+ </para>
+ <para>
+ Because this mode requires logging on both the transaction manager and the resource side to support recovery, it will likely be the slowest mode. If you require this level of quality of service, you must enable XA Recovery with JBoss Transactions.
+ </para>
+ <note>
+ <title>Alternative Methods</title>
+ <para>
+ You may be able to apply <emphasis>once and only once</emphasis> semantics to a specific application without setting <literal>QOS_ONCE_AND_ONLY_ONCE</literal>. Set <literal>QOS_DUPLICATES_OK</literal> mode, and then check for and discard duplicate messages at the destination. You may be able to implement this at the application level by maintaining a cache of received message IDs on disk and comparing received messages to this cache. Since the cache would only be valid for a certain period of time, this approach is not infallible, but can be a useful alternative depending on your application.
+ </para>
+ </note>
+ </listitem>
+ </itemizedlist>
+ </section>
+
+ <section id="bridge.deployment">
+ <title>Bridge deployment</title>
+
+ <para>
+ You can deploy a message bridge by adding a managed bean descriptor into the <filename>deploy</filename> directory of the JBoss Application Server installation that contains JBoss Messaging.
+ </para>
+ </section>
+
+ <section id="bridge.configuration">
+ <title>Bridge Configuration</title>
+
+ <para>
+ This section shows you how to configure the message bridge.
+ </para>
+ <para>
+ The following code is an example configuration of the message bridge, showing all attributes. Some attributes have been commented out for this configuration, since not all attributes should be specified at once.
+ </para>
+
+ <programlisting>
+ <mbean code="org.jboss.jms.server.bridge.BridgeService"
+ name="jboss.messaging:service=Bridge,name=TestBridge"
+ xmbean-dd="xmdesc/Bridge-xmbean.xml">
+
+ <!-- The JMS provider loader that is used to lookup the source destination -->
+ <depends optional-attribute-name="SourceProviderLoader">
+ jboss.messaging:service=JMSProviderLoader,name=JMSProvider</depends>
+
+ <!-- The JMS provider loader that is used to lookup the target destination -->
+ <depends optional-attribute-name="TargetProviderLoader">
+ jboss.messaging:service=JMSProviderLoader,name=JMSProvider</depends>
+
+ <!-- The JNDI lookup for the source destination -->
+ <attribute name="SourceDestinationLookup">/queue/A</attribute>
+
+ <!-- The JNDI lookup for the target destination -->
+ <attribute name="TargetDestinationLookup">/queue/B</attribute>
+
+ <!-- The username to use for the source connection
+ <attribute name="SourceUsername">bob</attribute>
+ -->
+
+ <!-- The password to use for the source connection
+ <attribute name="SourcePassword">cheesecake</attribute>
+ -->
+
+ <!-- The username to use for the target connection
+ <attribute name="TargetUsername">mary</attribute>
+ -->
+
+ <!-- The password to use for the target connection
+ <attribute name="TargetPassword">hotdog</attribute>
+ -->
+
+ <!-- Optional: The Quality Of Service mode to use, one of:
+ QOS_AT_MOST_ONCE = 0;
+ QOS_DUPLICATES_OK = 1;
+ QOS_ONCE_AND_ONLY_ONCE = 2; -->
+ <attribute name="QualityOfServiceMode">0</attribute>
+
+ <!-- JMS selector to use for consuming messages from the source
+ <attribute name="Selector">specify jms selector here</attribute>
+ -->
+
+ <!-- The maximum number of messages to consume from the source
+ before sending to the target -->
+ <attribute name="MaxBatchSize">5</attribute>
+
+ <!-- The maximum time to wait (in ms) before sending a batch to the target
+ even if MaxBatchSize is not exceeded.
+ -1 means wait forever -->
+ <attribute name="MaxBatchTime">-1</attribute>
+
+ <!-- If consuming from a durable subscription this is the subscription name
+ <attribute name="SubName">mysub</attribute>
+ -->
+
+ <!-- If consuming from a durable subscription this is the client ID to use
+ <attribute name="ClientID">myClientID</attribute>
+ -->
+
+ <!-- The number of ms to wait between connection retrues in the event connections
+ to source or target fail -->
+ <attribute name="FailureRetryInterval">5000</attribute>
+
+ <!-- The maximum number of connection retries to make in case of failure,
+ before giving up -1 means try forever-->
+ <attribute name="MaxRetries">-1</attribute>
+
+ <!-- If true then the message ID of the message before bridging will be added
+ as a header to the message so it is available to the receiver. Can then be
+ sent as correlation ID to correlate in a distributed request-response -->
+ <attribute name="AddMessageIDInHeader">false</attribute>
+
+ </mbean>
+ </programlisting>
+
+ <para>
+ The next section discusses these attributes in detail.
+ </para>
+
+ <section id="bridge.configuration.sourceproviderloader">
+ <title>SourceProviderLoader</title>
+
+ <para>
+ The <literal>JMSProviderLoader</literal> managed bean that the bridge uses to look up the source connection factory and source destination. By default, JBoss Application Server ships with one <literal>JMSProviderLoader</literal>, which is deployed in the <filename>jms-ds.xml</filename> file, and serves as the default local <literal>JMSProviderLoader</literal>. (A clustered configuration would use <filename>hajndi-jms-ds.xml</filename>.)
+ </para>
+ <para>
+ If your source destination is on a different server, or corresponds to a non-JBoss JMS Provider, you can deploy another <literal>JMSProviderLoader</literal> managed bean instance that refers to the remote JMS Provider, and refer to that destination from the second <literal>JMSProviderLoader</literal>. The bridge then uses the remote JMS Provider to contact the source destination.
+ </para>
+ <para>
+ If you want to use <emphasis>once and only once</emphasis> delivery and you are using a remote non-JBoss Messaging source or target, the remote JMS Provider must provide a fully-functional JMS XA resource implementation that works remotely from the server.
+ </para>
+ </section>
+
+ <section id="bridge.configuration.targetproviderloader">
+ <title>TargetProviderLoader</title>
+
+ <para>
+ The <literal>JMSProviderLoader</literal> managed bean used by the bridge to lookup the target connection factory and target destination. By default, JBoss Application Server ships with one <literal>JMSProviderLoader</literal>, which is deployed in the <filename>jms-ds.xml</filename> file, and serves as the default local <literal>JMSProviderLoader</literal>. (A clustered configuration would use <filename>hajndi-jms-ds.xml</filename>.)
+ </para>
+ <para>
+ If your target destination is on a different server, or corresponds to a non-JBoss JMS Provider, you can deploy another <literal>JMSProviderLoader</literal> managed bean instance that refers to the remote JMS Provider, and refer to that destination from the second <literal>JMSProviderLoader</literal>. The bridge then uses the remote JMS Provider to contact the target destination.
+ </para>
+ <para>
+ If you want to use <emphasis>once and only once</emphasis> delivery and you are using a remote non-JBoss Messaging source or target, the remote JMS Provider must provide a fully-functional JMS XA resource implementation that works remotely from the server.
+ </para>
+ </section>
+
+ <section id="bridge.configuration.sourcedestinationlookup">
+ <title>SourceDestinationLookup</title>
+
+ <para>
+ The full JNDI lookup for the source destination, via the <literal>SourceProviderLoader</literal>, such as <filename>/queue/mySourceQueue</filename>.
+ </para>
+ </section>
+
+ <section id="bridge.configuration.targetdestinationlookup">
+ <title>TargetDestinationLookup</title>
+
+ <para>
+ The full JNDI lookup for the target destination, via the <literal>TargetProviderLocator</literal>, such as <filename>/topic/myTargetTopic</filename>.
+ </para>
+ </section>
+
+ <section id="bridge.configuration.sourceusername">
+ <title>SourceUsername</title>
+
+ <para>
+ An optional attribute that specifies the username used when creating the source connection.
+ </para>
+ </section>
+
+ <section id="bridge.configuration.sourcepassword">
+ <title>SourcePassword</title>
+
+ <para>
+ An optional attribute that specifies the password used when creating the source connection.
+ </para>
+ </section>
+
+ <section id="bridge.configuration.targetusername">
+ <title>TargetUsername</title>
+
+ <para>
+ An optional attribute that specifies the username used when creating the raget connection.
+ </para>
+ </section>
+
+ <section id="bridge.configuration.targetpassword">
+ <title>TargetPassword</title>
+
+ <para>
+ An optional attribute that specifies the password used when creating the target connection.
+ </para>
+ </section>
+
+ <section id="bridge.configuration.qualityofservicemode">
+ <title>QualityOfServiceMode</title>
+
+ <para>
+ An integer representing the desired <emphasis>quality of service</emphasis> mode. The possible values are:
+ </para>
+ <itemizedlist>
+ <listitem>
+ <para>
+ <literal>0</literal> to represent <literal>QOS_AT_MOST_ONCE</literal>
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <literal>1</literal> to represent <literal>QOS_DUPLICATES_OK</literal>
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <literal>2</literal> to represent <literal>QOS_ONCE_AND_ONLY_ONCE</literal>
+ </para>
+ </listitem>
+ </itemizedlist>
+ <para>
+ See <xref linkend="bridge.overview" /> for a complete explanation of these modes.
+ </para>
+ </section>
+
+ <section id="bridge.configuration.selector">
+ <title>Selector</title>
+
+ <para>
+ An optional attribute that lets you provide a JMS selector expression when consuming messages from a source destination. Only messages that match the selector expression are bridged from the source to the target destination. The selector expression must follow the JMS selector syntax, specified here: <ulink url="http://java.sun.com/j2ee/1.4/docs/api/javax/jms/Message.html" />.
+ </para>
+ <para>
+ For optimal performance, apply source topic subscription selectors to source queue consumers.
+ </para>
+ </section>
+
+ <section id="bridge.configuration.maxbatchsize">
+ <title>MaxBatchSize</title>
+
+ <para>
+ Specifies the maximum number of messages to consume from the source destination before sending a message batch to the target destination. Its value must be greater than or equal to <literal>1</literal>.
+ </para>
+ </section>
+
+ <section id="bridge.configuration.maxbatchtime">
+ <title>MaxBatchTime</title>
+
+ <para>
+ Specifies the longest period (in milliseconds) to wait before sending a message batch to the target, even if the <varname>MaxBatchSize</varname> has not been reached. Its value must be either <literal>-1</literal> (wait forever) or greater than or equal to <literal>1</literal> to specify a time.
+ </para>
+ </section>
+
+ <section id="bridge.configuration.subname">
+ <title>SubName</title>
+
+ <para>
+ Represents the name of the durable subscription that will consume from the source destination topic.
+ </para>
+ </section>
+
+ <section id="bridge.configuration.clientid">
+ <title>ClientID</title>
+
+ <para>
+ Represents the JMS client ID to use when creating or looking up the durable subscription that will consume from the source destination topic.
+ </para>
+ </section>
+
+ <section id="bridge.configuration.failureretryinterval">
+ <title>FailureRetryInterval</title>
+
+ <para>
+ The period of time (in milliseconds) to wait between attempting to recreate the connection to the source or target server after failure is detected.
+ </para>
+ </section>
+
+ <section id="bridge.configuration.maxretries">
+ <title>MaxRetries</title>
+
+ <para>
+ The number of times to attempt to recreate the connection to the source or target server after failure is detected. The bridge will then stop attempting to recreate the connection. A value of <literal>-1</literal> means that the bridge will continue to attempt to reconnect forever.
+ </para>
+ </section>
+
+ <section id="bridge.configuration.addmessageidinheader">
+ <title>AddMessageIDInHeader</title>
+
+ <para>
+ When <literal>true</literal>, the original message ID is added to the <literal>JBossMessage.JBOSS_MESSAGING_BRIDGE_MESSAGE_ID_LIST</literal> header of the message being sent to the destination. If the message is bridged multiple times, each message ID is added to the header. This enables a distributed request-response pattern.
+ </para>
+ </section>
+ </section>
+</chapter>
Added: projects/docs/enterprise/5.0/JBoss_Messaging_1.4.3/en-US/C_Configuration.xml
===================================================================
--- projects/docs/enterprise/5.0/JBoss_Messaging_1.4.3/en-US/C_Configuration.xml (rev 0)
+++ projects/docs/enterprise/5.0/JBoss_Messaging_1.4.3/en-US/C_Configuration.xml 2009-09-09 03:35:49 UTC (rev 93305)
@@ -0,0 +1,98 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<chapter id="c_configuration">
+ <title>JBoss Messaging Clustering Notes</title>
+
+ <section id="c_conf.serverpeerid">
+ <title>Unique server peer id</title>
+
+ <para>
+ In most cases, JBoss Messaging works in a clustered environment with no configuration changes. However, it is crucial that every node is assigned a unique server ID, as specified in the Installation Guide.
+ </para>
+ <para>
+ Every deployed node must have a unique ID, including nodes that form a LAN cluster and nodes linked by message bridges.
+ </para>
+ </section>
+
+ <section id="c_conf.clustereddests">
+ <title>Clustered destinations</title>
+
+ <para>
+ JBoss Messaging clusters Java Message Service (JMS) queues and topics transparently across the cluster. Messages sent to a distributed queue or topic on one node are consumable on other nodes. To make a particular destination clustered, set the <varname>clustered</varname> attribute in the destination Deployment Descriptor to <literal>true</literal>.
+ </para>
+ <para>
+ JBoss Messaging balances messages between nodes and caters for consumers of varying speeds so that processing load is distributed efficiently across the cluster.
+ </para>
+
+ <para>
+ To disable message redistribution between nodes while retaining other characteristics of clustered destinations, do not specify the <varname>ClusterPullConnectionFactoryName</varname> attribute on the Server Peer.
+ </para>
+ </section>
+
+ <section id="c_conf.clustereddursubs">
+ <title>Clustered durable subscriptions</title>
+
+ <para>
+ It is also possible to cluster JBoss Messaging durable subscriptions such that multiple subscribers on multiple nodes can consume from one durable subscription. A durable subscription will be clustered if its topic is clustered.
+ </para>
+ </section>
+
+ <section id="c_conf.clusteredtempdest">
+ <title>Clustered temporary destinations</title>
+
+ <para>
+ JBoss Messaging supports clustering of temporary topics and queues. All temporary topics and queues will be clustered if the Post Office is clustered.
+ </para>
+ </section>
+
+ <section id="c_conf.nonclusteredserver">
+ <title>Non-clustered servers</title>
+
+ <para>
+ Set the <literal>PostOffice</literal>'s <varname>clustered</varname> attribute to <literal>false</literal> if you do not want all nodes to participate in a cluster, or if you do not want the server to be clustered.
+ </para>
+ </section>
+
+ <section id="c_conf.orderingincluster">
+ <title>Message ordering in the cluster</title>
+
+ <para>
+ To apply strict JMS ordering to messages such that messages are consumed in the same order they were produced, set the <varname>DefaultPreserveOrdering</varname> Server Peer attribute to <literal>true</literal>. (The default value is <literal>false</literal>.) While set to <literal>true</literal>, messages cannot be distributed as freely around the cluster.
+ </para>
+ </section>
+
+ <section id="c_conf.idempotentops">
+ <title>Idempotent operations</title>
+
+ <para>
+ If the call to send a persistent message to a persistent destination returns with no exception, then they message has definitely been persisted. However, if an exception is thrown, you cannot be certain that the message was <emphasis>not</emphasis> persisted, because failure may have occurred between the message being persisted and a response being returned to the caller.
+ </para>
+
+ <para>
+ Your applications must therefore be coded so that its operations are <emphasis>idempotent</emphasis> — that is, they can be repeated without causing the system to become inconsistent.
+ </para>
+
+ <para>
+ In a messaging system, you can do this on the application level by checking for duplicate messages and discarding them if the original message has been sent successfully. This <emphasis>duplicate checking</emphasis> is a powerful technique that can remove the need for XA transactions.
+ </para>
+
+ <para>
+ In a clustered environment, JBoss Messaging is configured to perform duplicate checking by default.
+ </para>
+ </section>
+
+ <section id="c_conf.clusteredcfs">
+ <title>Clustered connection factories</title>
+
+ <para>
+ When <varname>supportsLoadBalancing</varname> is set to <literal>true</literal>, consecutive attempts to create connections will round-robin between available servers. The first node is chosen randomly.
+ </para>
+
+ <para>
+ When <varname>supportsFailover</varname> is set to <literal>true</literal>, failover will occur transparently and automatically whenever any connection error is detected.
+ </para>
+
+ <para>
+ If automatic failover is not required, set <varname>supportsFailover</varname> to <literal>false</literal> and provide a standard JMS <literal>ExceptionListener</literal> to be called in case of server failure. Following server failure, you will need to manually close the connection, lookup a new connection factory from HAJNDI, and create a new connection.
+ </para>
+ </section>
+</chapter>
\ No newline at end of file
Added: projects/docs/enterprise/5.0/JBoss_Messaging_1.4.3/en-US/Configuration.xml
===================================================================
--- projects/docs/enterprise/5.0/JBoss_Messaging_1.4.3/en-US/Configuration.xml (rev 0)
+++ projects/docs/enterprise/5.0/JBoss_Messaging_1.4.3/en-US/Configuration.xml 2009-09-09 03:35:49 UTC (rev 93305)
@@ -0,0 +1,2085 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<chapter id="configuration">
+ <title>Configuration</title>
+
+ <para>
+ The Java Message Service (JMS) API specifies how a messaging client interacts with a messaging server. How messaging services such as message destinations and connection factories are defined and implemented depends on the JMS provider. JBoss Messaging has its own files for service configutation. <!--If you are migrating services from JBossMQ (or other JMS provider) to JBoss Messaging, you will need to understand those configuration files.-->
+ </para>
+
+ <para>
+ This chapter shows you how to configure various services available in JBoss Messaging that work together to provide JMS API-level services to client applications.
+ </para>
+
+ <para>
+ JBoss Messaging configuration is divided between several configuration files. Depending on the type of service provided, configuration information is divided between <filename>messaging-service.xml</filename>, <filename>remoting-bisocket-service.xml</filename>, <filename><your database type>-persistence-service.xml</filename>, <filename>connection-factories-service.xml</filename> and <filename>destinations-service.xml</filename>.
+ </para>
+
+ <para>
+ AOP interceptor stacks can be configured in <filename>aop-messaging-client.xml</filename> (for client-side behavior) and <filename>aop-messaging-server.xml</filename> (for server-side behavior). There is usually no need to change these files, but some interceptors can be removed to improve performance if they are not required. Ensure that you have considered the security implications before removing the security interceptor.
+ </para>
+
+ <section id="conf.serverpeer">
+ <title>Configuring the ServerPeer</title>
+
+ <para>
+ The <literal>ServerPeer</literal> is the heart of the JBoss Messaging JMS facade. You can configure its behaviour by altering <filename>messaging-service.xml</filename>.
+ </para>
+
+ <para>
+ All JBoss Messaging services are based in the <literal>ServerPeer</literal>.
+ </para>
+
+ <para>An example of a Server Peer configuration is presented below. Note
+ that not all values for the server peer's attributes are specified in the
+ example</para>
+
+ <programlisting>
+ <!-- ServerPeer MBean configuration
+ ============================== -->
+ <mbean code="org.jboss.jms.server.ServerPeer"
+ name="jboss.messaging:service=ServerPeer"
+ xmbean-dd="xmdesc/ServerPeer-xmbean.xml">
+
+ <!-- The unique id of the server peer - in a cluster each node MUST have a unique value - must be an integer -->
+
+ <attribute name="ServerPeerID">0</attribute>
+
+ <!-- The default JNDI context to use for queues when they are deployed without specifying one -->
+
+ <attribute name="DefaultQueueJNDIContext">/queue</attribute>
+
+ <!-- The default JNDI context to use for topics when they are deployed without specifying one -->
+
+ <attribute name="DefaultTopicJNDIContext">/topic</attribute>
+
+ <attribute name="PostOffice">jboss.messaging:service=PostOffice</attribute>
+
+ <!-- The default Dead Letter Queue (DLQ) to use for destinations.
+ This can be overridden on a per destinatin basis -->
+
+ <attribute name="DefaultDLQ">jboss.messaging.destination:service=Queue,name=DLQ</attribute>
+
+ <!-- The default maximum number of times to attempt delivery of a message before sending to the DLQ (if configured).
+ This can be overridden on a per destinatin basis -->
+
+ <attribute name="DefaultMaxDeliveryAttempts">10</attribute>
+
+ <!-- The default Expiry Queue to use for destinations. This can be overridden on a per destinatin basis -->
+
+ <attribute name="DefaultExpiryQueue">jboss.messaging.destination:service=Queue,name=ExpiryQueue</attribute>
+
+ <!-- The default redelivery delay to impose. This can be overridden on a per destination basis -->
+
+ <attribute name="DefaultRedeliveryDelay">0</attribute>
+
+ <!-- The periodicity of the message counter manager enquiring on queues for statistics -->
+
+ <attribute name="MessageCounterSamplePeriod">5000</attribute>
+
+ <!-- The maximum amount of time for a client to wait for failover to start on the server side after
+ it has detected failure -->
+
+ <attribute name="FailoverStartTimeout">60000</attribute>
+
+ <!-- The maximum amount of time for a client to wait for failover to complete on the server side after
+ it has detected failure -->
+
+ <attribute name="FailoverCompleteTimeout">300000</attribute>
+
+ <!-- The maximum number of days results to maintain in the message counter history -->
+
+ <attribute name="DefaultMessageCounterHistoryDayLimit">-1</attribute>
+
+ <!-- The name of the connection factory to use for creating connections between nodes to pull messages -->
+
+ <attribute name="ClusterPullConnectionFactoryName">jboss.messaging.connectionfactory:service=ClusterPullConnectionFactory</attribute>
+
+ <!-- When redistributing messages in the cluster. Do we need to preserve the order of messages received
+ by a particular consumer from a particular producer? -->
+
+ <attribute name="DefaultPreserveOrdering">false</attribute>
+
+ <!-- Max. time to hold previously delivered messages back waiting for clients to reconnect after failover -->
+
+ <attribute name="RecoverDeliveriesTimeout">300000</attribute>
+
+ <attribute name="EnableMessageCounters">false</attribute>
+
+
+ <!-- The password used by the message sucker connections to create connections.
+ THIS SHOULD ALWAYS BE CHANGED AT INSTALL TIME TO SECURE SYSTEM
+ <attribute name="SuckerPassword"></attribute>
+ -->
+
+ <depends optional-attribute-name="PersistenceManager">jboss.messaging:service=PersistenceManager</depends>
+
+ <depends optional-attribute-name="JMSUserManager">jboss.messaging:service=JMSUserManager</depends>
+
+ <depends>jboss.messaging:service=Connector,transport=bisocket</depends>
+ <depends optional-attribute-name="SecurityStore" proxy-type="org.jboss.jms.server.SecurityStore">jboss.messaging:service=SecurityStore</depends>
+
+ </mbean>
+</programlisting>
+
+ <section id="conf.serverpeer.attributes">
+ <title>ServerPeer attributes</title>
+
+ <para>
+ This section discusses the <literal>ServerPeer</literal> managed bean attributes.
+ </para>
+
+ <section id="conf.serverpeer.attributes.serverpeerid">
+ <title>ServerPeerID</title>
+
+ <para>
+ The unique identifier of the <literal>ServerPeer</literal>. Each node deployed must have a unique identifier, whether the nodes form a cluster or are linked by a message bridge. The identifier must be a valid integer.
+ </para>
+ </section>
+
+ <section id="conf.serverpeer.attributes.defaultqueuejndicontext">
+ <title>DefaultQueueJNDIContext</title>
+
+ <para>
+ The default JNDI context to be used when binding queues. The default value is <literal>/queue</literal>.
+ </para>
+ </section>
+
+ <section id="conf.serverpeer.attributes.defaultopicjndicontext">
+ <title>DefaultTopicJNDIContext</title>
+
+ <para>
+ The default JNDI context to be used when binding topics. The default value is <literal>/topic</literal>.
+ </para>
+ </section>
+
+ <section id="conf.serverpeer.attributes.postoffice">
+ <title>PostOffice</title>
+
+ <para>
+ The post office used by the <literal>ServerPeer</literal>. You will not normally need to edit this attribute. The post office routes messages to queues and maintains the mapping between queues and addresses.
+ </para>
+ </section>
+
+ <section id="conf.serverpeer.attributes.defaultdlq">
+ <title>DefaultDLQ</title>
+
+ <para>
+ The default DLQ (Dead Letter Queue) that the server uses for destinations. You can override the DLQ on a per-destination basis. (For more information, see the configuration information for the destination managed bean.) A DLQ is a destination for messages that the server has failed to deliver more than a certain number of times. If the DLQ is not specified, the message will be removed after the maximum number of delivery attempts. You can specify a global default for the maximum number of delivery attempts with the <varname>DefaultMaxDeliveryAttempts</varname> attribute, or set the maximum individually on a per-destination basis.
+ </para>
+ </section>
+
+ <section id="conf.serverpeer.attributes.defaultmaxdeliveryattempts">
+ <title>DefaultMaxDeliveryAttempts</title>
+
+ <para>
+ The global default for the maximum number of times delivery will be attempted for a message before the message is removed or sent to the DLQ, if configured. The default value is <literal>10</literal>. You can override this value on a per-destination basis.
+ </para>
+ </section>
+
+ <section id="conf.serverpeer.attributes.defaultexpiryqueue">
+ <title>DefaultExpiryQueue</title>
+
+ <para>
+ The default expiry queue that the <literal>ServerPeer</literal> will use for destinations. You can override this value on a per-destination basis, as seen in the section on destination managed bean configuration. An expiry queue holds messages that have expired. Message expiry is determined by the value of <literal>Message::getJMSExpiration()</literal>. If the expiry queue is not specified, the message will be deleted when it expires.
+ </para>
+ </section>
+
+ <section id="conf.serverpeer.attributes.defaultredliverydelay">
+ <title>DefaultRedeliveryDelay</title>
+
+ <para>
+ This attribute lets you delay a redelivery attempt, which helps to prevent thrashing delivery-failure. The default value is <literal>0</literal> (that is, no delay). You can override this value on a per-destination basis.
+ </para>
+ </section>
+
+ <section id="conf.serverpeer.attributes.messagecountersampleperiod">
+ <title>MessageCounterSamplePeriod</title>
+
+ <para>
+ This attribute defines the period of time between the server's queries to the queue for queue statistics. The default value is <literal>10000</literal> milliseconds.
+ </para>
+ </section>
+
+ <section id="conf.serverpeer.attributes.failoverstarttimeout">
+ <title>FailoverStartTimeout</title>
+
+ <para>
+ The longest period (in milliseconds) that the client will wait for failover to begin on the server side when a problem is detected. The default value is <literal>60000</literal> (one minute).
+ </para>
+ </section>
+
+ <section id="conf.serverpeer.attributes.failovercompletetimeout">
+ <title>FailoverCompleteTimeout</title>
+
+ <para>
+ The longest period (in milliseconds) that the client will wait for failover to complete on the server side once failover has been initiated. The default value is <literal>300000</literal> (five minutes).
+ </para>
+ </section>
+
+ <section id="conf.serverpeer.attributes.defaultmessagecounterhistorydaylimit">
+ <title>DefaultMessageCounterHistoryDayLimit</title>
+
+ <para>
+ JBoss Messaging provides a message counter history, which shows the number of messages arriving on each queue over a certain number of days. This attribute represents the maximum number of days for which to store message counter history. You can override this value on a per-destination.
+ </para>
+ </section>
+
+ <section id="conf.serverpeer.attributes.clusterpullconnectionfactory">
+ <title>ClusterPullConnectionFactory</title>
+
+ <para>
+ The connection factory used to pull, or suck, messages between queues. You can omit this attribute to disable message sucking while retaining failover.
+ </para>
+ </section>
+
+ <section id="conf.serverpeer.attributes.defaultpreserveordering">
+ <title>DefaultPreserveOrdering</title>
+
+ <para>
+ When <literal>true</literal>, JMS ordering is preserved in the cluster. See the Cluster Configuration section for more detail. The default value is <literal>false</literal>.
+ </para>
+ </section>
+
+ <section id="conf.serverpeer.attributes.recoverdeliveriestimeout">
+ <title>RecoverDeliveriesTimeout</title>
+
+ <para>
+ When failover occurs, messages that have been delivered will be stored while the clients reconnect. If the clients do not reconnect (for example, if the client is dead), these messages will eventually time out and be added to the queue. This attribute sets the period before timeout in milliseconds. The default value is <literal>300000</literal> (five minutes).
+ </para>
+ </section>
+
+ <section id="conf.serverpeer.attributes.enablemessagecounters">
+ <title>EnableMessageCounters</title>
+
+ <para>
+ When set to <literal>true</literal>, enables message counters upon server start.
+ </para>
+ </section>
+
+ <section id="conf.serverpeer.attributes.suckerpassword">
+ <title>SuckerPassword</title>
+
+ <para>
+ JBoss Messaging internally creates connections between nodes to redistribute messages between clustered destinations. These connections are created with a special, reserved username. This attribute defines the password to use when creating these connections.
+ </para>
+ <para>
+ For versions of JBoss Messaging later than 1.4.1.GA, you must define the <varname>SuckerPassword</varname> on the <literal>SecurityMetadataStore</literal>.
+ </para>
+ <warning>
+ <para>
+ The <varname>SuckerPassword</varname> must be changed at install time, or the default password will be used, giving any user who knows the default password access to any destination on the server.
+ </para>
+ </warning>
+ </section>
+
+ <section id="conf.serverpeer.attributes.stricttck">
+ <title>StrictTCK</title>
+
+ <para>
+ To enable strict JMS Technology Compatibility Kit (TCK) semantics, set this attribute to <literal>true</literal>.
+ </para>
+ </section>
+
+ <section id="conf.serverpeer.attributes.destinations">
+ <title>Destinations</title>
+
+ <para>
+ Returns a list of the destinations (queues and topics) currently deployed.
+ </para>
+ </section>
+
+ <section id="conf.serverpeer.attributes.messagecounters">
+ <title>MessageCounters</title>
+
+ <para>
+ A message counter for a particular queue.
+ </para>
+ </section>
+
+ <section id="conf.serverpeer.attributes.messagecounterstatistics">
+ <title>MessageCountersStatistics</title>
+
+ <para>
+ Statistics about each message counter for each queue.
+ </para>
+ </section>
+
+ <section id="conf.serverpeer.attributes.supportsfailover">
+ <title>SupportsFailover</title>
+
+ <para>
+ When this attribute is <literal>false</literal>, server-side failover does not occur when a node crashes in a cluster.
+ </para>
+ </section>
+
+ <section id="conf.serverpeer.attributes.persistencemanager">
+ <title>PersistenceManager</title>
+
+ <para>
+ The persistence manager used by the <literal>ServerPeer</literal>. (You will not normally need to change this attribute.)
+ </para>
+ </section>
+
+ <section id="conf.serverpeer.attributes.jmsusermanager">
+ <title>JMSUserManager</title>
+
+ <para>
+ The JMS user manager used by the <literal>ServerPeer</literal>. (You will not normally need to change this attribute.)
+ </para>
+ </section>
+
+ <section id="conf.serverpeer.attributes.securitystore">
+ <title>SecurityStore</title>
+
+ <para>
+ The pluggable <literal>SecurityStore</literal>. If you redefine this attribute, remember that you will need to authenticate the <literal>MessageSucker</literal> user (<literal>JBM.SUCKER</literal>) with all special permissions required by clustering.
+ </para>
+ </section>
+
+ <section id="conf.serverpeer.operations">
+ <title>Managed Beans in the ServerPeer</title>
+
+ <section id="conf.serverpeer.operations.deployQueue">
+ <title>DeployQueue</title>
+
+ <para>
+ Used to programmatically deploy a queue. If the queue exists but is undeployed, it will be deployed. Otherwise, it is created and deployed.
+ </para>
+ <para>
+ The <varname>name</varname> parameter matches a destination to deploy.
+ </para>
+ <para>
+ The optional <varname>jndiName</varname> parameter represents the full JNDI name of the location to which a destination will be bound. If this is not specified, the destination will be bound in <literal><DefaultQueueJNDIContext>/<name></literal>.
+ </para>
+ <para>
+ There are two overloaded versions of this operation. The first deploys the destination with default paging parameters. The second deploys the destination with the paging parameters specified. For more information about paging parameters, see the section on Configuring Destinations.
+ </para>
+ </section>
+
+ <section id="conf.serverpeer.operations.undeployQueue">
+ <title>UndeployQueue</title>
+
+ <para>
+ Used to programmatically undeploy a queue. Queues are not removed from persistent storage. This operation returns <literal>true</literal> if the queue is successfully undeployed. Otherwise, it returns <literal>false</literal>.
+ </para>
+ </section>
+
+ <section id="conf.serverpeer.operations.destroyQueue">
+ <title>DestroyQueue</title>
+
+ <para>
+ Used to programmatically destroy a queue. Queues are undeployed and all of their data is removed from the database and destroyed.
+ </para>
+ <warning>
+ <para>
+ Exercise caution when using this method, since it will delete all data for the queue.
+ </para>
+ </warning>
+ <para>
+ This operation returns <literal>true</literal> if the queue was destroyed successfully. Otherwise, it returns <literal>false</literal>.
+ </para>
+ </section>
+
+ <section id="conf.serverpeer.operations.deployTopic">
+ <title>DeployTopic</title>
+
+ <para>
+ Used to programmatically deploy a topic. There are two overloaded versions of this operation. The first deploys already existing topics with the default paging parameters. The second creates and deploys topics with specified paging parameters. See the section on Configuring Destinations for more information.
+ </para>
+ <para>
+ The <varname>name</varname> parameter represents the name of the destination to deploy.
+ </para>
+ <para>
+ The <varname>jndiName</varname> represents the full JNDI name of the location to which the destination will be bound. If this is not specified, the destination will be bound in <literal><DefaultTopicJNDIContext>/<name></literal>.
+ </para>
+ </section>
+
+ <section id="conf.serverpeer.operations.undeployTopic">
+ <title>UndeployTopic</title>
+
+ <para>
+ Used to programmatically undeploy a topic. Topics are undeployed, but not removed from persistent storage. This operation returns <literal>true</literal> if the topic is undeployed successfully. Otherwise, <literal>false</literal> is returned.
+ </para>
+ </section>
+
+ <section id="conf.serverpeer.operations.destroyTopic">
+ <title>DestroyTopic</title>
+
+ <para>
+ Used to programmatically destroy a topic. Topics are undeployed and all data is removed from the database and destroyed. This operation returns <literal>true</literal> if the topic is successfully destroyed. Otherwise, it returns <literal>false</literal>.
+ </para>
+ <warning>
+ <para>
+ Exercise caution when using this method, since it will delete all data for the topic.
+ </para>
+ </warning>
+ </section>
+
+ <section id="conf.serverpeer.operations.listmessagecountersashtml">
+ <title>ListMessageCountersHTML</title>
+
+ <para>
+ Returns message counters in a simply-displayed HTML format.
+ </para>
+ </section>
+
+ <section id="conf.serverpeer.operations.resetallmessagecounters">
+ <title>ResetAllMesageCounters</title>
+
+ <para>Resets all message counters to zero.</para>
+ </section>
+
+ <section id="conf.serverpeer.operations.resetallmessagecounterhistories">
+ <title>ResetAllMesageCounters</title>
+
+ <para>Resets all message counter histories to zero.</para>
+ </section>
+
+ <section id="conf.serverpeer.operations.enablemessagecounters">
+ <title>EnableMessageCounters</title>
+
+ <para>Enables all message counters for all destinations. Message counters are disabled by default.</para>
+ </section>
+
+ <section id="conf.serverpeer.operations.disablemessagecounters">
+ <title>DisableMessageCounters</title>
+
+ <para>Disables all message counters for all destinations. Message counters are disabled by default.</para>
+ </section>
+
+ <section id="conf.serverpeer.operations.retrievepreparedtransactions">
+ <title>RetrievePreparedTransactions</title>
+
+ <para>Retrieves a list of the XIDs for all transactions currently in a prepared state on the node.</para>
+ </section>
+
+ <section id="conf.serverpeer.operations.showpreparedtransactions">
+ <title>ShowPreparedTransactions</title>
+
+ <para>Retrieves a list of the XIDs for all transactions currently in a prepared state on the node in an easily-displayed HTML format.</para>
+ </section>
+ </section>
+ </section>
+ </section>
+
+ <section id="conf.changingds">
+ <title>Changing the Database</title>
+
+ <para>
+ The Persistence Manager, Post Office and JMS User Manager all interact with persistent storage. The Persistence Manager handles message-related persistence. The Post Office handles binding related persistence. The JMS User Manager handles user-related persistence. All configuration for these managed beans is handled in the <filename><your database type>-persistence-service.xml</filename> file.
+ </para>
+
+ <para>
+ Example configuration files for MySQL, Oracle, PostgreSQL, Microsoft SQL Server or Sybase databases are available in the <filename>examples/config</filename> directory of the release bundle.
+ </para>
+
+ <para>
+ To enable support for one of these databases, replace the default <filename>hsqldb-persistence-service.xml</filename> configuration file with the configuration file specific to your database type and restart the server.
+ </para>
+
+ <para>
+ By default, the messaging services relying on a data store reference <literal>java:/DefaultDS</literal> for the data source. To deploy a data source with a different JNDI name, you must update all <literal>DataSource</literal> attributes in the persistence configuration file. We include example data source configurations in the distribution.
+ </para>
+ </section>
+
+ <section id="conf.postoffice">
+ <title>Configuring the Post office</title>
+
+ <para>
+ The post office routes messages to their destination or destinations. It maintains the mappings between the addresses to which a message can be sent, and the final queue. For example, when sending a message with an address that represents a JMS queue, the post office routes the message to that JMS queue. When sending a message with an address that represents a JMS topic, the post office routes the message to a set of queues — one for each JMS subscription.
+ </para>
+
+ <para>The post office also handles the persistence for address mapping.</para>
+
+ <para>
+ JBoss Messaging post offices are cluster-aware. In a cluster, they automatically route and pull messages between nodes in order to provide fully-distributed JMS queues and topics.
+ </para>
+
+ <para>
+ You can configure the post office in your <filename><your database type>-persistence-service.xml</filename> file. For example:
+ </para>
+
+ <programlisting>
+<mbean code="org.jboss.messaging.core.jmx.MessagingPostOfficeService"
+ name="jboss.messaging:service=PostOffice"
+ xmbean-dd="xmdesc/MessagingPostOffice-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>
+
+ <!-- The name of the post office -->
+
+ <attribute name="PostOfficeName">JMS post office</attribute>
+
+ <!-- The datasource used by the post office to access it's binding information -->
+
+ <attribute name="DataSource">java:/DefaultDS</attribute>
+
+ <!-- If true will attempt to create tables and indexes on every start-up -->
+
+ <attribute name="CreateTablesOnStartup">true</attribute>
+
+
+ <!-- If true then we will automatically detect and reject duplicate messages sent during failover -->
+
+ <attribute name="DetectDuplicates">true</attribute>
+
+ <!-- The size of the id cache to use when detecting duplicate messages -->
+
+ <attribute name="IDCacheSize">500</attribute>
+
+
+ <attribute name="SqlProperties"><![CDATA[
+CREATE_POSTOFFICE_TABLE=CREATE TABLE JBM_POSTOFFICE (POSTOFFICE_NAME VARCHAR(255), NODE_ID INTEGER, QUEUE_NAME VARCHAR(255), COND VARCHAR(1023), SELECTOR VARCHAR(1023), CHANNEL_ID BIGINT, CLUSTERED CHAR(1), ALL_NODES CHAR(1), PRIMARY KEY(POSTOFFICE_NAME, NODE_ID, QUEUE_NAME)) ENGINE = INNODB
+INSERT_BINDING=INSERT INTO JBM_POSTOFFICE (POSTOFFICE_NAME, NODE_ID, QUEUE_NAME, COND, SELECTOR, CHANNEL_ID, CLUSTERED, ALL_NODES) VALUES (?, ?, ?, ?, ?, ?, ?, ?)
+DELETE_BINDING=DELETE FROM JBM_POSTOFFICE WHERE POSTOFFICE_NAME=? AND NODE_ID=? AND QUEUE_NAME=?
+LOAD_BINDINGS=SELECT QUEUE_NAME, COND, SELECTOR, CHANNEL_ID, CLUSTERED, ALL_NODES FROM JBM_POSTOFFICE WHERE POSTOFFICE_NAME=? AND NODE_ID=?
+ ]]></attribute>
+
+ <!-- This post office is clustered. If you don't want a clustered post office then set to false -->
+
+ <attribute name="Clustered">true</attribute>
+
+ <!-- All the remaining properties only have to be specified if the post office is clustered.
+ You can safely comment them out if your post office is non clustered -->
+
+ <!-- The JGroups group name that the post office will use -->
+
+ <attribute name="GroupName">${jboss.messaging.groupname:MessagingPostOffice}</attribute>
+
+ <!-- Max time to wait for state to arrive when the post office joins the cluster -->
+
+ <attribute name="StateTimeout">5000</attribute>
+
+ <!-- Max time to wait for a synchronous call to node members using the MessageDispatcher -->
+
+ <attribute name="CastTimeout">50000</attribute>
+
+ <!-- Set this to true if you want failover of connections to occur when a node is shut down -->
+
+ <attribute name="FailoverOnNodeLeave">false</attribute>
+
+
+ <!-- JGroups stack configuration for the data channel - used for sending data across the cluster -->
+
+ <!-- By default we use the TCP stack for data -->
+ <attribute name="DataChannelConfig">
+ <config>
+ <TCP start_port="7900"
+ loopback="true"
+ recv_buf_size="20000000"
+ send_buf_size="640000"
+ discard_incompatible_packets="true"
+ max_bundle_size="64000"
+ max_bundle_timeout="30"
+ use_incoming_packet_handler="true"
+ use_outgoing_packet_handler="false"
+ down_thread="false" up_thread="false"
+ enable_bundling="false"
+ use_send_queues="false"
+ sock_conn_timeout="300"
+ skip_suspected_members="true"/>
+ <MPING timeout="4000"
+ bind_to_all_interfaces="true"
+ mcast_addr="${jboss.messaging.datachanneludpaddress:228.6.6.6}"
+ mcast_port="${jboss.messaging.datachanneludpport:45567}"
+ ip_ttl="8"
+ num_initial_members="2"
+ num_ping_requests="1"/>
+ <MERGE2 max_interval="100000"
+ down_thread="false" up_thread="false" min_interval="20000"/>
+ <FD_SOCK down_thread="false" up_thread="false"/>
+ <VERIFY_SUSPECT timeout="1500" down_thread="false" up_thread="false"/>
+ <pbcast.NAKACK max_xmit_size="60000"
+ use_mcast_xmit="false" gc_lag="0"
+ retransmit_timeout="300,600,1200,2400,4800"
+ down_thread="false" up_thread="false"
+ discard_delivered_msgs="true"/>
+ <pbcast.STABLE stability_delay="1000" desired_avg_gossip="50000"
+ down_thread="false" up_thread="false"
+ max_bytes="400000"/>
+ <pbcast.GMS print_local_addr="true" join_timeout="3000"
+ down_thread="false" up_thread="false"
+ join_retry_timeout="2000" shun="false"
+ view_bundling="true"/>
+ </config>
+ </attribute>
+
+ <!-- JGroups stack configuration to use for the control channel - used for control messages -->
+
+ <!-- We use udp stack for the control channel -->
+ <attribute name="ControlChannelConfig">
+ <config>
+ <UDP
+ mcast_addr="${jboss.messaging.controlchanneludpaddress:228.7.7.7}"
+ mcast_port="${jboss.messaging.controlchanneludpport:45568}"
+ tos="8"
+ ucast_recv_buf_size="20000000"
+ ucast_send_buf_size="640000"
+ mcast_recv_buf_size="25000000"
+ mcast_send_buf_size="640000"
+ loopback="false"
+ discard_incompatible_packets="true"
+ max_bundle_size="64000"
+ max_bundle_timeout="30"
+ use_incoming_packet_handler="true"
+ use_outgoing_packet_handler="false"
+ ip_ttl="2"
+ down_thread="false" up_thread="false"
+ enable_bundling="false"/>
+ <PING timeout="2000"
+ down_thread="false" up_thread="false" num_initial_members="3"/>
+ <MERGE2 max_interval="100000"
+ down_thread="false" up_thread="false" min_interval="20000"/>
+ <FD_SOCK down_thread="false" up_thread="false"/>
+ <FD timeout="10000" max_tries="5" down_thread="false" up_thread="false" shun="true"/>
+ <VERIFY_SUSPECT timeout="1500" down_thread="false" up_thread="false"/>
+ <pbcast.NAKACK max_xmit_size="60000"
+ use_mcast_xmit="false" gc_lag="0"
+ retransmit_timeout="300,600,1200,2400,4800"
+ down_thread="false" up_thread="false"
+ discard_delivered_msgs="true"/>
+ <UNICAST timeout="300,600,1200,2400,3600"
+ down_thread="false" up_thread="false"/>
+ <pbcast.STABLE stability_delay="1000" desired_avg_gossip="50000"
+ down_thread="false" up_thread="false"
+ max_bytes="400000"/>
+ <pbcast.GMS print_local_addr="true" join_timeout="3000" use_flush="true" flush_timeout="3000"
+ down_thread="false" up_thread="false"
+ join_retry_timeout="2000" shun="false"
+ view_bundling="true"/>
+ <FRAG2 frag_size="60000" down_thread="false" up_thread="false"/>
+ <pbcast.STATE_TRANSFER down_thread="false" up_thread="false" use_flush="true" flush_timeout="3000"/>
+ <pbcast.FLUSH down_thread="false" up_thread="false" timeout="20000" auto_flush_conf="false"/>
+ </config>
+ </attribute>
+
+</mbean>
+ </programlisting>
+
+ <section id="conf.postoffice.attributes">
+ <title>Post office attributes</title>
+ <para>
+ In this section, we outline the attributes of the post office.
+ </para>
+ <section id="conf.postoffice.attributes.datasource">
+ <title>DataSource</title>
+
+ <para>
+ The data source used to persist post office mapping data.
+ </para>
+ </section>
+
+ <section id="conf.postoffice.attributes.sqlproperties">
+ <title>SQLProperties</title>
+
+ <para>
+ Specifies the DDL and DML for a particular database. If this attribute is not overridden, the default Hypersonic configuration will be used.
+ </para>
+ </section>
+
+ <section id="conf.postoffice.attributes.createtables">
+ <title>CreateTablesOnStartup</title>
+
+ <para>
+ When set to <literal>true</literal>, the post office will create tables and indexes on startup. If tables or indexes already exist, a <exceptionname>SQLException</exceptionname> is thrown by the JDBC driver, but this is ignored by the Persistence Manager and the operation continues unhindered. The default value is <literal>true</literal>.
+ </para>
+ </section>
+
+ <section id="conf.postoffice.attributes.detectdups">
+ <title>DetectDuplicates</title>
+
+ <para>
+ When set to <literal>true</literal>, the post office detects duplicate messages that may be sent when delivery is retried on a new node after server failure. The default value of this attribute is <literal>true</literal>.
+ </para>
+ </section>
+
+ <section id="conf.postoffice.attributes.idcachesize">
+ <title>IDCacheSize</title>
+
+ <para>
+ If duplicate detection is enabled, the server remembers the last <literal>n</literal> message IDs sent, to prevent duplicate messages being sent after failover occurs. <varname>IDCacheSize</varname> determines the value of <literal>n</literal>. Its default value is <literal>500</literal>.</para>
+ </section>
+
+ <section id="conf.postoffice.attributes.postofficename">
+ <title>PostOfficeName</title>
+
+ <para>The name of the post office.</para>
+ </section>
+
+ <section id="conf.postoffice.attributes.nodeidview">
+ <title>NodeIDView</title>
+
+ <para>Returns the node IDs of all nodes in a cluster as a set.</para>
+ </section>
+
+ <section id="conf.postoffice.attributes.groupname">
+ <title>GroupName</title>
+
+ <para>
+ Post offices with the same group name will form a cluster together. Match post office group names to form a cluster with particular post offices.
+ </para>
+ </section>
+
+ <section id="conf.postoffice.attributes.clustered">
+ <title>Clustered</title>
+
+ <para>
+ If set to <literal>true</literal>, the post office will join a cluster to form distributed queues and topics. If set to <literal>false</literal>, all cluster-related attributes will be ignored.
+ </para>
+ </section>
+
+ <section id="conf.postoffice.attributes.statetimeout">
+ <title>StateTimeout</title>
+
+ <para>
+ The maximum period of time the post office will wait to receive group state when a node joins a pre-existing cluster. The default value is <literal>5000</literal> milliseconds.
+ </para>
+ </section>
+
+ <section id="conf.postoffice.attributes.casttimeout">
+ <title>CastTimeout</title>
+
+ <para>
+ The maximum time that the post office will wait for a reply casting message synchronously. The default value is <literal>5000</literal>.
+ </para>
+ </section>
+
+ <section id="conf.postoffice.attributes.failoveronnodeleave">
+ <title>FailoverOnNodeLeave</title>
+
+ <para>
+ If set to <literal>true</literal>, when a server node is shut down cleanly, any connections on that node will failover onto another node. The default value is <literal>false</literal>.
+ </para>
+ </section>
+
+ <section id="conf.postoffice.attributes.maxconcurrentreplications">
+ <title>MaxConcurrentReplications</title>
+
+ <para>
+ The maximum number of concurrent replication requests to make before blocking to allow replies to return. This prevents JGroups overloading. There is rarely a good reason to alter this. The default value is <literal>50</literal>
+ </para>
+ </section>
+
+ <section id="conf.postoffice.attributes.controlchannelconfig">
+ <title>ControlChannelConfig</title>
+
+ <para>
+ JBoss Messaging uses JGroups for all group management. This attribute contains JGroups stack configuration for the control channel, which sends requests to and receives responses from other nodes in the cluster.</para>
+
+ <para>
+ Standard JGroups configuration is used. For more information, see the JGroups release documentation or visit <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="conf.postoffice.attributes.datachannelconfig">
+ <title>DataChannelConfig</title>
+
+ <para>
+ JBoss Messaging uses JGroups for all group management. This attribute contains JGroups stack configuration for the data channel, which sends and receives messages to and from other nodes in the cluster, and replicates session data.
+ </para>
+
+ <para>
+ Standard JGroups configuration is used. For more information, see the JGroups release documentation or visit <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>
+ </section>
+
+ <section id="conf.persistencemanager">
+ <title>Configuring the Persistence Manager</title>
+
+ <para>
+ The Persistence Manager manages all message-related persistence. JBoss Messaging ships with a JDBC Persistence Manager, which handles message data persistence in a relational database accessed via JDBC. The Persistence Manager can be plugged into the Messaging server, which lets you provide additional implementations to persist message data in non-relational stores, file stores, etc.
+ </para>
+ <para>
+ Persistent service configuration details are grouped in <filename><your database type>-persistence-service.xml</filename>. By default, JBoss Messaging ships with the <filename>hsqldb-persistence-service.xml</filename> file, which configures the Messaging server to use the Hypersonic database instance included by default with any JBoss Application Server instance.
+ </para>
+
+ <warning>
+ <para>
+ Hypersonic should not be used in a production environment, since it has limited support for transaction isolation and tends to behave erratically when under high loads.
+ </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 Persistence Manager configurations for MySQL, Oracle, PostgreSQL, Sybase, Microsoft SQL Server, and DB2. The example configuration files (<filename>mysql-persistence-service.xml</filename>, <filename>ndb-persistence-service.xml</filename>, etc.) are available from the <filename>examples/config</filename> directory of the release bundle.
+ </para>
+
+ <para>
+ We encourage users to contribute their own configuration files for thorough testing and certification for use with JBoss Messaging. The JDBC Persistence Manager uses standard SQL as its Data Manipulation Language (DML), so writing a Persistence Manager configuration for another database type is a matter of changing the configuration's Data Definition Language (DDL), which usually differs on a per-database basis.
+ </para>
+
+ <para>
+ JBoss Messaging also ships with a Null Persistence Manager configuration option, which can be used when you do not want persistence.
+ </para>
+
+ <para>
+ The following code is the default Hypersonic persistence configuration file:
+ </para>
+
+ <programlisting>
+ <mbean code="org.jboss.messaging.core.jmx.JDBCPersistenceManagerService"
+ 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>
+
+ <!-- The datasource to use for the persistence manager -->
+
+ <attribute name="DataSource">java:/DefaultDS</attribute>
+
+ <!-- If true will attempt to create tables and indexes on every start-up -->
+
+ <attribute name="CreateTablesOnStartup">true</attribute>
+
+ <!-- If true then will use JDBC batch updates -->
+
+ <attribute name="UsingBatchUpdates">true</attribute>
+
+ <attribute name="SqlProperties"><![CDATA[
+ CREATE_DUAL=CREATE TABLE JBM_DUAL (DUMMY INTEGER, PRIMARY KEY (DUMMY)) ENGINE = INNODB
+ CREATE_MESSAGE_REFERENCE=CREATE TABLE JBM_MSG_REF (CHANNEL_ID BIGINT, MESSAGE_ID BIGINT, TRANSACTION_ID BIGINT, STATE CHAR(1), ORD BIGINT, PAGE_ORD BIGINT, DELIVERY_COUNT INTEGER, SCHED_DELIVERY BIGINT, PRIMARY KEY(CHANNEL_ID, MESSAGE_ID)) ENGINE = INNODB
+ CREATE_IDX_MESSAGE_REF_TX=CREATE INDEX JBM_MSG_REF_TX ON JBM_MSG_REF (TRANSACTION_ID)
+ CREATE_IDX_MESSAGE_REF_ORD=CREATE INDEX JBM_MSG_REF_ORD ON JBM_MSG_REF (ORD)
+ CREATE_IDX_MESSAGE_REF_PAGE_ORD=CREATE INDEX JBM_MSG_REF_PAGE_ORD ON JBM_MSG_REF (PAGE_ORD)
+ CREATE_IDX_MESSAGE_REF_MESSAGE_ID=CREATE INDEX JBM_MSG_REF_MESSAGE_ID ON JBM_MSG_REF (MESSAGE_ID)
+ CREATE_IDX_MESSAGE_REF_SCHED_DELIVERY=CREATE INDEX JBM_MSG_REF_SCHED_DELIVERY ON JBM_MSG_REF (SCHED_DELIVERY)
+ CREATE_MESSAGE=CREATE TABLE JBM_MSG (MESSAGE_ID BIGINT, RELIABLE CHAR(1), EXPIRATION BIGINT, TIMESTAMP BIGINT, PRIORITY TINYINT, TYPE TINYINT, HEADERS MEDIUMBLOB, PAYLOAD LONGBLOB, PRIMARY KEY (MESSAGE_ID)) ENGINE = INNODB
+ CREATE_IDX_MESSAGE_TIMESTAMP=CREATE INDEX JBM_MSG_REF_TIMESTAMP ON JBM_MSG (TIMESTAMP)
+ CREATE_TRANSACTION=CREATE TABLE JBM_TX (NODE_ID INTEGER, TRANSACTION_ID BIGINT, BRANCH_QUAL VARBINARY(254), FORMAT_ID INTEGER, GLOBAL_TXID VARBINARY(254), PRIMARY KEY (TRANSACTION_ID)) ENGINE = INNODB
+ CREATE_COUNTER=CREATE TABLE JBM_COUNTER (NAME VARCHAR(255), NEXT_ID BIGINT, PRIMARY KEY(NAME)) ENGINE = INNODB
+ INSERT_DUAL=INSERT INTO JBM_DUAL VALUES (1)
+ CHECK_DUAL=SELECT 1 FROM JBM_DUAL
+ INSERT_MESSAGE_REF=INSERT INTO JBM_MSG_REF (CHANNEL_ID, MESSAGE_ID, TRANSACTION_ID, STATE, ORD, PAGE_ORD, DELIVERY_COUNT, SCHED_DELIVERY) VALUES (?, ?, ?, ?, ?, ?, ?, ?)
+ DELETE_MESSAGE_REF=DELETE FROM JBM_MSG_REF WHERE MESSAGE_ID=? AND CHANNEL_ID=? AND STATE='C'
+ UPDATE_MESSAGE_REF=UPDATE JBM_MSG_REF SET TRANSACTION_ID=?, STATE='-' WHERE MESSAGE_ID=? AND CHANNEL_ID=? AND STATE='C'
+ UPDATE_PAGE_ORDER=UPDATE JBM_MSG_REF SET PAGE_ORD = ? WHERE MESSAGE_ID=? AND CHANNEL_ID=?
+ COMMIT_MESSAGE_REF1=UPDATE JBM_MSG_REF SET STATE='C', TRANSACTION_ID = NULL WHERE TRANSACTION_ID=? AND STATE='+'
+ COMMIT_MESSAGE_REF2=DELETE FROM JBM_MSG_REF WHERE TRANSACTION_ID=? AND STATE='-'
+ ROLLBACK_MESSAGE_REF1=DELETE FROM JBM_MSG_REF WHERE TRANSACTION_ID=? AND STATE='+'
+ ROLLBACK_MESSAGE_REF2=UPDATE JBM_MSG_REF SET STATE='C', TRANSACTION_ID = NULL WHERE TRANSACTION_ID=? AND STATE='-'
+ LOAD_PAGED_REFS=SELECT MESSAGE_ID, DELIVERY_COUNT, PAGE_ORD, SCHED_DELIVERY FROM JBM_MSG_REF WHERE CHANNEL_ID = ? AND PAGE_ORD BETWEEN ? AND ? ORDER BY PAGE_ORD
+ LOAD_UNPAGED_REFS=SELECT MESSAGE_ID, DELIVERY_COUNT, SCHED_DELIVERY FROM JBM_MSG_REF WHERE STATE = 'C' AND CHANNEL_ID = ? AND PAGE_ORD IS NULL ORDER BY ORD
+ LOAD_REFS=SELECT MESSAGE_ID, DELIVERY_COUNT, SCHED_DELIVERY FROM JBM_MSG_REF WHERE STATE = 'C' AND CHANNEL_ID = ? ORDER BY ORD
+ UPDATE_REFS_NOT_PAGED=UPDATE JBM_MSG_REF SET PAGE_ORD = NULL WHERE PAGE_ORD BETWEEN ? AND ? AND CHANNEL_ID=?
+ SELECT_MIN_MAX_PAGE_ORD=SELECT MIN(PAGE_ORD), MAX(PAGE_ORD) FROM JBM_MSG_REF WHERE CHANNEL_ID = ?
+ SELECT_EXISTS_REF_MESSAGE_ID=SELECT MESSAGE_ID FROM JBM_MSG_REF WHERE MESSAGE_ID = ?
+ UPDATE_DELIVERY_COUNT=UPDATE JBM_MSG_REF SET DELIVERY_COUNT = ? WHERE CHANNEL_ID = ? AND MESSAGE_ID = ?
+ UPDATE_CHANNEL_ID=UPDATE JBM_MSG_REF SET CHANNEL_ID = ? WHERE CHANNEL_ID = ?
+ LOAD_MESSAGES=SELECT MESSAGE_ID, RELIABLE, EXPIRATION, TIMESTAMP, PRIORITY, HEADERS, PAYLOAD, TYPE FROM JBM_MSG
+ INSERT_MESSAGE=INSERT INTO JBM_MSG (MESSAGE_ID, RELIABLE, EXPIRATION, TIMESTAMP, PRIORITY, TYPE, HEADERS, PAYLOAD) VALUES (?, ?, ?, ?, ?, ?, ?, ?)
+ INSERT_MESSAGE_CONDITIONAL=INSERT INTO JBM_MSG (MESSAGE_ID, RELIABLE, EXPIRATION, TIMESTAMP, PRIORITY, TYPE, INST_TIME) SELECT ?, ?, ?, ?, ?, ?, ? FROM JBM_DUAL WHERE NOT EXISTS (SELECT MESSAGE_ID FROM JBM_MSG WHERE MESSAGE_ID = ?)
+ UPDATE_MESSAGE_4CONDITIONAL=UPDATE JBM_MSG SET HEADERS=?, PAYLOAD=? WHERE MESSAGE_ID=?
+ INSERT_MESSAGE_CONDITIONAL_FULL=INSERT INTO JBM_MSG (MESSAGE_ID, RELIABLE, EXPIRATION, TIMESTAMP, PRIORITY, TYPE, HEADERS, PAYLOAD) SELECT ?, ?, ?, ?, ?, ?, ?, ? FROM JBM_DUAL WHERE NOT EXISTS (SELECT MESSAGE_ID FROM JBM_MSG WHERE MESSAGE_ID = ?)
+ MESSAGE_ID_COLUMN=MESSAGE_ID
+ DELETE_MESSAGE=DELETE FROM JBM_MSG WHERE MESSAGE_ID = ? AND NOT EXISTS (SELECT * FROM JBM_MSG_REF WHERE JBM_MSG_REF.MESSAGE_ID = ?)
+ INSERT_TRANSACTION=INSERT INTO JBM_TX (NODE_ID, TRANSACTION_ID, BRANCH_QUAL, FORMAT_ID, GLOBAL_TXID) VALUES(?, ?, ?, ?, ?)
+ DELETE_TRANSACTION=DELETE FROM JBM_TX WHERE NODE_ID = ? AND TRANSACTION_ID = ?
+ SELECT_PREPARED_TRANSACTIONS=SELECT TRANSACTION_ID, BRANCH_QUAL, FORMAT_ID, GLOBAL_TXID FROM JBM_TX WHERE NODE_ID = ?
+ SELECT_MESSAGE_ID_FOR_REF=SELECT MESSAGE_ID, CHANNEL_ID FROM JBM_MSG_REF WHERE TRANSACTION_ID = ? AND STATE = '+' ORDER BY ORD
+ SELECT_MESSAGE_ID_FOR_ACK=SELECT MESSAGE_ID, CHANNEL_ID FROM JBM_MSG_REF WHERE TRANSACTION_ID = ? AND STATE = '-' ORDER BY ORD
+ UPDATE_COUNTER=UPDATE JBM_COUNTER SET NEXT_ID = ? WHERE NAME=?
+ SELECT_COUNTER=SELECT NEXT_ID FROM JBM_COUNTER WHERE NAME=? FOR UPDATE
+ INSERT_COUNTER=INSERT INTO JBM_COUNTER (NAME, NEXT_ID) VALUES (?, ?)
+ SELECT_ALL_CHANNELS=SELECT DISTINCT(CHANNEL_ID) FROM JBM_MSG_REF
+ UPDATE_TX=UPDATE JBM_TX SET NODE_ID=? WHERE NODE_ID=?
+ ]]></attribute>
+
+ <!-- The maximum number of parameters to include in a prepared statement -->
+
+ <attribute name="MaxParams">500</attribute>
+
+ <attribute name="UseNDBFailoverStrategy">true</attribute>
+
+ </mbean>
+
+ </programlisting>
+
+ <important>
+ <para>
+ When a database is created in Sybase, the maximum size of text and image datatypes is set to the default page size of <literal>2 kilobytes</literal>. Any message that exceeds this limit is truncated without any information or warning. To avoid this, edit the database parameters to set <varname>@@TEXTSIZE</varname> to a greater value.
+ </para>
+ <para>
+ Truncation may also occur in the Microsoft SQL Server if <varname>@@TEXTSIZE</varname> value is set to a lesser value than the default value. For further information, see <ulink url="http://jira.jboss.com/jira/browse/SOA-554" />.
+ </para>
+ </important>
+ <important>
+ <para>
+ Microsoft SQL Server does not automatically un-allocate the hard drive space occupied by data in a database when that data is deleted. This means that, when the space is used as a data store for a service that temporarily stores many records (such as a messaging service), the disk space will quickly become much greater than the amount of data actually being stored.
+ </para>
+ <para>
+ Database administrators should implement database maintenance plans to ensure that the unused space is reclaimed. Refer to your Microsoft SQL Server documentation for the DBCC commands <command>ShrinkDatabase</command> and <command>UpdateUsage</command> for guidance reclaiming the unused space. For further information about this issue, see <ulink url="https://jira.jboss.org/jira/browse/SOA-629"/>
+ </para>
+ </important>
+
+ <section id="conf.persistencemanager.attributes">
+ <title>We now discuss the MBean attributes of the PersistenceManager
+ MBean</title>
+
+ <section id="conf.persistencemanager.attributes.createtables">
+ <title>CreateTablesOnStartup</title>
+
+ <para>
+ When <literal>true</literal>, the persistence manager will attempt to create tables (and indexes) on startup. If tables or indexes already exist, a <exceptionname>SQLException</exceptionname> will be thrown by the JDBC driver and ignored by the persistence manager, allowing it to continue unhindered.
+ </para>
+
+ <para>
+ By default, this parameter is set to <literal>true</literal>.
+ </para>
+ </section>
+
+ <section id="conf.persistencemanager.attributes.batchupdates">
+ <title>UsingBatchUpdates</title>
+
+ <para>
+ If your database supports JDBC batch updates, setting this to <literal>true</literal> will group multiple database updates in batches to improve performance. The default value is <literal>false</literal>.
+ </para>
+ </section>
+
+ <section id="conf.persistencemanager.attributes.binarystream">
+ <title>UsingBinaryStream</title>
+ <para>
+ When <literal>true</literal>, messages will be stored and read with a JDBC binary stream instead of via <literal>getBytes()</literal> and <literal>setBytes()</literal>, which, in some databases, can only get or set a certain number of bytes. The default value is <literal>true</literal>.
+ </para>
+ </section>
+
+ <section id="conf.persistencemanager.attributes.trailingbyte">
+ <title>UsingTrailingByte</title>
+ <para>
+ Some versions of Sybase will truncate a BLOB with trailing zeros. When <varname>UseTrailingByte</varname> is set to <literal>true</literal>, a trailing non-zero byte will be added to each BLOB before persistence, and removed from the BLOB following persistence, preventing truncation by the database. This is only known to be necessary for Sybase databases. By default, the value is set to <literal>false</literal>.
+ </para>
+ </section>
+
+ <section id="conf.persistencemanager.attributes.supportsblobonselect">
+ <title>SupportsBlobOnSelect</title>
+ <para>
+ Some databases, specifically Oracle, do not allow BLOB insertion via an <code>INSERT INTO ... SELECT FROM</code> statement, and require two-stage conditional message insertion. When <varname>SupportsBlobOnSelect</varname> is set to <literal>false</literal>, two-stage insertion will be used. The default value is <literal>true</literal>.
+ </para>
+ </section>
+
+ <section id="conf.persistencemanager.attributes.sqlproperties">
+ <title>SQLProperties</title>
+ <para>
+ Specifies the DDL and DML for a particular database. If a particular DDL or DML statement is not overridden, the default Hypersonic configuration will be used for that statement.
+ </para>
+ </section>
+
+ <section id="conf.persistencemanager.attributes.maxparams">
+ <title>MaxParams</title>
+ <para>
+ While loading messages, the persistence manager generates prepared statements with numerous parameters. This attribute defines the maximum number of parameters allowed per prepared statement. The default value is <literal>100</literal>.
+ </para>
+ </section>
+
+ <section id="conf.persistencemanager.attributes.usendbfailoverstrategy">
+ <title>UseNDBFailoverStrategy</title>
+ <para>
+ When some databases, such as MySQL, run in clustered environments, they can fail during database transaction commits. This can happen when the database node dies during the commit, so that the final transaction state is unknown. If <varname>UseNDBFailoverStrategy</varname> is set to <literal>true</literal>, the SQL statement will be re-executed in the event that the commit fails. If a further error occurs, the persistence manager assumes the error is due to the previous transaction having committed successfully, and ignores the error. By default, this attribute is set to <literal>false</literal>.
+ </para>
+ </section>
+ </section>
+
+ <!-- end conf.persistencemanager.attributes -->
+ </section>
+
+ <!-- end conf.persistencemanager -->
+
+ <section id="conf.jmsusermanager">
+ <title>Configuring the JMS user manager</title>
+
+ <para>
+ The JMS User Manager maps preconfigured client IDs to users. It also manages user and role tables, depending on the configured login module.
+ </para>
+
+ <para>
+ The following is an example <literal>JMSUserManager</literal> configuration:
+ </para>
+
+ <programlisting>
+ <mbean code="org.jboss.jms.server.plugin.JDBCJMSUserManagerService"
+ name="jboss.messaging:service=JMSUserManager"
+ xmbean-dd="xmdesc/JMSUserManager-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="CreateTablesOnStartup">true</attribute>
+ <attribute name="SqlProperties"><![CDATA[
+ CREATE_USER_TABLE=CREATE TABLE JBM_USER (USER_ID VARCHAR(32) NOT NULL,
+ PASSWD VARCHAR(32) NOT NULL, CLIENTID VARCHAR(128),
+ PRIMARY KEY(USER_ID)) ENGINE = INNODB
+ CREATE_ROLE_TABLE=CREATE TABLE JBM_ROLE (ROLE_ID VARCHAR(32) NOT NULL,
+ USER_ID VARCHAR(32) NOT NULL, PRIMARY KEY(USER_ID, ROLE_ID))
+ ENGINE = INNODB
+ SELECT_PRECONF_CLIENTID=SELECT CLIENTID FROM JBM_USER WHERE USER_ID=?
+ POPULATE.TABLES.1=INSERT INTO JBM_USER (USER_ID,PASSWD,CLIENTID)
+ VALUES ('dilbert','dogbert','dilbert-id')
+ ]]></attribute>
+ </mbean>
+ </programlisting>
+
+ <section id="conf.jmsusermanager.attributes">
+ <title>JMSUserManager Managed Bean Attributes</title>
+
+ <section id="conf.jmsusermanager.attributes.createtables">
+ <title>CreateTablesOnStartup</title>
+
+ <para>
+ When set to <literal>true</literal>, the JMS User Manager attempts to create tables (and indexes) upon startup. If the tables or indexes already exist, a <exceptionname>SQLException</exceptionname> is thrown and ignored, allowing the operation to continue. The default value is <literal>true</literal>.
+ </para>
+ </section>
+
+ <section id="conf.jmsusermanager.attributes.batchupdates">
+ <title>UsingBatchUpdates</title>
+
+ <para>
+ If your database supports JDBC batch updates, set this to <literal>true</literal> to have the persistence manager group database updates into batches to improve performance. The default value is <literal>false</literal>.
+ </para>
+ </section>
+
+ <section id="conf.jmsusermanager.attributes.sqlproperties">
+ <title>SQLProperties</title>
+
+ <para>
+ Specifies the DDL and DML for the database. If this is not overridden, the default Hypersonic configuration will be used. You can also specify default user and role data. Specify any data to be inserted with property names prefixed with <literal>POPULATE.TABLES</literal>, as in the previous example.
+ </para>
+ </section>
+ </section>
+
+ <!-- end conf.jmsusermanager.attributes -->
+ </section>
+
+ <!-- end.conf.jmsusermanager -->
+
+ <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 preconfigured destinations that are deployed as the server starts up. The configuration information for these destinations can be found in the following section of <filename>destinations-service.xml</filename>:
+ </para>
+
+ <programlisting>
+ <!--
+ The Default Dead Letter Queue. This destination is a dependency of an EJB MDB container.
+ -->
+
+ <mbean code="org.jboss.jms.server.destination.QueueService"
+ name="jboss.messaging.destination:service=Queue,name=DLQ"
+ xmbean-dd="xmdesc/Queue-xmbean.xml">
+ <depends optional-attribute-name="ServerPeer">
+ jboss.messaging:service=ServerPeer
+ </depends>
+ <depends>jboss.messaging:service=PostOffice</depends>
+ </mbean>
+
+
+ <mbean code="org.jboss.jms.server.destination.TopicService"
+ name="jboss.messaging.destination:service=Topic,name=testTopic"
+ xmbean-dd="xmdesc/Topic-xmbean.xml">
+ <depends optional-attribute-name="ServerPeer">
+ jboss.messaging:service=ServerPeer
+ </depends>
+ <depends>jboss.messaging:service=PostOffice</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.TopicService"
+ name="jboss.messaging.destination:service=Topic,name=securedTopic"
+ xmbean-dd="xmdesc/Topic-xmbean.xml">
+ <depends optional-attribute-name="ServerPeer">
+ jboss.messaging:service=ServerPeer
+ </depends>
+ <depends>jboss.messaging:service=PostOffice</depends>
+ <attribute name="SecurityConfig">
+ <security>
+ <role name="publisher" read="true" write="true" create="false"/>
+ </security>
+ </attribute>
+ </mbean>
+
+
+ <mbean code="org.jboss.jms.server.destination.QueueService"
+ name="jboss.messaging.destination:service=Queue,name=testQueue"
+ xmbean-dd="xmdesc/Queue-xmbean.xml">
+ <depends optional-attribute-name="ServerPeer">
+ jboss.messaging:service=ServerPeer
+ </depends>
+ <depends>jboss.messaging:service=PostOffice</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>
+
+ <mbean code="org.jboss.jms.server.destination.QueueService"
+ name="jboss.messaging.destination:service=Queue,name=A"
+ xmbean-dd="xmdesc/Queue-xmbean.xml">
+ <depends optional-attribute-name="ServerPeer">
+ jboss.messaging:service=ServerPeer
+ </depends>
+ <depends>jboss.messaging:service=PostOffice</depends>
+ </mbean>
+
+
+ <!-- It's possible for indiviual queues and topics to use a specific queue for
+ an expiry or DLQ -->
+
+ <mbean code="org.jboss.jms.server.destination.QueueService"
+ name="jboss.messaging.destination:service=Queue,name=PrivateDLQ"
+ xmbean-dd="xmdesc/Queue-xmbean.xml">
+ <depends optional-attribute-name="ServerPeer">
+ jboss.messaging:service=ServerPeer
+ </depends>
+ <depends>jboss.messaging:service=PostOffice</depends>
+ </mbean>
+
+ <mbean code="org.jboss.jms.server.destination.QueueService"
+ name="jboss.messaging.destination:service=Queue,name=PrivateExpiryQueue"
+ xmbean-dd="xmdesc/Queue-xmbean.xml">
+ <depends optional-attribute-name="ServerPeer">
+ jboss.messaging:service=ServerPeer
+ </depends>
+ <depends>jboss.messaging:service=PostOffice</depends>
+ </mbean>
+
+ <mbean code="org.jboss.jms.server.destination.QueueService"
+ name="jboss.messaging.destination:service=Queue,name=QueueWithOwnDLQAndExpiryQueue"
+ xmbean-dd="xmdesc/Queue-xmbean.xml">
+ <depends optional-attribute-name="ServerPeer">
+ jboss.messaging:service=ServerPeer
+ </depends>
+ <depends>jboss.messaging:service=PostOffice</depends>
+ <attribute name="DLQ">
+ jboss.messaging.destination:service=Queue,name=PrivateDLQ
+ </attribute>
+ <attribute name="ExpiryQueue">
+ jboss.messaging.destination:service=Queue,name=PrivateExpiryQueue
+ </attribute>
+ </mbean>
+
+ <mbean code="org.jboss.jms.server.destination.TopicService"
+ name="jboss.messaging.destination:service=Topic,name=TopicWithOwnDLQAndExpiryQueue"
+ xmbean-dd="xmdesc/Topic-xmbean.xml">
+ <depends optional-attribute-name="ServerPeer">
+ jboss.messaging:service=ServerPeer
+ </depends>
+ <depends>jboss.messaging:service=PostOffice</depends>
+ <attribute name="DLQ">
+ jboss.messaging.destination:service=Queue,name=PrivateDLQ
+ </attribute>
+ <attribute name="ExpiryQueue">
+ jboss.messaging.destination:service=Queue,name=PrivateExpiryQueue
+ </attribute>
+ </mbean>
+
+
+ <mbean code="org.jboss.jms.server.destination.TopicService"
+ name="jboss.messaging.destination:service=Topic,name=TopicWithOwnRedeliveryDelay"
+ xmbean-dd="xmdesc/Topic-xmbean.xml">
+ <depends optional-attribute-name="ServerPeer">
+ jboss.messaging:service=ServerPeer
+ </depends>
+ <depends>jboss.messaging:service=PostOffice</depends>
+ <attribute name="RedeliveryDelay">5000</attribute>
+ </mbean>
+
+
+ <mbean code="org.jboss.jms.server.destination.TopicService"
+ name="jboss.messaging.destination:service=Topic,name=testDistributedTopic"
+ xmbean-dd="xmdesc/Topic-xmbean.xml">
+ <depends optional-attribute-name="ServerPeer">
+ jboss.messaging:service=ServerPeer
+ </depends>
+ <depends>jboss.messaging:service=PostOffice</depends>
+ <attribute name="Clustered">true</attribute>
+ </mbean>
+....
+ </programlisting>
+ </section>
+
+ <!-- end conf.preconf.destinations -->
+
+ <section id="conf.destination.queue">
+ <title>Configuring Queues</title>
+
+ <section id="conf.destination.queue.attributes">
+ <title>Queue MBean Attributes</title>
+
+ <section id="conf.destination.queue.attributes.name">
+ <title>Name</title>
+
+ <para>Defines the queue name.</para>
+ </section>
+
+ <section id="conf.destination.queue.attributes.jndiName">
+ <title>JNDIName</title>
+
+ <para>Defines the JNDI name that binds the queue.</para>
+ </section>
+
+ <section id="conf.destination.queue.attributes.dlq">
+ <title>DLQ</title>
+
+ <para>Defines the DLQ (Dead Letter Queue) for this queue and overrides any value set in the Server Peer configuration file.</para>
+ </section>
+
+ <section id="conf.destination.queue.attributes.expiryqueue">
+ <title>ExpiryQueue</title>
+
+ <para>Defines the expiry queue and overrides any value set in the Server Peer configuration file.</para>
+ </section>
+
+ <section id="conf.destination.queue.attributes.redeliverydelay">
+ <title>RedeliveryDelay</title>
+
+ <para>Defines the redelivery delay to be applied to this queue and overrides any value set in the Server Peer configuration file.</para>
+ </section>
+
+ <section id="conf.destination.queue.attributes.maxdeliveryattempts">
+ <title>MaxDeliveryAttempts</title>
+
+ <para>
+ Defines the maximum number of times message delivery is attempted before the message is sent to the DLQ, if configured. The default value, <literal>-1</literal>, means that the value from the Server Peer configuration file is used. Any other setting will override the value set in the Server Peer configuration file.
+ </para>
+ </section>
+
+ <section id="conf.destination.queue.attributes.security">
+ <title>Destination Security Configuration</title>
+
+ <para>
+ <literal>SecurityConfig</literal> determines which roles can read, write and create upon the destination. It uses the same syntax and semantics as JBossMQ destination security configuration.
+ </para>
+ <para>
+ The <literal>SecurityConfig</literal> element should contain one <literal><security></literal> element, which can contain multiple <literal><role></literal> elements. A <literal><role></literal> element defines the access type for that particular role.
+ </para>
+ <para>
+ If the <varname>read</varname> attribute is set to <literal>true</literal>, then that role will be able to <emphasis>read</emphasis> (create consumers, receive messages, and browse) this destination.
+ </para>
+ <para>
+ If the <varname>write</varname> attribute is set to <literal>true</literal>, then that role will be able to <emphasis>write</emphasis> (create producers or send messages) to this destination.
+ </para>
+ <para>
+ If the <varname>create</varname> attribute is set to <literal>true</literal>, then that role will be able to create durable subscriptions on this destination.
+ </para>
+ <para>
+ Configuring security for a destination is optional. If a <literal>SecurityConfig</literal> element is not specified, then the default security configuration from the Server Peer will be used instead.
+ </para>
+ </section>
+
+ <section id="conf.destination.queue.attributes.paging">
+ <title>Destination paging parameters</title>
+
+ <para>
+ <emphasis>Pageable Channels</emphasis> is a new feature available in JBoss Messaging.
+ </para>
+ <para>
+ Previously, for an application to support a queue or subscription, the queue needed to be stored entirely in memory. This was not always possible for very large queues or subscriptions.
+ </para>
+ <para>
+ <emphasis>Pageable Channels</emphasis> is a new JBoss Messaging feature that lets you specify a maximum number of messages to be stored in memory at one time, on a queue-by-queue or topic-by-topic basis. JBoss Messaging then pages messages to and from storage transparently in blocks. This allows queues and subscriptions to grow to very large sizes without any degradation in performance as channel size increases. It has been tested with queues in excess of ten million 2 kilobyte messages on very basic hardware, and has the potential to scale to much greater message numbers.
+ </para>
+ <para>
+ The individual parameters associated with pageable channels are as follows:
+ </para>
+
+ <para>
+ <literal>FullSize</literal> defines the maximum number of messages held by the queue or topic subscription in memory at any one time. The actual queue can hold more messages, but these are paged to and from storage as messages are added or consumed. If no value is specified, the default is <literal>75000</literal>.
+ </para>
+ <para>
+ <literal>PageSize</literal> defines the maximum number of messages that are pre-loaded per operation when loading messages from the queue or subscription. If no value is specified, the default is <literal>2000</literal>.
+ </para>
+ <para>
+ <literal>DownCacheSize</literal> — when messages are paged to storage from the queue, they enter a <emphasis>Down Cache</emphasis> before being written to storage. This enables the write to occur as a single operation, which aids performance. This attribute determines the maximum number of messages that the Down Cache will hold before the messages are flushed to storage. If no value is specified, the default is <literal>2000</literal>.
+ </para>
+ <para>
+ Paging parameters for temporary queues must be specified on the appropriate connection factory. See the section on Connection Factory Configuration for details.
+ </para>
+ </section>
+
+ <section id="conf.destination.queue.attributes.createdprogrammatically">
+ <title>CreatedProgrammatically</title>
+
+ <para>Returns <literal>true</literal> if the queue was created
+ programmatically.</para>
+ </section>
+
+ <section id="conf.destination.queue.attributes.messagecount">
+ <title>MessageCount</title>
+
+ <para>Returns the total number of messages in the queue. That is, the number of messages being scheduled plus the number being delivered, plus the number not being dedlivered.</para>
+ </section>
+
+ <section id="conf.destination.queue.attributes.scheduledmessagecount">
+ <title>ScheduledMessageCount</title>
+
+ <para>Returns the number of <emphasis>scheduled messages</emphasis> in the queue. This is the number of messages scheduled to be delivered at a later date.</para>
+
+ <para>
+ Scheduled delivery lets you specify the earliest time at which a particular message will be delivered. For example, you can send a message now, and specify that it will not be delivered for two hours. To do so, you would set the following in the message header:
+ </para>
+
+ <programlisting>
+
+long now = System.currentTimeMillis();
+
+Message msg = sess.createMessage();
+
+msg.setLongProperty(JBossMessage.JMS_JBOSS_SCHEDULED_DELIVERY_PROP_NAME,
+ now + 1000 * 60 * 60 * 2);
+
+prod.send(msg);
+
+ </programlisting>
+ </section>
+
+ <section id="conf.destination.queue.attributes.maxsize">
+ <title>MaxSize</title>
+
+ <para>
+ Specifies the maximum number of messages that can be held in a queue. Any excess messages will be dropped. The default value is <literal>-1</literal>, which is unbounded.
+ </para>
+ </section>
+
+ <section id="conf.destination.queue.attributes.clustered">
+ <title>Clustered</title>
+
+ <para>This attribute must be set to <literal>true</literal> if the destination is clustered.
+ </para>
+ </section>
+
+ <section id="conf.destination.queue.attributes.messagecounter">
+ <title>MessageCounter</title>
+
+ <para>Each queue maintains a message counter.</para>
+ </section>
+
+ <section id="conf.destination.queue.attributes.messagecounterstats">
+ <title>MessageCounterStatistics</title>
+
+ <para>The statistics for the message counter.</para>
+ </section>
+
+ <section id="conf.destination.queue.attributes.messagecounterhistorydaylimit">
+ <title>MessageCounterHistoryDayLimit</title>
+
+ <para>The maximum number of days for which to hold message counter history. Overrides any value set in the Server Peer configuration file.</para>
+ </section>
+
+ <section id="conf.destination.queue.attributes.consumercount">
+ <title>ConsumerCount</title>
+
+ <para>The number of consumers currently consuming from the queue.</para>
+ </section>
+ </section>
+
+ <section id="conf.destination.queue.operations">
+ <title>Queue Managed Bean Operations</title>
+
+ <section id="conf.destination.queue.operations.removeallmessages">
+ <title>RemoveAllMessages</title>
+
+ <para>
+ Removes (and deletes) all messages from the queue. <emphasis>Use with caution, as this will permanently delete all messages from the queue.</emphasis>
+ </para>
+ </section>
+
+ <section id="conf.destination.queue.operations.listallmessages">
+ <title>ListAllMessages</title>
+
+ <para>
+ Lists all messages currently in the queue. Using a JMS selector as an argument in this operation lets you retrieve a subset of the messages in the queue that match the given criteria.
+ </para>
+ </section>
+
+ <section id="conf.destination.queue.operations.listdurablemessages">
+ <title>ListDurableMessages</title>
+
+ <para>
+ Lists all <emphasis>durable</emphasis> messages in the queue. Using a JMS selector as an argument in this operation lets you retrieve a subset of messages in the queue that match the given criteria.
+ </para>
+ </section>
+
+ <section id="conf.destination.queue.operations.listnondurablemessages">
+ <title>ListNonDurableMessages</title>
+
+ <para>
+ Lists all <emphasis>non-durable</emphasis> messages in a queue. Using a JMS selector as an argument in this operation lets you retrieve a subset of messages in the queue that match the given criteria.
+ </para>
+ </section>
+
+ <section id="conf.destination.queue.operations.resetmessagecounter">
+ <title>ResetMessageCounter</title>
+
+ <para>Resets the message counter to zero.</para>
+ </section>
+
+ <section id="conf.destination.queue.operations.resetmessagecounterhistory">
+ <title>ResetMessageCounterHistory</title>
+
+ <para>Resets the message counter history.</para>
+ </section>
+
+ <section id="conf.destination.queue.operations.listmessagecounterashtml">
+ <title>ListMessageCounterAsHTML</title>
+
+ <para>Lists the message counter in an easily-displayed HTML format.</para>
+ </section>
+
+ <section id="conf.destination.queue.operations.listmessagecounterhistoryashtml">
+ <title>ListMessageCounterHistoryAsHTML</title>
+
+ <para>Lists the message counter history in an easily-displayed HTML format.</para>
+ </section>
+ </section>
+ </section>
+
+ <section id="conf.destination.topics">
+ <title>Configuring Topics</title>
+
+ <section id="conf.destination.topic.attributes">
+ <title>Topic Managed Bean Attributes</title>
+
+ <section id="conf.destination.topic.attributes.name">
+ <title>Name</title>
+
+ <para>Defines the name of the topic.</para>
+ </section>
+
+ <section id="conf.destination.topic.attributes.jndiName">
+ <title>JNDIName</title>
+
+ <para>Defines the JNDI location where the topic is bound.</para>
+ </section>
+
+ <section id="conf.destination.topic.attributes.dlq">
+ <title>DLQ</title>
+
+ <para>Defines the Dead Letter Queue (DLQ) used for this topic and overrides any value set in the Server Peer configuration file.</para>
+ </section>
+
+ <section id="conf.destination.topic.attributes.expiryqueue">
+ <title>ExpiryQueue</title>
+
+ <para>Defines the expiry queue used for this topic and overrides any value set in the Server Peer configuration file.</para>
+ </section>
+
+ <section id="conf.destination.topic.attributes.redeliverydelay">
+ <title>RedeliveryDelay</title>
+
+ <para>Defines the delay period between redelivery attempts for this topic and overrides any value set in the Server Peer configuration file.</para>
+ </section>
+
+ <section id="conf.destination.topic.attributes.maxdeliveryattempts">
+ <title>MaxDeliveryAttempts</title>
+
+ <para>
+ Defines the maximum number of times message delivery will be attempted before the message is sent to the DLQ, if configured. The default value is <literal>-1</literal>, which specifies that the value from the Server Peer configuration file be used. Any other setting overrides the Server Peer value.
+ </para>
+ </section>
+
+ <section id="conf.destination.topic.attributes.security">
+ <title>Destination Security Configuration</title>
+
+ <para>
+ <literal>SecurityConfig</literal> lets you define which roles can read, write and create on the destination. The syntax matches that of the security configuration in JBossMQ destinations.
+ </para>
+
+ <para>
+ The <literal>SecurityConfig</literal> element should contain one <literal><security></literal> element, which can contain multiple <literal><role></literal> elements. Each <literal><role></literal> element defines the access type for that particular role.
+ </para>
+
+ <para>
+ If the <varname>read</varname> attribute is set to <literal>true</literal>, that role has permission to <emphasis>read</emphasis> (create consumers, receive messages, and browse) this destination.
+ </para>
+
+ <para>
+ If the <varname>write</varname> attribute is set to <literal>true</literal>, that role has permission to <emphasis>write</emphasis> (create producers or send messages) to this destination.</para>
+
+ <para>
+ If the <varname>create</varname> attribute is set to <literal>true</literal>, that role has permission to create durable subscriptions on this destination.
+ </para>
+ <para>
+ Configuring security for destinations is optional. If a <literal>SecurityConfig</literal> element is not specified, the default security configuration from the Server Peer will be used.
+ </para>
+ </section>
+
+ <section id="conf.destination.topic.attributes.paging">
+ <title>Destination paging parameters</title>
+
+ <para>
+ <emphasis>Pageable Channels</emphasis> is a new feature available in JBoss Messaging.
+ </para>
+ <para>
+ Previously, for an application to support a queue or subscription, the queue needed to be stored entirely in memory. This was not always possible for very large queues or subscriptions.
+ </para>
+ <para>
+ <emphasis>Pageable Channels</emphasis> is a new JBoss Messaging feature that lets you specify a maximum number of messages to be stored in memory at one time, on a queue-by-queue or topic-by-topic basis. JBoss Messaging then pages messages to and from storage transparently in blocks. This allows queues and subscriptions to grow to very large sizes without any degradation in performance as channel size increases. It has been tested with queues in excess of ten million 2 kilobyte messages on very basic hardware, and has the potential to scale to much greater message numbers.
+ </para>
+ <para>
+ The individual parameters associated with pageable channels are as follows:
+ </para>
+
+ <para>
+ <literal>FullSize</literal> defines the maximum number of messages held by the queue or topic subscription in memory at any one time. The actual queue can hold more messages, but these are paged to and from storage as messages are added or consumed. If no value is specified, the default is <literal>75000</literal>.
+ </para>
+ <para>
+ <literal>PageSize</literal> defines the maximum number of messages that are pre-loaded per operation when loading messages from the queue or subscription. If no value is specified, the default is <literal>2000</literal>.
+ </para>
+ <para>
+ <literal>DownCacheSize</literal> — when messages are paged to storage from the queue, they enter a <emphasis>Down Cache</emphasis> before being written to storage. This enables the write to occur as a single operation, which aids performance. This attribute determines the maximum number of messages that the Down Cache will hold before the messages are flushed to storage. If no value is specified, the default is <literal>2000</literal>.
+ </para>
+ <para>
+ Paging parameters for temporary queues must be specified on the appropriate connection factory. See the section on Connection Factory Configuration for details.
+ </para>
+ </section>
+
+ <section id="conf.destination.topic.attributes.createdprogrammatically">
+ <title>CreatedProgrammatically</title>
+
+ <para>
+ Returns <literal>true</literal> if the topic was created programmatically.
+ </para>
+ </section>
+
+ <section id="conf.destination.topic.attributes.maxsize">
+ <title>MaxSize</title>
+
+ <para>
+ Specifies the maximum number of messages that can be held in a topic subscription. Any excess messages will be dropped from the topic. The default value is <literal>-1</literal>, which applies no size restriction.
+ </para>
+ </section>
+
+ <section id="conf.destination.topic.attributes.clustered">
+ <title>Clustered</title>
+
+ <para>
+ Set this to <literal>true</literal> if your destination is clustered.
+ </para>
+ </section>
+
+ <section id="conf.destination.topic.attributes.messagecounterhistorydaylimit">
+ <title>MessageCounterHistoryDayLimit</title>
+
+ <para>
+ Defines the maximum number of days to retain message counter history, and overrides any value set in the Server Peer configuration file.</para>
+ </section>
+
+ <section id="conf.destination.topic.attributes.messagecounters">
+ <title>MessageCounters</title>
+
+ <para>
+ Returns a list of message counters for the topic's subscriptions.
+ </para>
+ </section>
+
+ <section id="conf.destination.topic.attributes.allmessagecount">
+ <title>AllMessageCount</title>
+
+ <para>
+ Returns the total number of messages in all supscriptions belonging to the topic.
+ </para>
+ </section>
+
+ <section id="conf.destination.topic.attributes.durablemessagecount">
+ <title>DurableMessageCount</title>
+
+ <para>
+ Returns the total number of <emphasis>durable</emphasis> messages in all subscriptions belonging to this topic.
+ </para>
+ </section>
+
+ <section id="conf.destination.topic.attributes.nondurablemessagecount">
+ <title>NonDurableMessageCount</title>
+
+ <para>
+ Returns the total number of <emphasis>non-durable</emphasis> messages in all subscriptions belonging to this topic.
+ </para>
+ </section>
+
+ <section id="conf.destination.topic.attributes.allsubscriptionscount">
+ <title>AllSubscriptionsCount</title>
+
+ <para>
+ Returns a count of all subscriptions belonging to this topic.
+ </para>
+ </section>
+
+ <section id="conf.destination.topic.attributes.durablesubscriptionscount">
+ <title>DurableSubscriptionsCount</title>
+
+ <para>Returns a count of all durable subscriptions belonging to this topic.</para>
+ </section>
+
+ <section id="conf.destination.topic.attributesnon.durablesubscriptionscount">
+ <title>NonDurableSubscriptionsCount</title>
+
+ <para>
+ Returns a count of all non-durable subscriptions belonging to this topic.
+ </para>
+ </section>
+ </section>
+
+ <section id="conf.destination.topic.operations">
+ <title>Topic Managed Bean Operations</title>
+
+ <section id="conf.destination.topic.operations.removeallmessages">
+ <title>RemoveAllMessages</title>
+
+ <para>
+ Removes and deletes all messages from the subscriptions belonging to this topic. <emphasis>Use with caution, as this permanently deletes all messages from the topic.</emphasis>
+ </para>
+ </section>
+
+ <section id="conf.destination.topic.operations.listallsubscriptions">
+ <title>ListAllSubscriptions</title>
+
+ <para>Lists all subscriptions belonging to this topic.</para>
+ </section>
+
+ <section id="conf.destination.topic.operations.listdurablesubscriptions">
+ <title>ListDurableSubscriptions</title>
+
+ <para>Lists all durable subscriptions belonging to this topic.</para>
+ </section>
+
+ <section id="conf.destination.topic.operations.listnondurablesubscriptions">
+ <title>ListNonDurableSubscriptions</title>
+
+ <para>Lists all non-durable subscriptions belonging to this topic.</para>
+ </section>
+
+ <section id="conf.destination.topic.operations.listallsubscriptionsashtml">
+ <title>ListAllSubscriptionsAsHTML</title>
+
+ <para>
+ Lists all subscriptions belonging to this topic in an easily-displayed HTML format.
+ </para>
+ </section>
+
+ <section id="conf.destination.topic.operations.listdurablesubscriptionsashtml">
+ <title>ListDurableSubscriptionsAsHTML</title>
+
+ <para>
+ Lists all durable subscriptions belonging to this topic in an easily-displayed HTML format.
+ </para>
+ </section>
+
+ <section id="conf.destination.topic.operations.listnondurablesubscriptionsashtml">
+ <title>ListNonDurableSubscriptionsAsHTML</title>
+
+ <para>
+ Lists all non-durable subscriptions belonging to this topic in an easily-displayed HTML format.</para>
+ </section>
+
+ <section id="conf.destination.topic.operations.listallmessages">
+ <title>ListAllMessages</title>
+
+ <para>Lists all messages belonging to a specified subscription. Using a JMS selector as an argument in this operation lets you retrieve a subset of messages in the queue that match the given criteria.</para>
+ </section>
+
+ <section id="conf.destination.topic.operations.listnondurablemessages">
+ <title>ListNonDurableMessages</title>
+
+ <para>
+ Lists all non-durable messages belonging to the specified subscription. Using a JMS selector as an argument in this operation lets you retrieve a subset of messages in the queue that match the given criteria.
+ </para>
+ </section>
+
+ <section id="conf.destination.topic.operations.listdurablemessages">
+ <title>ListDurableMessages</title>
+
+ <para>
+ Lists all durable messages belonging to the specified subscription. Using a JMS selector as an argument in this operation lets you retrieve a subset of messages in the queue that match the given criteria.
+ </para>
+ </section>
+ </section>
+ </section>
+ </section>
+
+ <!-- end of conf destination -->
+
+ <section id="conf.connectionfactory">
+ <title>Configuring Connection Factories</title>
+
+ <para>
+ By default, JBoss Messaging is configured to bind two connection factories in JNDI upon startup.
+ </para>
+
+ <para>
+ The first connection factory is the default non-clustered connection factory, which is bound into the following JNDI contexts: <literal>/ConnectionFactory</literal>, <literal>/XAConnectionFactory</literal>, <literal>java:/ConnectionFactory</literal>, and <literal>java:/XAConnectionFactory</literal>. This connection factory is provided to maintain compatibility with applications originally written against JBossMQ, which does not include automatic failover or load balancing. If you do not require client-side automatic failover or load balancing, then you should use this first connection factory.
+ </para>
+ <para>
+ The second connection factory is the default clustered connection factory, which is bound into the following JNDI contexts: <literal>/ClusteredConnectionFactory</literal>, <literal>/ClusteredXAConnectionFactory</literal>, <literal>java:/ClusteredConnectionFactory</literal>, and <literal>java:/ClusteredXAConnectionFactory</literal>.
+ </para>
+ <para>
+ You may want to configure additional connection factories — for example, if you want to provide a default client ID for a connection factory, or to bind a connection factory to a different JNDI location. To deploy a new connection factory, configure a new <literal>ConnectionFactory</literal> managed bean in <filename>connection-factories-service.xml</filename>.
+ </para>
+ <para>
+ You can also create a new service deployment descriptor, <filename><name>-service.xml</filename>, and deploy it in <filename>$JBOSS_HOME/server/messaging/deploy</filename>.
+ </para>
+
+ <para>
+ Enable support for automatic failover or load balancing by setting the relevant attributes in your connection faactory:
+ </para>
+
+ <programlisting>
+<mbean code="org.jboss.jms.server.connectionfactory.ConnectionFactory"
+ name="jboss.messaging.connectionfactory:service=MyConnectionFactory"
+ xmbean-dd="xmdesc/ConnectionFactory-xmbean.xml">
+ <depends optional-attribute-name="ServerPeer">
+ jboss.messaging:service=ServerPeer
+ </depends>
+ <depends optional-attribute-name="Connector">
+ jboss.messaging:service=Connector,transport=bisocket
+ </depends>
+ <depends>jboss.messaging:service=PostOffice</depends>
+
+ <attribute name="JNDIBindings">
+ <bindings>
+ <binding>/MyConnectionFactory</binding>
+ <binding>/factories/cf</binding>
+ </bindings>
+ </attribute>
+
+ <attribute name="ClientID">myClientID</attribute>
+
+ <attribute name="SupportsFailover">true</attribute>
+
+ <attribute name="SupportsLoadBalancing">false</attribute>
+
+ <attribute name="LoadBalancingFactory">org.acme.MyLoadBalancingFactory</attribute>
+
+ <attribute name="PrefetchSize">1000</attribute>
+
+ <attribute name="SlowConsumers">false</attribute>
+
+ <attribute name="StrictTck">true</attribute>
+
+ <attribute name="SendAcksAsync">false</attribute>
+
+ <attribute name="DefaultTempQueueFullSize">50000</attribute>
+
+ <attribute name="DefaultTempQueuePageSize">1000</attribute>
+
+ <attribute name="DefaultTempQueueDownCacheSize">1000</attribute>
+
+ <attribute name="DupsOKBatchSize">10000</attribute>
+ </mbean>
+ </programlisting>
+
+ <para>
+ The example configuration would create a connection factory with the preconfigured client ID <literal>myClientID</literal>, which would be bound to two locations in the JNDI tree: <literal>/MyConnectionFactory</literal> and <literal>/factories/cf</literal>. This connection factory overrides the default values for <varname>PreFetchSize</varname>, <varname>DefaultTempQueueFullSize</varname>, <varname>DefaultTempQueuePageSize</varname>, <varname>DefaultTempQueueDownCacheSize</varname> and <varname>DupsOKBatchSize</varname>, <varname>SupportsFailover</varname>, <varname>SupportsLoadBalancing</varname> and <varname>LoadBalancingFactory</varname>. 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>
+
+ <section id="conf.connectionfactory.attributes">
+ <title>ConnectionFactory Managed Bean Attributes</title>
+
+ <section id="conf.connectionfactory.attributes.clientid">
+ <title>ClientID</title>
+
+ <para>
+ You can preconfigure a connection factory with a client ID. Any connection created via this connection factory will obtain this client ID.
+ </para>
+ </section>
+
+ <section id="conf.connectionfactory.attributes.jndibindings">
+ <title>JNDIBindings</title>
+
+ <para>Lists available JNDI bindings for this connection factory.</para>
+ </section>
+
+ <section id="conf.connectionfactory.attributes.prefetchsize">
+ <title>PrefetchSize</title>
+
+ <para>
+ Specifies how many messages the window holds at once, for consumer flow control. The window size determines the number of messages a server can send to a consumer without blocking. Each consumer maintains a buffer of messages from which it consumes.
+ </para>
+ <para>
+ Transmission Control Protocol (TCP) implements its own additional flow control. Message consumption can also be blocked if the TCP window size is smaller than the PrefetchSize parameter.
+ </para>
+ </section>
+
+ <section id="conf.connectionfactory.attributes.slowconsumers">
+ <title>SlowConsumers</title>
+
+ <para>
+ If a slow consumer maintains a large buffer, it may prevent faster consumers receiving the buffered messages. Setting <varname>SlowConsumers</varname> to <literal>true</literal> is equivalent to setting <varname>PrefetchSize</varname> to <literal>1</literal>.
+ </para>
+ </section>
+
+ <section id="conf.connectionfactory.attributes.tckstrictbehavior">
+ <title>StrictTck</title>
+
+ <para>When set to <literal>true</literal>, strict JMS behavior (as required by the Technology Compatibility Kit) is enabled.</para>
+ </section>
+
+ <section id="conf.connectionfactory.attributes.sendacksasync">
+ <title>SendAcksAsync</title>
+
+ <para>
+ When set to <literal>true</literal>, acknowledgements are sent asynchronously. This can improve performance, particularly if <literal>auto_acknowledge</literal> mode is active.
+ </para>
+ </section>
+
+ <section id="conf.connectionfactory.attributes.tempqueuepaging">
+ <title>Temporary queue paging parameters</title>
+
+ <para>
+ <varname>DefaultTempQueueFullSize</varname>, <varname>DefaultTempQueuePageSize</varname> and <varname>DefaultTempQueueDownCacheSize</varname> are optional attributes. They determine the default paging parameters used for temporary destinations that are scoped to connections created with this connection factory. See the section on Paging Channels for further information about these values.
+ </para>
+ <para>
+ <varname>DefaultTempQueueFullSize</varname> defaults to <literal>200000</literal>.
+ </para>
+ <para>
+ <varname>DefaultTempQueuePageSize</varname> and <varname>DefaultTempQueueDownCacheSize</varname> default to <literal>2000</literal>.
+ </para>
+ </section>
+
+ <section id="conf.connectionfactory.attributes.dupsokbatchsize">
+ <title>DupsOKBatchSize</title>
+
+ <para>
+ For sessions that use the <literal>DUPS_OK_ACKNOWLEDGE</literal> mode, this setting determines the number of acknowledgements that will be buffered locally before they are sent. The default value is <literal>2000</literal>.
+ </para>
+ </section>
+
+ <section id="conf.connectionfactory.attributes.supportsloadbalancing">
+ <title>SupportsLoadBalancing</title>
+
+ <para>
+ When you use a connection factory with a clustered JBoss Messaging installation, client-side load balancing is determined by the <varname>supportsLoadBalancing</varname> attribute on the connection factory. If load balancing is enabled, any connection created by that connection factory will be load-balanced across the nodes of a cluster. A connection created on a particular node remains on that node.
+ </para>
+ <para>
+ The <varname>LoadBalancingFactory</varname> attribute determines whether connections are load-balanced. The default value is <literal>false</literal>
+ </para>
+ </section>
+
+ <section id="conf.connectionfactory.attributes.supportsfailover">
+ <title>SupportsFailover</title>
+
+ <para>
+ When you use a connection factory with a clustered JBoss Messaging installation, automatic failover on the client side is determined by the <varname>supportsFailover</varname> attribute on the connection factory. If automatic failover is enabled, when a connection problem is detected, JBoss Messaging will automatically and transparently failover to another node in the cluster.
+ </para>
+ <para>
+ If automatic failover is not required, set this attribute to <literal>false</literal>. (This is the default value.) When automatic failover is disabled, the user code is responsible for catching connection exceptions in synchronous JMS operations, and a JMS <literal>ExceptionListener</literal> must be installed to catch exceptions asynchronously. When an exception is caught, the client-side code should lookup a new connection factory via HAJNDI and recreate the connection.
+ </para>
+ </section>
+
+ <section id="conf.connectionfactory.attributes.disableremotingchecks">
+ <title>DisableRemotingChecks</title>
+
+ <para>
+ By default, when deploying a connection factory, JBoss Messaging checks that the corresponding JBoss Remoting Connector has sensible values. JBoss Messaging is very sensitive to these values, and there is rarely any need to change them. To disable this sanity checking, set <varname>DisableRemotingChecks</varname> to <literal>false</literal> (the default value).
+ </para>
+ <warning>
+ <para>
+ There is rarely a good reason to disable checking. Only do so if you are absolutely certain it must be done.
+ </para>
+ </warning>
+ </section>
+
+ <section id="conf.connectionfactory.attributes.loadbalancingfactory">
+ <title>LoadBalancingFactory</title>
+
+ <para>
+ If your connection factory uses client-side load balancing, you can specify how this is implemented by overriding this attribute. The value must correspond to the name of a class that implements the interface <literal>org.jboss.jms.client.plugin.LoadBalancingFactory</literal>.
+ </para>
+ <para>
+ The default value is <literal>org.jboss.jms.client.plugin.RoundRobinLoadBalancingFactory</literal>, which load-balances connections across the cluster in a round-robin fashion.
+ </para>
+ </section>
+
+ <section id="conf.connectionfactory.attributes.connector">
+ <title>Connector</title>
+
+ <para>
+ Specifies the remoting connector used by the connection factory. Different connection factories can use different connectors, so you can deploy one connection factory that uses the HTTP transport to communicate with the server, and another that uses the bisocket transport to communicate.
+ </para>
+ </section>
+ </section>
+
+ <!-- End conf.connectionfactory.attributes -->
+ </section>
+
+ <!-- End conf.connectionfactory -->
+
+ <section id="conf.connector">
+ <title>Configuring the Remoting Connector</title>
+
+ <para>
+ JBoss Messaging uses JBoss Remoting for all communication between the client and the server. (For further information about JBoss Remoting configuration and capabilities, see the JBoss Remoting documentation.)
+ </para>
+ <para>
+ The default configuration includes one remoting connector, which is used by the single default connection factory. Each connection factory can be configured to use a different connector.
+ </para>
+ <para>
+ The default connector is configured to use the remoting bisocket transport, a TCP socket-based transport that listens and accepts connections only on the server side. That is, connections are always initiated from the client side. This connector is ideal for typical firewall scenarios, where only inbound connections are allowed on the server, or where only outbound connections are allowed from the client.
+ </para>
+ <para>
+ The bisocket transport can be configured to use SSL when a higher level of security is required.
+ </para>
+ <para>
+ The other supported transport is the HTTP transport, which uses the Hypertext Transfer Protocol to communicate between client and server. The client periodically polls the server for messages to receive data. This transport is ideal when a firewall between server and client allows only incoming HTTP traffic on the server. Because of its polling behavior and the HTTP, this transport does not perform as well as the bisocket transport. It is not designed to handle high-load situations.
+ </para>
+ <para>
+ No other remoting transports are currently supported by JBoss Messaging.
+ </para>
+
+ <para>
+ Remoting configuration details can be seen in <filename>$JBOSS_HOME/server/$SERVER/deploy/jboss-messaging.sar/remoting-bisocket-service.xml</filename>. The following code is an example of a bisocket remoting configuration:
+ </para>
+ <programlisting>
+<config>
+ <invoker transport="bisocket">
+
+ <!-- There should be no reason to change these parameters - warning!
+ Changing them may stop JBoss Messaging working correctly -->
+ <attribute name="marshaller" isParam="true">org.jboss.jms.wireformat.JMSWireFormat</attribute>
+ <attribute name="unmarshaller" isParam="true">org.jboss.jms.wireformat.JMSWireFormat</attribute>
+ <attribute name="dataType" isParam="true">jms</attribute>
+ <attribute name="socket.check_connection" isParam="true">false</attribute>
+ <attribute name="timeout" isParam="true">0</attribute>
+ <attribute name="serverBindAddress">${jboss.bind.address}</attribute>
+ <attribute name="serverBindPort">4457</attribute>
+ <attribute name="clientSocketClass" isParam="true">org.jboss.jms.client.remoting.ClientSocketWrapper</attribute>
+ <attribute name="serverSocketClass" isParam="true">org.jboss.jms.server.remoting.ServerSocketWrapper</attribute>
+ <attribute name="numberOfCallRetries" isParam="true">1</attribute>
+ <attribute name="pingFrequency" isParam="true">214748364</attribute>
+ <attribute name="pingWindowFactor" isParam="true">10</attribute>
+ <attribute name="onewayThreadPool">org.jboss.jms.server.remoting.DirectThreadPool</attribute>
+
+ <!-- Periodicity of client pings. Server window by default is twice this figure -->
+ <attribute name="clientLeasePeriod" isParam="true">10000</attribute>
+
+ <!-- Number of seconds to wait for a connection in the client pool to become free -->
+ <attribute name="numberOfRetries" isParam="true">10</attribute>
+
+ <!-- Max Number of connections in client pool. This should be significantly higher than
+ the max number of sessions/consumers you expect -->
+ <attribute name="clientMaxPoolSize" isParam="true">200</attribute>
+
+ <!-- Use these parameters to specify values for binding and connecting control connections to
+ work with your firewall/NAT configuration
+ <attribute name="secondaryBindPort">xyz</attribute>
+ <attribute name="secondaryConnectPort">abc</attribute>
+ -->
+
+ </invoker>
+ <handlers>
+ <handler subsystem="JMS">org.jboss.jms.server.remoting.JMSServerInvocationHandler</handler>
+ </handlers>
+</config>
+ </programlisting>
+
+
+ <para>
+ Some attributes should not be changed unless you know exactly what you are doing. Attributes that can be changed include:
+ </para>
+ <itemizedlist>
+ <listitem>
+ <para>
+ <varname>clientLeasePeriod</varname>
+ </para>
+ <para>
+ Clients periodically return <emphasis>heartbeats</emphasis> to the server to confirm that they are still active. If the server does not receive a heartbeat after a certain period of time, it will close down the connection and remove all resources that correspond to the client's session. The <varname>clientLeasePeriod</varname> determines the period of time between heartbeats, in milliseconds. The default value is <literal>10000</literal>.
+ </para>
+ <para>
+ By default, the server closes a client if it does not receive a heartbeat within double the <varname>clientLeasePeriod</varname>. In reality, the period is automatically resized according to system load.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <varname>numberOfRetries</varname>
+ </para>
+ <para>
+ The number of seconds JBoss Remoting blocks on the client pool while waiting for a connection to become available. If you have a very large number of sessions concurrently accessing the server from a client and cannot obtain connections from the pool, you may want to increase this value.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <varname>clientMaxPoolSize</varname>
+ </para>
+ <para>
+ JBoss Remoting maintains a client-side pool of TCP connections on which to service requests. If you have a large number of sessions concurrently accessing the server from a client and cannot obtain connections from the pool, you may want to increase this value.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <varname>secondaryBindPort</varname>
+ </para>
+ <para>
+ The bisocket transport uses control connections to pass control messages between server and client. This attribute defines the address to which the secondary <literal>ServerSocket</literal> is bound. To work behind a firewall, you may need to specify a particular value for your firewall configuration.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <varname>secondaryConnectPort</varname>
+ </para>
+ <para>
+ The port that the client uses to connect. Specify this to let your client work with NAT routers.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <varname>maxPoolSize</varname>
+ </para>
+ <para>
+ The number of threads used on the server side to service requests.
+ </para>
+ </listitem>
+ </itemizedlist>
+ <para>
+ By default, JBoss Messaging binds to <literal>${jboss.bind.address}</literal>, which can be defined by running the <command>./run.sh -c <yourconfig> -b yourIP</command> command.
+ </para>
+ <para>
+ If necessary, you can change <filename>remoting-bisocket-service.xml</filename> to use a different communication port.
+ </para>
+ <warning>
+ <para>
+ There is rarely a good reason to change values in the bisocket or sslbisocket connector configuration other than those listed previously. Changing other values can cause JBoss Messaging to stop functioning correctly.
+ </para>
+ </warning>
+ </section>
+
+ <!-- end conf.connector -->
+
+ <section id="conf.servicebindingmanager">
+ <title>ServiceBindingManager</title>
+
+ <para>
+ The <literal>SeviceBindingManager</literal> provides multiple application server instances running on the same IP using different port ranges, which is useful during development. There are other ways to do this, but the <literal>ServiceBindingManager</literal> removes much hassle.
+ </para>
+ <para>
+ In JBoss Messaging 4.x, the remoting configurations must match those defined in <filename>remoting-bisocket-service.xml</filename>.
+ </para>
+ <para>
+ If you are using a more recent version of JBoss Messaging in an older version of the JBoss Application Server, the example bindings in the Application Server distribution may be out of date. The relevant sections must therefore be overwritten with the remoting configuration from the JBoss Messaging distribution.
+ </para>
+ <para>
+ See the Installation chapter for further information about setting up the <literal>ServiceBindingManager</literal> for JBoss Messaging.
+ </para>
+ </section>
+
+ <!-- End conf.callback -->
+</chapter>
Added: projects/docs/enterprise/5.0/JBoss_Messaging_1.4.3/en-US/Getting_Started.xml
===================================================================
--- projects/docs/enterprise/5.0/JBoss_Messaging_1.4.3/en-US/Getting_Started.xml (rev 0)
+++ projects/docs/enterprise/5.0/JBoss_Messaging_1.4.3/en-US/Getting_Started.xml 2009-09-09 03:35:49 UTC (rev 93305)
@@ -0,0 +1,16 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<chapter id="gettingstarted">
+ <title>Download Software</title>
+ <para>
+ The official JBoss Messaging project page can be found at <ulink url="http://labs.jboss.com/jbossmessaging">http://labs.jboss.com/jbossmessaging/</ulink>.
+ </para>
+ <para>
+ You can download JBoss Messaging from the JBoss Labs Messaging Project download zone: <ulink url="http://labs.jboss.com/jbossmessaging/">http://labs.jboss.com/jbossmessaging/downloads</ulink>
+ </para>
+ <!--<section id="SVN">
+ <title>SVN Access</title>
+ <para>
+ To experiment with the latest developments, you can check the latest code out from the Messaging SVN trunk. Be aware that the information provided in this guide may not be accurate for the version in the trunk. For the latest instructions about checking out and building the source code, visit <ulink url="http://wiki.jboss.org/wiki/Wiki.jsp?page=JBossMessagingDevelopment">Messaging Development wiki page</ulink>, specifically <ulink url="http://wiki.jboss.org/wiki/Wiki.jsp?page=JBossMessagingBuildInstructions">"Building and Running JBoss Messaging"</ulink>.
+ </para>
+ </section>-->
+</chapter>
\ No newline at end of file
Added: projects/docs/enterprise/5.0/JBoss_Messaging_1.4.3/en-US/Installation.xml
===================================================================
--- projects/docs/enterprise/5.0/JBoss_Messaging_1.4.3/en-US/Installation.xml (rev 0)
+++ projects/docs/enterprise/5.0/JBoss_Messaging_1.4.3/en-US/Installation.xml 2009-09-09 03:35:49 UTC (rev 93305)
@@ -0,0 +1,1287 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<chapter id="installation">
+ <title>JBoss Messaging Installation</title>
+
+ <para>
+ JBoss Enterprise Application Platform (EAP) comes with JBoss Messaging pre-installed as the default JMS provider. If you are using EAP version 4.3 or higher, there is no need to manually install JBoss Messaging.
+ </para>
+ <!--<para>
+ This chapter explains how to create a JBoss Messaging configuration that will start a clustered or non-clustered messaging server.
+ </para>
+
+#modify: in which case, is the rest of this chapter strictly necessary?
+
+<para>
+ This section describes procedures on how to install JBoss Messaging
+ into JBoss Application Server community edition 4.2. At the end of this
+ procedure, you will create a JBoss Messaging configuration that will start a
+ clustered or non-clustered messaging server.</para>
+
+ <para>Please note that JBoss EAP 4.3 and JBoss 5 comes with JBoss Messaging
+ pre-installed as default JMS provider so if you are using that, there is no need to manually
+ install JBoss Messaging</para>
+
+ <para>By default, JBoss AS 4.2 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><note>
+ 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.sar</filename>
+
+ over to the JBoss instance
+
+ <filename>deploy</filename>
+
+ directory. Follow one of the alternate installation procedures outlined below instead.
+ </note></para>
+
+ <para><note>
+ We only recommend and support installing JBoss Messaging in JBoss AS 4.2 or later. You should avoid using JBoss Messaging on any version of JBoss AS prior to JBoss 4.2.0.GA, such as 4.0.5.GA and 4.0.4.GA.
+ </note><note>
+ JBoss Messaging is built against the JBoss AS 4.2 libraries which are built using Java 5. Therefore JBoss Messaging only runs with Java 5 or later.
+ </note></para>
+
+ <section id="install">
+ <title>Installing JBoss Messaging on JBoss AS 4.2</title>
+
+ <para>In this section we present two different methods of installing JBoss
+ Messaging in JBoss AS 4.2</para>
+
+ <itemizedlist>
+ <listitem>
+ If you have a completely clean JBoss AS 4.2.0 installation then you can do an
+
+ <xref linkend="install.automated">automatic install</xref>
+
+ .
+ </listitem>
+
+ <listitem>
+ If you have a JBoss 4.2.0 that you have changed in some way from a clean JBoss AS 4.2.0 installation then you will need to do a
+
+ <xref linkend="install.manual">manual install</xref>
+
+ .
+ </listitem>
+ </itemizedlist>
+
+ <section id="install.automated">
+ <title>Automated Installation</title>
+
+ <para><note>
+ This procedure should only be performed from a clean JBoss AS 4.2 installation. If you have modifed the JBoss AS 4.2 installation at all since installation then you will need to perform a manual clustered JBoss Messaging installation
+ </note></para>
+
+ <itemizedlist>
+ <listitem>
+ <para>Set up the <literal>JBOSS_HOME</literal> environment variable
+ to point to the JBoss 4.2 installation you want to use JBoss
+ Messaging with.</para>
+
+ <para>Run the installation script, available in the
+ <filename>util</filename> directory of the release bundle as
+ follows:</para>
+
+ <para>If you want to create a simple non clustered installion based
+ on the default configuration:</para>
+
+ <programlisting>
+ cd util
+ ant -f release-admin.xml
+ </programlisting>
+
+ <para>If you want to create a clustered installation based on the
+ all configuration or change the configuration name:</para>
+
+ <programlisting>
+ cd util
+ ant -f release-admin.xml -Dmessaging.config.source=all -Dmessaging.config.name=messaging-node0
+ </programlisting>
+
+ <para>In the above you would substitute
+ <literal>messaging-node0</literal> with whatever is the name you
+ want to give the configuration. If you want several cluster nodes on
+ the same machine, e.g. for development purposes then a good
+ convention is to name them <literal>messaging-node0,
+ messaging-node1</literal> to match
+ <literal>messaging-node<ServerPeerID></literal></para>
+
+ <para>The messaging.config.source variable determines which JBoss AS
+ configuration (e.g. default or all) to base the installation
+ on</para>
+
+ <para>The installation script will create a
+ <filename>$JBOSS_HOME/server/messaging-node0</filename>
+ configuration. (If you have chosen
+ <literal>messaging-node0</literal>)</para>
+ </listitem>
+
+ <para>For the rest of the procedure we assume JBOSS_CONFIG refers to
+ your new messaging configuration (e.g. messaging-node0 or
+ messaging)</para>
+
+ <para>You don't actually have to create an environment variable
+ <literal>JBOSS_CONFIG</literal>, this is just used in the installation
+ instructions to describe the steps</para>
+
+ <listitem>
+ <para>
+ <warning>For a clustered installation it is mandatory that a
+ shared database is available to all nodes in the cluster. The
+ default JBoss AS uses HSQLDB for its database which is a local
+ shared database. Therefore in order to use clustering you must
+ replace this with a different shared database. If the database is
+ not replaced then clustering will not work.</warning>
+ </para>
+
+ <itemizedlist>
+ <listitem>
+ <para>Replace
+ <literal>$JBOSS_CONFIG/deploy/jboss-messaging.sar/hsqldb-persistence-service.xml</literal>
+ by the <literal>databasename>-persistence-service</literal>
+ from
+ <literal><downloadPackage>/examples/config.</literal>. For
+ instance <literal>mysql-persistence-service.xml</literal></para>.
+ <para>If you are installing in a clustered configuration
+ make sure to set the <literal>Clustered</literal> attribute to <literal>true</literal></para>
+ </listitem>
+
+ <listitem><para>Configure a JCA datasource using an example from
+ <literal>$JBOSS_HOME/docs/examples/jca</literal></para> and
+ copying to <literal>$JBOSS_CONFIG/deploy</literal> <para>JBoss
+ Messaging uses <literal>DefaultDS</literal> by default so you
+ should configure your datasource to bind to that</para></listitem>
+
+ <listitem>
+ <para>Remove hsqldb-ds.xml from
+ <literal>$JBOSS_CONFIG/deploy</literal></para>
+ </listitem>
+
+ <listitem>
+ <para>Copy your database driver to
+ <literal>$JBOSS_CONFIG/lib</literal></para>
+
+ <para>Your database driver can probably be downloaded from your
+ database provider's web site</para>
+ </listitem>
+ </itemizedlist>
+ </listitem>
+
+ <listitem>
+ <para>Ensure the <literal>ServerPeerID</literal> MBean attribute
+ value in messaging-service.xml is unique for each node. The
+ <literal>ServerPeerID</literal> value must be a valid integer. Every
+ node MUST have a unique id, including those just connected by
+ message bridges.</para>
+
+ <para>
+ <warning>Each node must have a unique
+ <literal>ServerPeerID</literal> irrespective of whether you are
+ using clustering.</warning>
+ </para>
+ </listitem>
+ <listitem>
+ <para>If you want to run multiple JBoss Messaging nodes on the same
+ box using the same IP address, e.g. for development purposes, then
+ you can use the ServiceBindingManager to do this as follows:</para>
+
+ <para><warning>JBoss5 has introduced a much simpler ServiceBindingManager.
+ You should refer to the JBoss5 documentation about how to administer the new bindingManager if you are using JBoss5.
+ </warning></para>
+
+
+ <itemizedlist>
+ <listitem>
+ <para>Uncomment binding manager service from
+ $JBOSS_CONFIG/conf/jboss-service.xml</para>
+ </listitem>
+
+ <listitem>
+ <para>Specify the desired port rage (e.g. ports-01, ports-02...
+ etc)</para>
+ </listitem>
+
+ <listitem>
+ <para>Look at
+ $JBOSS_HOME/docs/examples/binding-manager/sample-bindings.xml.
+ Here is an example:</para>
+
+ <programlisting>
+ <service-config name="jboss.messaging:service=Connector,transport=bisocket"
+ delegateClass="org.jboss.services.binding.AttributeMappingDelegate">
+ <delegate-config>
+ <attribute name="Configuration"><![CDATA[
+ <config>
+ <invoker transport="bisocket">
+
+ <! There should be no reason to change these parameters - warning!
+ Changing them may stop JBoss Messaging working correctly >
+ <attribute name="marshaller" isParam="true">org.jboss.jms.wireformat.JMSWireFormat</attribute>
+ <attribute name="unmarshaller" isParam="true">org.jboss.jms.wireformat.JMSWireFormat</attribute>
+ <attribute name="dataType" isParam="true">jms</attribute>
+ <attribute name="socket.check_connection" isParam="true">false</attribute>
+ <attribute name="timeout" isParam="true">0</attribute>
+ <attribute name="serverBindAddress">${jboss.bind.address}</attribute>
+ <attribute name="serverBindPort">4657</attribute>
+ <attribute name="clientSocketClass" isParam="true">org.jboss.jms.client.remoting.ClientSocketWrapper</attribute>
+ <attribute name="serverSocketClass" isParam="true">org.jboss.jms.server.remoting.ServerSocketWrapper</attribute>
+ <attribute name="numberOfCallRetries" isParam="true">1</attribute>
+ <attribute name="pingFrequency" isParam="true">214748364</attribute>
+ <attribute name="pingWindowFactor" isParam="true">10</attribute>
+ <attribute name="onewayThreadPool">org.jboss.jms.server.remoting.DirectThreadPool</attribute>
+
+ <! Periodicity of client pings. Server window by default is twice this figure >
+ <attribute name="clientLeasePeriod" isParam="true">10000</attribute>
+
+ <! Number of seconds to wait for a connection in the client pool to become free ->
+ <attribute name="numberOfRetries" isParam="true">10</attribute>
+
+ <!- Max Number of connections in client pool. This should be significantly higher than
+ the max number of sessions/consumers you expect ->
+ <attribute name="JBM_clientMaxPoolSize" isParam="true">200</attribute>
+
+ <!- Use these parameters to specify values for binding and connecting control connections to
+ work with your firewall/NAT configuration
+ <attribute name="secondaryBindPort">xyz</attribute>
+ <attribute name="secondaryConnectPort">abc</attribute>
+ ->
+
+ </invoker>
+ <handlers>
+ <handler subsystem="JMS">org.jboss.jms.server.remoting.JMSServerInvocationHandler</handler>
+ </handlers>
+ </config>
+ ]]></attribute>
+ </delegate-config>
+ <binding port="4657"/>
+ </service-config>
+
+ </programlisting>
+
+ <warning>The above config only apply to JBoss 4.2 and EAP 4.3.
+ On EAP4.3 and JBOSS 4.2 You must ensure that the config (like above) is
+ identical to that in
+ <literal>remoting-bisocket-service.xml</literal> With the
+ exception of the actual serverBindPort which clearly must be
+ different for each ports range. Please note that the default
+ JBoss Messaging service binding manager bindings in
+ <literal>sample-bindings.xml</literal> shipped with JBAS 4.2.0
+ may be out of date and you will need to copy the config from
+ <literal>remoting-bisocket-service.xml. DO NOT just copy and
+ paste from the above example - copy it from the JBoss Messaging
+ distribution.</literal>. On JBoss5 the ports are controlled by
+ system-property substitution hence you don't need to worry about copying the config into bindings.xml</warning>
+
+ <para>You should ensure that each node is configured to use a
+ different ports range.</para>
+ </listitem>
+ </itemizedlist>
+ </listitem>
+
+ <listitem>
+ <para>There are few extra steps at <xref
+ linkend="install.extra-steps" /></para>
+ </listitem>
+
+ <listitem>That's it</listitem>
+ </itemizedlist>
+ </section>
+
+ <section id="install.manual">
+ <title>Manual Installation</title>
+
+ <para><note>
+ This installation procedure should be performed if you are installing into a JBoss AS configuration that you have changed in some way from the default JBoss AS distribution. If you are just using the standard, untouched JBoss AS 4.2 distribution you can use the automated procedure above
+ </note></para>
+
+ <para>For this procedure we assume you already have your custom
+ configuration located at
+ <literal>JBOSS_CONFIG=$JBOSS_HOME/server/<myconfiguration></literal>,
+ and that it contains a JBoss MQ installation.</para>
+
+ <para>You don't actually have to create an environment variable
+ <literal>JBOSS_CONFIG</literal>, this is just used in the installation
+ instructions to describe the steps</para>
+
+ <itemizedlist>
+ <listitem>
+ <para>Move
+ <literal>$JBOSS_CONFIG/deploy/jms/hajndi-jms-ds.xml</literal> and
+ <literal>$JBOSS_CONFIG/deploy/jms/jms-ra.rar</literal> to
+ <literal>$JBOSS_CONFIG/deploy</literal></para>
+ </listitem>
+
+ <listitem>
+
+
+ <para>Remove the old JBoss MQ by removing the directory
+ <literal>$JBOSS_CONFIG/deploy/jms.</literal></para>
+
+ .
+
+ <para>Remove the old JBoss MQ jar file:
+ <literal>$JBOSS_CONFIG/lib/jbossmq.jar</literal></para>
+
+
+
+ <para>Make sure you don't have any JBossMQ files under
+ <literal>$JBOSS_CONFIG/deploy-hasingleton</literal>. For that just
+ remove
+ <literal>$JBOSS_CONFIG/deploy-hasingleton/jms</literal></para>
+
+
+ </listitem>
+
+ <listitem>
+
+
+ <para>Add a security policy called "messaging" on
+ $JBOSS_CONFIG/config/login-config.xml. You could use this as an
+ example, or create one according to JBoss Security
+ Documentation:</para>
+
+
+
+ <programlisting>
+<application-policy name = "messaging">
+<authentication>
+<login-module code = "org.jboss.security.auth.spi.UsersRolesLoginModule" flag = "required" >
+ <module-option name = "unauthenticatedIdentity">guest</module-option>
+ <module-option name = "usersProperties">props/messaging-users.properties</module-option>
+ <module-option name = "rolesProperties">props/messaging-roles.properties</module-option>
+</login-module>
+</authentication>
+</application-policy>
+ </programlisting>
+
+
+
+ <para>In case you are using the above policy you should also create
+ files <literal>messaging-users.properties</literal> and
+ <literal>messaging-roles.properties</literal> in the
+ <literal>$JBOSS_CONFIG/config/props/</literal> directory</para>
+
+ .
+
+ <para>
+ <note>You can find an example
+ <literal>messaging-users.properties</literal> and
+ <literal>messaging-roles.properties</literal> in the JBoss
+ Messaging distribution in the
+ <literal><downloadPackage>src/etc/server/default/config</literal>
+ directory.</note>
+ </para>
+
+
+
+ <programlisting>
+# messaging-roles.properties
+# Add roles as you like
+# user=role1,role2,...
+#
+guest=guest
+ </programlisting>
+
+
+
+ <programlisting>
+# messaging-users.properties
+
+# Add users as you like
+# user=password
+#
+guest=guest
+ </programlisting>
+
+
+ </listitem>
+
+ <listitem>
+ <para>Unzip jboss-messaging.sar from your download package into the
+ directory
+ <literal>JBOSS_CONFIG/deploy/jboss-messaging.sar</literal></para>
+
+ <para>JBoss Messaging should be deployed unzipped (exploded) so you
+ have easy access to its config files which are stored there.</para>
+ </listitem>
+
+ <listitem>
+ <para>Copy jboss-messaging.jar from your download package into the
+ directory <literal>JBOSS_CONFIG/lib</literal></para>
+
+ <para>jboss-messaging.jar needs to go in the lib directory so it is
+ accessible to other services e.g. the JBoss Transactions Recovery
+ Manager</para>
+ </listitem>
+
+ <listitem>
+ <para><warning>
+ For a clustered installation it is mandatory that a shared database is available to all nodes in the cluster. The default JBoss AS uses HSQLDB for its database which is a local shared database. Therefore in order to use clustering you must replace this with a different shared database. If the database is not replaced then clustering will not work.
+ </warning></para>
+
+ <itemizedlist>
+ <listitem>
+ <para>Replace
+ <literal>$JBOSS_CONFIG/deploy/jboss-messaging.sar/hsqldb-persistence-service.xml</literal>
+ by the <literal>databasename>-persistence-service</literal>
+ from
+ <literal><downloadPackage>/examples/config.</literal>. For
+ instance <literal>mysql-persistence-service.xml</literal></para>
+
+ <para>If you are installing in a clustered configuration
+ make sure to set the <literal>Clustered</literal> attribute to <literal>true</literal></para>
+ </listitem>
+
+ <listitem>
+
+
+ <para>Configure a JCA datasource using an example from
+ <literal>$JBOSS_HOME/docs/examples/jca</literal></para>
+
+ and copying to
+
+ <literal>$JBOSS_CONFIG/deploy</literal>
+
+
+
+ <para>JBoss Messaging uses <literal>DefaultDS</literal> by
+ default so you should configure your datasource to bind to
+ that</para>
+
+
+ </listitem>
+
+ <listitem>
+ <para>Remove hsqldb-ds.xml from
+ <literal>$JBOSS_CONFIG/deploy</literal></para>
+ </listitem>
+
+ <listitem>
+ <para>Copy your database driver to
+ <literal>$JBOSS_CONFIG/lib</literal></para>
+
+ <para>Your database driver can probably be downloaded from your
+ database provider's web site</para>
+ </listitem>
+ </itemizedlist>
+ </listitem>
+
+ <listitem>
+ <para>Ensure the <literal>ServerPeerID</literal> MBean attribute
+ value in messaging-service.xml is unique for each node on the
+ cluster. The <literal>ServerPeerID</literal> value must be a valid
+ integer.</para>
+
+ <para><warning>
+ Each node must have a unique
+
+ <literal>ServerPeerID</literal>
+
+ irrespective of whether you are using clustering.
+ </warning></para>
+ </listitem>
+
+ <listitem>
+ <para>If you want to run multiple JBoss Messaging nodes on the same
+ box using the same IP address, e.g. for development purposes, then
+ you can use the ServiceBindingManager to do this as follows:</para>
+
+ <itemizedlist>
+ <listitem>
+ <para>Uncomment binding manager service from
+ $JBOSS_CONFIG/conf/jboss-service.xml</para>
+ </listitem>
+
+ <listitem>
+ <para>Specify the desired port rage (e.g. ports-01, ports-02...
+ etc)</para>
+ </listitem>
+
+ <listitem>
+ <para>Look at
+ $JBOSS_HOME/docs/examples/binding-manager/sample-bindings.xml.
+ On each port range, JBoss Remoting configuration should look
+ like:</para>
+
+ <programlisting>
+ <service-config name="jboss.messaging:service=Connector,transport=bisocket"
+ delegateClass="org.jboss.services.binding.AttributeMappingDelegate">
+ <delegate-config>
+ <attribute name="Configuration"><![CDATA[
+ <config>
+ <invoker transport="bisocket">
+
+ <!- There should be no reason to change these parameters - warning!
+ Changing them may stop JBoss Messaging working correctly ->
+ <attribute name="marshaller" isParam="true">org.jboss.jms.wireformat.JMSWireFormat</attribute>
+ <attribute name="unmarshaller" isParam="true">org.jboss.jms.wireformat.JMSWireFormat</attribute>
+ <attribute name="dataType" isParam="true">jms</attribute>
+ <attribute name="socket.check_connection" isParam="true">false</attribute>
+ <attribute name="timeout" isParam="true">0</attribute>
+ <attribute name="serverBindAddress">${jboss.bind.address}</attribute>
+ <attribute name="serverBindPort">4657</attribute>
+ <attribute name="clientSocketClass" isParam="true">org.jboss.jms.client.remoting.ClientSocketWrapper</attribute>
+ <attribute name="serverSocketClass" isParam="true">org.jboss.jms.server.remoting.ServerSocketWrapper</attribute>
+ <attribute name="numberOfCallRetries" isParam="true">1</attribute>
+ <attribute name="pingFrequency" isParam="true">214748364</attribute>
+ <attribute name="pingWindowFactor" isParam="true">10</attribute>
+ <attribute name="onewayThreadPool">org.jboss.jms.server.remoting.DirectThreadPool</attribute>
+
+ <!- Periodicity of client pings. Server window by default is twice this figure ->
+ <attribute name="clientLeasePeriod" isParam="true">10000</attribute>
+
+ <!- Number of seconds to wait for a connection in the client pool to become free ->
+ <attribute name="numberOfRetries" isParam="true">10</attribute>
+
+ <!- Max Number of connections in client pool. This should be significantly higher than
+ the max number of sessions/consumers you expect ->
+ <attribute name="JBM_clientMaxPoolSize" isParam="true">200</attribute>
+
+ <!- Use these parameters to specify values for binding and connecting control connections to
+ work with your firewall/NAT configuration
+ <attribute name="secondaryBindPort">xyz</attribute>
+ <attribute name="secondaryConnectPort">abc</attribute>
+ ->
+
+ </invoker>
+ <handlers>
+ <handler subsystem="JMS">org.jboss.jms.server.remoting.JMSServerInvocationHandler</handler>
+ </handlers>
+ </config>
+ ]]></attribute>
+ </delegate-config>
+ <binding port="4657"/>
+ </service-config>
+
+ </programlisting>
+
+ <warning>
+ You must ensure that the config (like above) is identical to that in
+
+ <literal>remoting-bisocket-service.xml</literal>
+
+ With the exception of the actual serverBindPort which clearly must be different for each ports range. Please note that the default JBoss Messaging service binding manager bindings in
+
+ <literal>sample-bindings.xml</literal>
+
+ shipped with JBAS 4.2.0 may be out of date and you will need to copy the config from
+
+ <literal>remoting-bisocket-service.xml. DO NOT just copy and
+ paste from the above example - copy it from the JBoss
+ Messaging distribution.</literal>
+
+
+
+ <literal />
+
+
+
+ <literal />
+
+
+
+ <literal />
+
+
+ </warning>
+
+ <para>You should ensure that each node is configured to use a
+ different ports range.</para>
+ </listitem>
+ </itemizedlist>
+ </listitem>
+
+ <listitem>
+ <para>There are few extra steps at <xref
+ linkend="install.extra-steps" /></para>
+ </listitem>
+
+ <listitem>
+ That's it
+ </listitem>
+ </itemizedlist>
+ </section>
+
+ <section id="install.extra-steps">
+ <title>Extra steps to complete your installation</title>
+
+ <itemizedlist>
+ <listitem>
+ <para>
+ <warning>SECURITY RISK! To avoid a security risk, you MUST specify
+ the value of the attribute SuckerPassword in the Server Peer
+ config (messaging-service.xml). If you do not specify a value, the
+ default value will be used. Any person that knows the default
+ value will be able to access to all destinations on the server.
+ The password chosen should only be exposed to
+ administrators</warning>
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ <note>
+ JBoss Messaging 1.4.3.GA requires pecific versions
+ of jboss-remoting.jar if used outside of JBoss 5. If you are installing JBoss Messaging 1.4.3.GA at JBoss 4.2+, you should use this version:
+ <ulink url="http://repository.jboss.com/jboss/remoting/2.5.0.SP2/ ">Remoting 2.5.0.SP2</ulink>.
+ If you are using JBoss5 you don't need to take any extra steps on the remoting installation.
+ </note>
+ </para>
+ </listitem>
+
+ <para>You should also make these changes on any configuration you
+ choose, to remove all references to the old JBossMQ:</para>
+
+ <listitem>
+ <para>Edit <literal>$JBOSS_CONFIG/deploy/jms-ds.xml</literal> and
+ replace jboss.mq by jboss.messaging on every occurrence</para>
+
+ <para>If you are in a clustered installation, then do the above with
+ the file
+ <literal>$JBOSS_CONFIG/deploy/hajndi-jms-ds.xml</literal></para>
+ </listitem>
+
+ <listitem>
+ <para>Edit <literal>$JBOSS_CONFIG/conf/standardjboss.xml</literal>
+ and set <literal>CreateJBossMQDestination</literal> to false on
+ every occurrence</para>
+
+ <para>Make sure it looks like this:</para>
+
+ <para>
+ <literal><CreateJBossMQDestination>false</CreateJBossMQDestination></literal>
+ </para>
+
+ <para>Those Proxies will try to create a Destination on JBossMQ if
+ they can't find it on JNDI, what would cause some errors related to
+ JBoss MQ.</para>
+ </listitem>
+
+ <listitem>
+ <para>Edit $JBOSS_CONFIG/conf/jboss-service.xml and remove the
+ reference to JBoss MQ on JSR-77 Management Bean:</para>
+
+ <programlisting>
+ <!- ==================================================================== ->
+ <!- JSR-77 Single JBoss Server Management Domain ->
+ <!- ==================================================================== ->
+ <mbean code="org.jboss.management.j2ee.LocalJBossServerDomain"
+
+ ... Remove this line ...
+ <attribute name="JMSService">jboss.mq:service=DestinationManager</attribute>
+ </programlisting>
+ </listitem>
+
+ <listitem>
+ <para>Change <literal>$JBOSS_CONFIG/conf/login-config.xml</literal>
+ and remove jboss-mq security policies</para>
+
+ <programlisting>
+### Remove these lines:
+
+<!- Security domain for JBossMQ ->
+<application-policy name = "jbossmq">
+ <authentication>
+ <login-module code = "org.jboss.security.auth.spi.DatabaseServerLoginModule"
+ flag = "required">
+ <module-option name = "unauthenticatedIdentity">guest</module-option>
+ <module-option name = "dsJndiName">java:/DefaultDS</module-option>
+ <module-option name = "principalsQuery">
+ SELECT PASSWD FROM JMS_USERS WHERE USERID=?</module-option>
+ <module-option name = "rolesQuery">
+ SELECT ROLEID, 'Roles' FROM JMS_ROLES WHERE USERID=?</module-option>
+ </login-module>
+ </authentication>
+</application-policy>
+
+<!- Security domain for JBossMQ when using file-state-service.xml
+<application-policy name = "jbossmq">
+ <authentication>
+ <login-module code = "org.jboss.mq.sm.file.DynamicLoginModule"
+ flag = "required">
+ <module-option name = "unauthenticatedIdentity">guest</module-option>
+ <module-option name = "sm.objectname">jboss.mq:service=StateManager</module-option>
+ </login-module>
+ </authentication>
+</application-policy>
+->
+
+ </programlisting>
+ </listitem>
+ </itemizedlist>
+ </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 <config name>
+ </programlisting>
+
+ <para>Where config_name is the name of the JBoss AS configuration where
+ you have installed messaging. (The default is 'messaging')</para>
+
+ <para>A successful JBoss Messaging deployment generates logging output
+ similar to for a non clustered installation (for a clustered installation
+ you will also see extra cluster related output)</para>
+
+ <programlisting>
+....
+13:19:14,914 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.
+
+13:19:15,166 INFO [ServerPeer] JBoss Messaging 1.4.0.GA server [0] started
+13:19:15,411 INFO [ConnectionFactory] Connector bisocket://127.0.0.1:4457 has leasing enabled
+, lease period 10000 milliseconds
+13:19:15,412 INFO [ConnectionFactory] [/ConnectionFactory, /XAConnectionFactory, java:/Connec
+tionFactory, java:/XAConnectionFactory] started
+13:19:15,412 WARN [ConnectionFactoryJNDIMapper] supportsFailover attribute is true on connect
+ion factory: jboss.messaging.connectionfactory:service=ClusteredConnectionFactory but
+post office is non clustered. So connection factory will *not* support failover
+13:19:15,413 WARN [ConnectionFactoryJNDIMapper] supportsLoadBalancing attribute is true on co
+nnection factory: jboss.messaging.connectionfactory:service=ClusteredConnectionFactory
+but post office is non clustered. So connection factory will *not* support load balanc
+ing
+13:19:15,449 INFO [ConnectionFactory] Connector bisocket://127.0.0.1:4457 has leasing enabled
+, lease period 10000 milliseconds
+13:19:15,449 INFO [ConnectionFactory] [/ClusteredConnectionFactory, /ClusteredXAConnectionFac
+tory, java:/ClusteredConnectionFactory, java:/ClusteredXAConnectionFactory] started
+13:19:15,468 INFO [QueueService] Queue[/queue/DLQ] started, fullSize=200000, pageSize=2000, d
+ownCacheSize=2000
+13:19:15,474 INFO [QueueService] Queue[/queue/ExpiryQueue] started, fullSize=200000, pageSize
+=2000, downCacheSize=2000
+13:19:15,476 INFO [TopicService] Topic[/topic/testTopic] started, fullSize=200000, pageSize=2
+000, downCacheSize=2000
+13:19:15,478 INFO [TopicService] Topic[/topic/securedTopic] started, fullSize=200000, pageSiz
+e=2000, downCacheSize=2000
+13:19:15,479 INFO [TopicService] Topic[/topic/testDurableTopic] started, fullSize=200000, pag
+eSize=2000, downCacheSize=2000
+13:19:15,482 INFO [QueueService] Queue[/queue/testQueue] started, fullSize=200000, pageSize=2
+000, downCacheSize=2000
+13:19:15,483 INFO [QueueService] Queue[/queue/A] started, fullSize=200000, pageSize=2000, dow
+nCacheSize=2000
+13:19:15,485 INFO [QueueService] Queue[/queue/B] started, fullSize=200000, pageSize=2000, dow
+nCacheSize=2000
+13:19:15,487 INFO [QueueService] Queue[/queue/C] started, fullSize=200000, pageSize=2000, dow
+nCacheSize=2000
+13:19:15,489 INFO [QueueService] Queue[/queue/D] started, fullSize=200000, pageSize=2000, dow
+nCacheSize=2000
+13:19:15,490 INFO [QueueService] Queue[/queue/ex] started, fullSize=200000, pageSize=2000, do
+wnCacheSize=2000
+13:19:15,501 INFO [QueueService] Queue[/queue/PrivateDLQ] started, fullSize=200000, pageSize=
+2000, downCacheSize=2000
+13:19:15,503 INFO [QueueService] Queue[/queue/PrivateExpiryQueue] started, fullSize=200000, p
+ageSize=2000, downCacheSize=2000
+13:19:15,507 INFO [QueueService] Queue[/queue/QueueWithOwnDLQAndExpiryQueue] started, fullSiz
+e=200000, pageSize=2000, downCacheSize=2000
+13:19:15,508 INFO [TopicService] Topic[/topic/TopicWithOwnDLQAndExpiryQueue] started, fullSiz
+e=200000, pageSize=2000, downCacheSize=2000
+13:19:15,511 INFO [QueueService] Queue[/queue/QueueWithOwnRedeliveryDelay] started, fullSize=
+200000, pageSize=2000, downCacheSize=2000
+13:19:15,512 INFO [TopicService] Topic[/topic/TopicWithOwnRedeliveryDelay] started, fullSize=
+200000, pageSize=2000, downCacheSize=2000
+13:19:15,514 INFO [QueueService] Queue[/queue/testDistributedQueue] started, fullSize=200000,
+pageSize=2000, downCacheSize=2000
+13:19:15,519 INFO [TopicService] Topic[/topic/testDistributedTopic] started, fullSize=200000,
+pageSize=2000, downCacheSize=2000
+13:19:15,809 INFO [ConnectionFactoryBindingService] Bound ConnectionManager 'jboss.jca:servic
+e=ConnectionFactoryBinding,name=JmsXA' to JNDI name 'java:JmsXA'
+13:19:15,834 INFO [TomcatDeployer] deploy, ctxPath=/jmx-console, warUrl=.../deploy/jmx-consol
+e.war/
+13:19:16,322 INFO [Http11Protocol] Starting Coyote HTTP/1.1 on http-127.0.0.1-8080
+13:19:16,342 INFO [AjpProtocol] Starting Coyote AJP/1.3 on ajp-127.0.0.1-8009
+13:19:16,480 INFO [Server] JBoss (MX MicroKernel) [4.2.0.GA (build: SVNTag=JBoss_4_2_0_GA dat
+e=200705111440)] Started in 19s:359ms
+
+ </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 Oracle, Sybase, PostgreSQL, MS SQL or MySQL, 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>
+
+ <para>Make sure you start the JBoss server before trying to run the
+ tests</para>
+
+ <programlisting>
+
+setenv JBOSS_HOME=<your_JBoss_installation>
+cd .../examples/queue
+$ant
+
+ </programlisting>
+
+ <para>A successfull execution log output looks similar to:</para>
+
+ <programlisting>
+[tim at Vigor14 queue]$ ant
+Buildfile: build.xml
+
+identify:
+ [echo] ###########################################################################
+ [echo] # Running the QUEUE example #
+ [echo] ###########################################################################
+ [echo] The queue: testQueue
+ [echo] The client jar: ../../../output/lib/jboss-messaging-client.jar
+
+sanity-check:
+
+init:
+ [mkdir] Created dir: /home/tim/dev/jboss-messaging/trunk/docs/examples/queue/output/classe
+s
+ [mkdir] Created dir: /home/tim/dev/jboss-messaging/trunk/docs/examples/common/output/class
+es
+
+compile:
+ [javac] Compiling 5 source files to /home/tim/dev/jboss-messaging/trunk/docs/examples/comm
+on/output/classes
+ [javac] Compiling 1 source file to /home/tim/dev/jboss-messaging/trunk/docs/examples/queue
+/output/classes
+
+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.4.0.GA (1.4)
+
+ [java] #####################
+ [java] ### SUCCESS! ###
+ [java] #####################
+
+BUILD SUCCESSFUL
+Total time: 5 seconds
+[tim at Vigor14 queue]$
+
+</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>
+
+ <section id="inst.remoteclient">
+ <title>Accessing JBoss Messaging from a remote client - JBoss 4.2 and EAP 4.3</title>
+
+ <para>In order to access JBoss Messaging from a client outside the JBoss
+ app server, you will need to ensure the following jar files are on the
+ client classpath:</para>
+
+ <itemizedlist>
+ <listitem>
+ <para><note>
+ If you are using JBoss Messaging 1.4.3.GA outiside of JBoss 4.2 or EAP 4.3, you need to make sure you use a JBoss Remoting 2.5.0.SP2. If you are using JBoss5 or EAP 4.3 you will have the required JAR available already:
+ The version could be found at:
+
+ <ulink
+ url="http://repository.jboss.com/jboss/remoting/2.5.0.SP2/lib/">here</ulink>
+
+ . Please download it and make sure this jar is on your classpath *before* jbossall-client.jar.
+ </note></para>
+ </listitem>
+
+ <listitem>
+ <para>jboss-messaging-client.jar - This is available in the messaging
+ distribution</para>
+ </listitem>
+
+ <listitem>
+ <para>jbossall-client.jar - This is available in your
+ $JBOSS_HOME/client directory</para>
+ </listitem>
+
+ <listitem>
+ <para>$JBOSS_HOME/server/<SERVER_NAME>/deploy/jboss-aop.deployer/jboss-aop.jar</para>
+
+ <para>JBoss AOP 2.0.1.GA</para>
+
+ <para><ulink url="http://repository.jboss.com/jboss/aop/2.0.1.GA/lib/">http://repository.jboss.com/jboss/aop/2.0.1.GA/lib/</ulink></para>
+
+ <para>(For AOP, sometimes you have to use a specific JAR according to
+ your JVM of choice. Use the most convenient for you)</para>
+ </listitem>
+
+ <listitem>
+ <para>$JBOSS_HOME/server/<SERVER_NAME>/lib/javassist.jar</para>
+
+ <para>Javassist 3.9.0.GA</para>
+
+ <para><ulink
+ url="http://repository.jboss.com/javassist/3.9.0.GA/lib/">http://repository.jboss.com/javassist/3.9.0.GA/lib/</ulink></para>
+ </listitem>
+
+ <listitem>
+ <para>$JBOSS_HOME/server/<SERVER_NAME>/lib/trove.jar</para>
+
+ <para>trove 1.0.2</para>
+
+ <para><ulink
+ url="http://repository.jboss.com/trove/1.0.2/lib/">http://repository.jboss.com/trove/1.0.2/lib/</ulink></para>
+ </listitem>
+
+ <listitem>
+ <para>log4j</para>
+ </listitem>
+ </itemizedlist>
+ </section>
+
+ <section id="inst.remoteclient.jb5">
+ <title>Accessing JBoss Messaging from a remote client - JBoss 5.0</title>
+
+ <para>In order to access JBoss Messaging from a client outside the JBoss
+ app server, you will need to ensure the following jar files are on the
+ client classpath:</para>
+
+ <itemizedlist>
+ <listitem>
+ <para>$JBOSS_HOME/client/jnp-client.jar</para>
+ </listitem>
+ <listitem>
+ <para>$JBOSS_HOME/client/jboss-javaee.jar</para>
+ </listitem>
+ <listitem>
+ <para>$JBOSS_HOME/client/jboss-messaging.jar</para>
+ </listitem>
+ <listitem>
+ <para>$JBOSS_HOME/client/jboss-remoting.jar</para>
+ </listitem>
+ <listitem>
+ <para>$JBOSS_HOME/client/jboss-serialization.jar</para>
+ </listitem>
+ <listitem>
+ <para>$JBOSS_HOME/client/javassist.jar</para>
+ </listitem>
+ <listitem>
+ <para>$JBOSS_HOME/client/jboss-aop-client.jar</para>
+ </listitem>
+ <listitem>
+ <para>$JBOSS_HOME/client/trove.jar</para>
+ </listitem>
+ <listitem>
+ <para>$JBOSS_HOME/client/log4j.jar</para>
+ </listitem>
+ <listitem>
+ <para>$JBOSS_HOME/client/jboss-logging-spi.jar</para>
+ </listitem>
+ <listitem>
+ <para>$JBOSS_HOME/client/jboss-logging-log4j.jar</para>
+ </listitem>
+ <listitem>
+ <para>$JBOSS_HOME/client/jboss-common-core.jar</para>
+ </listitem>
+ <listitem>
+ <para>$JBOSS_HOME/client/jboss-mdr.jar</para>
+ </listitem>
+ <listitem>
+ <para>$JBOSS_HOME/client/concurrent.jar</para>
+ </listitem>
+ </itemizedlist>
+ </section>
+
+ <section id="inst.mqmessagemigration">
+ <title>Migrating Messages from JBoss MQ to JBoss Messaging</title>
+
+ <para>This configuration will allow you to migrate your systems using
+ JBossMQ to JBM(JBoss Messaging). Many Enterprise systems are complex and
+ have multiple applications and can't be migrated from JBossMQ to JBM all
+ at one time.</para>
+
+ <para>Made up Use Case: For instance, your business is selling items, some
+ you make directly and some you farm out to other distributors. Your
+ ordering system is JBossMQ based. Customers place orders that are then
+ queued up to be processed(via JBossMQ). You also use MQ to queue up the
+ orders that you need to produce and you also queue up the orders that will
+ go to your other distributors. You use MDB's in three separate places in
+ your operation. You want to do a staged migration from JBossMQ to JBM.
+ That requires that JBossMQ and JBM work together. This is exactly what the
+ JBM bridge was meant to do. It's meant to take messages from one
+ queue/topic and transfer them to another queue/topic. This helps with the
+ migration by allowing you to pull messages from your JBossMQ queues
+ automatically and push them into your JBM Queues. You can also do the
+ opposite, you can push messages from your JBM system to your JBossMQ
+ system. In our example, we want to replace the ordering side(producer)
+ with JBM. We push messages into the JBM Order queue, but we set the bridge
+ up to send all of those messages to the JBossMQ Order queue. The rest of
+ your processing happens as normal. Lets say you want to leave your
+ ordering system intact, but you want to have JBM and EJB3 MDBs process the
+ orders. You can have your old client put messages in JBossMQ as normal,
+ but you set the bridge up to pull the messages from JBossMQ Order queue
+ and push them into the JBM Order queue.</para>
+
+ <para>This allows JBM and JBossMQ to interact together by pushing messages
+ back and forth between different systems.</para>
+
+ <para>The Following Assumptions are made:</para>
+
+ <itemizedlist>
+ <listitem>You have one JBoss instance set up for JBoss Messaging and One
+ Jboss instance set up that has your old JBoss MQ on it.</listitem>
+
+ <listitem>We are copying messages from JBossMQ(Source) to
+ JBM(Target)</listitem>
+ </itemizedlist>
+
+ <section id="inst.mqmessagemigration.steps">
+ <title>Steps to Set up the bridge</title>
+
+ <itemizedlist>
+ <listitem>
+ <para>Copy the jbossmq.jar from the Source Machine(JBossMQ) under
+ the server/default/lib/ to the messaging configuration on the Target
+ JBM machine(server/messaging/lib)</para>
+
+ <note>substitute what ever your messaging server configuration is
+ above. I used the default stand alone messaging server configuration
+ note: This is required to dereference the JBossMQ objects that are
+ dereferenced on the JBM side. If you don't copy the jar over, you
+ will get a "java.lang.ClassCastException: javax.naming.Reference"
+ exception and the bridge will not be able to start</note>
+ </listitem>
+
+ <listitem>
+ <para>Add the remote JBossMQ provider to the jms-ds.xml file in the
+ server/messaging/deploy directory on your target(JBM)
+ machine.</para>
+
+ <para>Here is an example of the provider to add.</para>
+
+ <programlisting>
+<mbean code="org.jboss.jms.jndi.JMSProviderLoader"
+ name="jboss.messaging:service=JMSProviderLoader,
+ name=MyRemoteJMSProvider">
+ <attribute name="ProviderName">RemoteXAConnectionFactory</attribute>
+ <attribute name="ProviderAdapterClass">org.jboss.jms.jndi.JNDIProviderAdapter</attribute>
+ <!- The combined connection factory ->
+ <attribute name="FactoryRef">XAConnectionFactory</attribute>
+ <!- The queue connection factory ->
+ <attribute name="QueueFactoryRef">XAConnectionFactory</attribute>
+ <!- The topic factory ->
+ <attribute name="TopicFactoryRef">XAConnectionFactory</attribute>
+ <attribute name="Properties">
+ java.naming.factory.initial=org.jnp.interfaces.NamingContextFactory
+ java.naming.factory.url.pkgs=org.jboss.naming:org.jnp.interfaces
+ java.naming.provider.url=192.168.0.199:1099
+ </attribute>
+</mbean>
+ </programlisting>
+
+ <note>you will need to change the java.naming.provider.url so that
+ it points to your JBossMQ machine. Everything else should remain the
+ same. Keep your jms-ds.xml file open, because you will be addning
+ another entry in it for the next step.</note>
+ </listitem>
+
+ <listitem>
+ <para>Add the Bridge provider to the jms-ds.xml file in the
+ server/messaging/deploy directory on your target(JBM)
+ machine.</para>
+
+ <para>Here is an example bridge configuration</para>
+
+ <programlisting>
+<mbean code="org.jboss.jms.server.bridge.BridgeService"
+ name="jboss.messaging:service=Bridge,name=TestBridge"
+ xmbean-dd="xmdesc/Bridge-xmbean.xml">
+ <depends optional-attribute-name="SourceProviderLoader">
+ jboss.messaging:service=JMSProviderLoader,
+ name=MyRemoteJMSProvider</depends>
+ <depends optional-attribute-name="TargetProviderLoader">
+ jboss.messaging:service=JMSProviderLoader,
+ name=JMSProvider</depends>
+ <attribute name="SourceDestinationLookup">/queue/testQueue</attribute>
+ <attribute name="TargetDestinationLookup">/queue/A</attribute>
+ <attribute name="QualityOfServiceMode">0</attribute>
+ <attribute name="MaxBatchSize">5</attribute>
+ <attribute name="MaxBatchTime">-1</attribute>
+ <attribute name="FailureRetryInterval">5000</attribute>
+ <attribute name="MaxRetries">-1</attribute>
+ <attribute name="AddMessageIDInHeader">false</attribute>
+</mbean>
+ </programlisting>
+
+ <note>my target is the current JBM JMS Provider and the source is
+ the JBossMQ remote provider. If you have a pretty stock system and
+ you want to move messages from JBossMQ to JBM, you will not have to
+ change this example except for the queue Names. If you wish to move
+ from JBM to JBossMQ, just switch the soure and target
+ definitions.</note>
+ </listitem>
+ </itemizedlist>
+
+ <para>Start the JBossMQ system and then just start the JBM system and
+ the messages will begin to move over.</para>
+
+ <para>The following is an example of the jms-ds.xml file that was used
+ for the test. If you want to test the bridge first and you have a stock
+ JBM system(JBM has been installed using the default configuration), then
+ you can just copy the jms-ds.xml file over the one in
+ server/messaging/deploy and begin to put messages in the JBossMQ system
+ under the /queue/TestQueue. The messages will then be moved over to your
+ JBM queue /queue/A. Both of these queues exist in the stock versions of
+ JBM and JBossMQ.</para>
+ </section>
+
+ <programlisting>
+<?xml version="1.0" encoding="UTF-8"?>
+
+<connection-factories>
+
+ <!- ==================================================================== ->
+ <!- JMS Stuff ->
+ <!- ==================================================================== ->
+
+ <!- The JMS provider loader ->
+ <mbean code="org.jboss.jms.jndi.JMSProviderLoader"
+ name="jboss.messaging:service=JMSProviderLoader,name=JMSProvider">
+ <attribute name="ProviderName">DefaultJMSProvider</attribute>
+
+ <attribute name="ProviderAdapterClass">
+ org.jboss.jms.jndi.JNDIProviderAdapter
+ </attribute>
+ <!- The combined connection factory ->
+ <attribute name="FactoryRef">java:/XAConnectionFactory</attribute>
+ <!- The queue connection factory ->
+ <attribute name="QueueFactoryRef">java:/XAConnectionFactory</attribute>
+ <!- The topic factory ->
+
+ <attribute name="TopicFactoryRef">java:/XAConnectionFactory</attribute>
+ <!- Uncomment to use HAJNDI to access JMS
+ <attribute name="Properties">
+ java.naming.factory.initial=org.jnp.interfaces.NamingContextFactory
+ java.naming.factory.url.pkgs=org.jboss.naming:org.jnp.interfaces
+ java.naming.provider.url=localhost:1100
+ </attribute>
+ ->
+ </mbean>
+
+
+<mbean code="org.jboss.jms.jndi.JMSProviderLoader"
+ name="jboss.messaging:service=JMSProviderLoader,
+ name=MyRemoteJMSProvider">
+ <attribute name="ProviderName">RemoteXAConnectionFactory</attribute>
+ <attribute name="ProviderAdapterClass">org.jboss.jms.jndi.JNDIProviderAdapter</attribute>
+ <!- The combined connection factory ->
+
+ <attribute name="FactoryRef">XAConnectionFactory</attribute>
+ <!- The queue connection factory ->
+ <attribute name="QueueFactoryRef">XAConnectionFactory</attribute>
+ <!- The topic factory ->
+ <attribute name="TopicFactoryRef">XAConnectionFactory</attribute>
+ <attribute name="Properties">
+ java.naming.factory.initial=org.jnp.interfaces.NamingContextFactory
+ java.naming.factory.url.pkgs=org.jboss.naming:org.jnp.interfaces
+ java.naming.provider.url=192.168.0.199:1099
+ </attribute>
+
+</mbean>
+
+<mbean code="org.jboss.jms.server.bridge.BridgeService"
+ name="jboss.messaging:service=Bridge,name=TestBridge"
+ xmbean-dd="xmdesc/Bridge-xmbean.xml">
+ <depends optional-attribute-name="SourceProviderLoader">
+ jboss.messaging:service=JMSProviderLoader,
+ name=MyRemoteJMSProvider</depends>
+ <depends optional-attribute-name="TargetProviderLoader">
+ jboss.messaging:service=JMSProviderLoader,
+ name=JMSProvider</depends>
+ <attribute name="SourceDestinationLookup">/queue/testQueue</attribute>
+ <attribute name="TargetDestinationLookup">/queue/A</attribute>
+ <attribute name="QualityOfServiceMode">0</attribute>
+
+ <attribute name="MaxBatchSize">5</attribute>
+ <attribute name="MaxBatchTime">-1</attribute>
+ <attribute name="FailureRetryInterval">5000</attribute>
+ <attribute name="MaxRetries">-1</attribute>
+ <attribute name="AddMessageIDInHeader">false</attribute>
+</mbean>
+
+ <!- The server session pool for Message Driven Beans ->
+ <mbean code="org.jboss.jms.asf.ServerSessionPoolLoader"
+ name="jboss.messaging:service=ServerSessionPoolMBean,name=StdJMSPool">
+ <depends optional-attribute-name="XidFactory">jboss:service=XidFactory</depends>
+ <attribute name="PoolName">StdJMSPool</attribute>
+ <attribute name="PoolFactoryClass">
+ org.jboss.jms.asf.StdServerSessionPoolFactory
+ </attribute>
+ </mbean>
+
+ <!- JMS XA Resource adapter, use this to get transacted JMS in beans ->
+ <tx-connection-factory>
+ <jndi-name>JmsXA</jndi-name>
+ <xa-transaction/>
+ <rar-name>jms-ra.rar</rar-name>
+ <connection-definition>org.jboss.resource.adapter.jms.JmsConnectionFactory
+ </connection-definition>
+ <config-property name="SessionDefaultType" type="java.lang.String">javax.jms.Topic
+ </config-property>
+
+ <config-property name="JmsProviderAdapterJNDI" type="java.lang.String">
+ java:/DefaultJMSProvider</config-property>
+ <max-pool-size>20</max-pool-size>
+ <security-domain-and-application>JmsXARealm</security-domain-and-application>
+ </tx-connection-factory>
+
+</connection-factories>
+
+ </programlisting>
+
+ <para>You can also merge topics back and forth from JBM to JBossMQ, by
+ setting the subscription name and client id. You can see these arguments
+ in the JBM Bridge chapter.</para>
+ </section>-->
+</chapter>
Added: projects/docs/enterprise/5.0/JBoss_Messaging_1.4.3/en-US/Introduction.xml
===================================================================
--- projects/docs/enterprise/5.0/JBoss_Messaging_1.4.3/en-US/Introduction.xml (rev 0)
+++ projects/docs/enterprise/5.0/JBoss_Messaging_1.4.3/en-US/Introduction.xml 2009-09-09 03:35:49 UTC (rev 93305)
@@ -0,0 +1,197 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<chapter id="introduction">
+ <title>Introduction</title>
+
+ <para>
+ JBoss Messaging provides an open-source and standards-based messaging platform to bring enterprise-class messaging to the mass market.
+ </para>
+
+ <para>
+ JBoss Messaging implements a robust, high-performance messaging core designed to support Service-Oriented Architectures (SOAs), Enterprise Service Buses (ESBs), and other integration requirements regardless of the level of demand.
+ </para>
+
+ <para>
+ JBoss Messaging lets you distribute application load evenly across your cluster. It balances each node's CPU cycles with no single point of failure, providing a highly scalable and performant clustering implementation.
+ </para>
+
+ <para>
+ JBoss Messaging includes a Java Messaging Service (JMS) front-end so that messages are delivered in a standards-based format, and to enable support for other messaging protocols in the future.
+ </para>
+
+ <section id="features">
+ <title>JBoss Messaging Features</title>
+
+ <para>JBoss Messaging provides:</para>
+
+ <itemizedlist>
+ <listitem>
+ <para>
+ a Sun-certified implementation of Java Messaging Service 1.1, which currently works with the standard installation of JBoss Enterprise Application Platform version 4.2 or later.
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ a strong focus on performance, reliability and scalability with high throughput and low latency.
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ a foundation for JBoss ESB for SOA initiatives. (JBoss ESB uses JBoss Messaging as its default JMS provider.)
+ </para>
+ </listitem>
+ </itemizedlist>
+
+ <para>JBoss Messaging also includes the following features:</para>
+
+ <itemizedlist>
+ <listitem>
+ <para>publish-subscribe and point-to-point messaging models,</para>
+ </listitem>
+
+ <listitem>
+ <para>persistent and non-persistent messages,</para>
+ </listitem>
+
+ <listitem>
+ <para>guaranteed message delivery that ensures messages arrive once and only once where required,</para>
+ </listitem>
+
+ <listitem>
+ <para>a transactional and reliable interface that supports ACID semantics,</para>
+ </listitem>
+
+ <listitem>
+ <para>a customizable JAAS-based security framework,</para>
+ </listitem>
+
+ <listitem>
+ <para>complete integration with JBoss Transactions (previously Arjuna JTA) to support full transaction recovery,</para>
+ </listitem>
+
+ <listitem>
+ <para>an extensive JMX management interface,</para>
+ </listitem>
+
+ <listitem>
+ <para>support for most major databases, including Oracle, DB2, Sybase, Microsoft SQL Server, PostgreSQL and MySQL,</para>
+ </listitem>
+
+ <listitem>
+ <para>HTTP transport, for use with firewalls that allow only HTTP traffic,
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>SSL transport,</para>
+ </listitem>
+
+ <listitem>
+ <para>configurable DLQs (Dead Letter Queues) and Expiry Queues,</para>
+ </listitem>
+
+ <listitem>
+ <para>message statistics, which provide a rolling historical view of the messages delivered to queues and subscriptions,</para>
+ </listitem>
+
+ <listitem>
+ <para>the automatic paging of messages to storage, which lets you use very large queues that would be too large to fit entirely within system memory,</para>
+ </listitem>
+ </itemizedlist>
+
+ <para>JBoss Messaging also includes the following clustering features:</para>
+
+ <itemizedlist>
+ <listitem>
+ <formalpara>
+ <title>Fully-clustered queues and topics</title>
+ <para>
+ <emphasis>Logical</emphasis> queues and topics are distributed across the cluster. You can send or receive a queue or topic to or from any node on the cluster.
+ </para>
+ </formalpara>
+ </listitem>
+
+ <listitem>
+ <formalpara>
+ <title>Fully-clustered durable subscriptions</title>
+ <para>
+ A particular durable subscription can be accessed from any node of the cluster, letting you spread processing load from that subscription across the entire cluster.
+ </para>
+ </formalpara>
+ </listitem>
+
+ <listitem>
+ <formalpara>
+ <title>Fully-clustered temporary queues</title>
+ <para>
+ If a sent message includes the <literal>replyTo</literal> of a temporary queue, it can be returned on any node of the cluster.
+ </para>
+ </formalpara>
+ </listitem>
+
+ <listitem>
+ <formalpara>
+ <title>Intelligent message redistribution</title>
+ <para>
+ Messages are automatically moved between nodes of the cluster to take advantage of different consumer speeds on different nodes. This helps to prevent starvation or build-up of messages on a particular node.
+ </para>
+ </formalpara>
+ </listitem>
+
+ <listitem>
+ <formalpara>
+ <title>Message order protection</title>
+ <para>
+ Enable this to ensure that the order of messages produced by a producer is identical to the order of messages consumed by a consumer. This works even if message redistribution is active.
+ </para>
+ </formalpara>
+ </listitem>
+
+ <listitem>
+ <formalpara>
+ <title>Completely transparent failover</title>
+ <para>
+ When a server fails, your sessions continue exception-free on a new node. This is also completely configurable: if you do not want to implement this failover behaviour, you can disable it and fall back to exceptions being thrown and manually recreating connections on a new node.
+ </para>
+ </formalpara>
+ </listitem>
+
+ <listitem>
+ <formalpara>
+ <title>High availability and seamless failover</title>
+ <para>
+ If the node fails, you will automatically failover to a different node without losing any persistent messages and can seamlessly continue your session. <emphasis>Once and only once</emphasis> delivery of persistent messages is respected at all times.
+ </para>
+ </formalpara>
+ </listitem>
+
+ <listitem>
+ <formalpara>
+ <title>Message bridge</title>
+ <para>
+ JBoss Messaging contains a message bridge component, which lets you bridge messages between any two JMS 1.1 destinations. This lets you connect geographically separate clusters and form large, globally-distributed logical queues and topics.
+ </para>
+ </formalpara>
+ </listitem>
+ </itemizedlist>
+ </section>
+
+ <section id="compatibility">
+ <title>Compatibility with JBoss MQ</title>
+
+ <para>
+ JBoss MQ is the JMS implementation currently shipped with JBoss Application Server. Since JBoss Messaging is compatible with both JMS 1.1 and JMS 1.0.2b, the JMS code written against JBoss MQ will run with JBoss Messaging without any further changes.
+ </para>
+
+ <para>
+ JBoss Messaging has no wire format compatibility with JBoss MQ. It is therefore necessary to upgrade JBoss MQ clients with JBoss Messaging client JARs.
+ </para>
+
+ <important>
+ <para>
+ Although JBoss Messaging deployment descriptors are similar to JBoss MQ deployment descriptors, they are <emphasis>not identical</emphasis>, and will require some simple adjustments before they will work with JBoss Mesaging. The database data model is completely different, so JBoss Messaging should not be used with a JBoss MQ data schema, or vice-versa.
+ </para>
+ </important>
+ </section>
+</chapter>
\ No newline at end of file
Added: projects/docs/enterprise/5.0/JBoss_Messaging_1.4.3/en-US/JBoss_Messaging_User_Guide.ent
===================================================================
--- projects/docs/enterprise/5.0/JBoss_Messaging_1.4.3/en-US/JBoss_Messaging_User_Guide.ent (rev 0)
+++ projects/docs/enterprise/5.0/JBoss_Messaging_1.4.3/en-US/JBoss_Messaging_User_Guide.ent 2009-09-09 03:35:49 UTC (rev 93305)
@@ -0,0 +1,5 @@
+<!ENTITY PRODUCT "JBoss Enterprise Application Platform">
+<!ENTITY BOOKID "JBoss_Messaging_User_Guide">
+<!ENTITY YEAR "2008">
+<!ENTITY HOLDER "Red Hat, Inc.">
+
Added: projects/docs/enterprise/5.0/JBoss_Messaging_1.4.3/en-US/JBoss_Messaging_User_Guide.xml
===================================================================
--- projects/docs/enterprise/5.0/JBoss_Messaging_1.4.3/en-US/JBoss_Messaging_User_Guide.xml (rev 0)
+++ projects/docs/enterprise/5.0/JBoss_Messaging_1.4.3/en-US/JBoss_Messaging_User_Guide.xml 2009-09-09 03:35:49 UTC (rev 93305)
@@ -0,0 +1,19 @@
+<?xml version='1.0'?>
+<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [
+]>
+
+<book id="JBoss_Messaging_User_Guide">
+ <xi:include href="Book_Info.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
+ <xi:include href="About.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
+ <xi:include href="Introduction.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
+ <xi:include href="Getting_Started.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
+ <xi:include href="Installation.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
+ <xi:include href="Running_Examples.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
+ <xi:include href="Configuration.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
+ <xi:include href="C_Configuration.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
+ <xi:include href="Recovery_Configuration.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
+ <xi:include href="Bridge.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
+ <xi:include href="Revision_History.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
+ <index />
+</book>
+
Added: projects/docs/enterprise/5.0/JBoss_Messaging_1.4.3/en-US/Preface.xml
===================================================================
--- projects/docs/enterprise/5.0/JBoss_Messaging_1.4.3/en-US/Preface.xml (rev 0)
+++ projects/docs/enterprise/5.0/JBoss_Messaging_1.4.3/en-US/Preface.xml 2009-09-09 03:35:49 UTC (rev 93305)
@@ -0,0 +1,13 @@
+<?xml version='1.0'?>
+<!DOCTYPE preface PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [
+]>
+
+<preface id="Default_Book-Preface">
+ <title>Preface</title>
+ <xi:include href="Common_Content/Conventions.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
+ <xi:include href="Feedback.xml" xmlns:xi="http://www.w3.org/2001/XInclude">
+ <xi:fallback xmlns:xi="http://www.w3.org/2001/XInclude">
+ <xi:include href="Common_Content/Feedback.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
+ </xi:fallback>
+ </xi:include>
+</preface>
Added: projects/docs/enterprise/5.0/JBoss_Messaging_1.4.3/en-US/Recovery_Configuration.xml
===================================================================
--- projects/docs/enterprise/5.0/JBoss_Messaging_1.4.3/en-US/Recovery_Configuration.xml (rev 0)
+++ projects/docs/enterprise/5.0/JBoss_Messaging_1.4.3/en-US/Recovery_Configuration.xml 2009-09-09 03:35:49 UTC (rev 93305)
@@ -0,0 +1,54 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<chapter id="recovery">
+ <title>JBoss Messaging XA Recovery Configuration</title>
+
+ <para>
+ This section describes how to configure JBoss Transactions to handle XA recovery for JBoss Messaging resources in JBoss Application Server 4.x.
+ </para>
+
+ <para>
+ The JBoss Transactions Recovery Manager can be configured to continually poll for and recover JBoss Messaging XA resources. This provides a high level of transaction durability.
+ </para>
+ <para>
+ To enable JBoss Transactions Recovery Manager, add a line to <filename>$JBOSS_CONFIG/conf/jbossjta-properties.xml</filename>. The following code snippet includes the line required:
+ </para>
+ <programlisting>
+<properties depends="arjuna" name="jta">
+ <!--
+ Support subtransactions in the JTA layer?
+ Default is NO.
+ -->
+ <property name="com.arjuna.ats.jta.supportSubtransactions" value="NO"/>
+ <property name="com.arjuna.ats.jta.jtaTMImplementation"
+ value="com.arjuna.ats.internal.jta.transaction.arjunacore.TransactionManagerImple"/>
+ <property name="com.arjuna.ats.jta.jtaUTImplementation"
+ value="com.arjuna.ats.internal.jta.transaction.arjunacore.UserTransactionImple"/>
+ <!--
+ *** Add this line to enable recovery for JMS resources using DefaultJMSProvider ***
+ -->
+ <property name="com.arjuna.ats.jta.recovery.XAResourceRecovery.JBMESSAGING1"
+ value="org.jboss.jms.server.recovery.MessagingXAResourceRecovery;java:/DefaultJMSProvider"/>
+
+</properties>
+ </programlisting>
+
+ <para>
+ Here, the Recovery Manager attempts to recover JMS resources via the JMS Provider Loader, <literal>DefaultJMSProvider</literal>.
+ </para>
+
+ <para>
+ <literal>DefaultJMSProvider</literal> ships with JBoss Application Server. It is defined in <filename>jms-ds.xml</filename> (or, in a clustered environment, <filename>hajndi-jms-ds.xml</filename>). To perform recovery with a different JMS provider loader (for example, one that corresponds with a remote JMS Provider), add another line to the properties file and specify your remote provider instead of <literal>DefaultJMSProvider</literal>. Your provider's name should be listed in its managed bean configuration file.
+ </para>
+
+ <para>
+ Each provider requires a unique name, for example, <literal>com.arjuna.ats.jta.recovery.XAResourceRecovery.JBMESSAGING1</literal>, <literal>com.arjuna.ats.jta.recovery.XAResourceRecovery.JBMESSAGING2</literal>, etc.
+ </para>
+
+ <para>
+ Recovery should work with any JMS provider that implements recoverable XAResources (that is, it properly implements <literal>XAResource.recover()</literal>).
+ </para>
+
+ <para>
+ For the Recovery Manager to recover from any node of the cluster, you must add a line in the configuration for every node of the cluster.
+ </para>
+</chapter>
\ No newline at end of file
Added: projects/docs/enterprise/5.0/JBoss_Messaging_1.4.3/en-US/Revision_History.xml
===================================================================
--- projects/docs/enterprise/5.0/JBoss_Messaging_1.4.3/en-US/Revision_History.xml (rev 0)
+++ projects/docs/enterprise/5.0/JBoss_Messaging_1.4.3/en-US/Revision_History.xml 2009-09-09 03:35:49 UTC (rev 93305)
@@ -0,0 +1,26 @@
+<?xml version='1.0'?>
+<!DOCTYPE appendix PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [
+]>
+
+<appendix id="appe-Publican-Revision_History">
+ <title>Revision History</title>
+ <simpara>
+ <revhistory>
+ <revision>
+ <revnumber>1.0</revnumber>
+ <date></date>
+ <author>
+ <firstname></firstname>
+ <surname></surname>
+ <email></email>
+ </author>
+ <revdescription>
+ <simplelist>
+ <member></member>
+ </simplelist>
+ </revdescription>
+ </revision>
+ </revhistory>
+ </simpara>
+</appendix>
+
Added: projects/docs/enterprise/5.0/JBoss_Messaging_1.4.3/en-US/Running_Examples.xml
===================================================================
--- projects/docs/enterprise/5.0/JBoss_Messaging_1.4.3/en-US/Running_Examples.xml (rev 0)
+++ projects/docs/enterprise/5.0/JBoss_Messaging_1.4.3/en-US/Running_Examples.xml 2009-09-09 03:35:49 UTC (rev 93305)
@@ -0,0 +1,138 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<chapter id="examples">
+ <title>Running the Examples</title>
+
+ <para>
+ The <filename>docs/examples</filename> directory contains a set of examples that demonstrate the various aspects of JBoss Messaging at work.
+ </para>
+
+ <para>
+ Before you run these examples, deploy the <literal>example-destinations</literal> located under <filename>/docs/examples/destinations</filename>.
+ </para>
+
+ <para>
+ The following examples are included with JBoss Messaging:
+ </para>
+
+ <variablelist>
+ <varlistentry>
+ <term><filename>docs/example/queue</filename></term>
+ <listitem>
+ <para>
+ This example shows a simple send and receive to a remote queue using a JMS client.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><filename>docs/example/topic</filename></term>
+ <listitem>
+ <para>
+ This example shows a simple send and receive to a remote topic using a JMS client.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><filename>docs/example/mdb</filename></term>
+ <listitem>
+ <para>
+ This example demonstrates the use of an Enterprise JavaBean 2.1 MDB with JBoss Messaging.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><filename>docs/example/ejb3mdb</filename></term>
+ <listitem>
+ <para>
+ This example demonstrates the use of an Enterprise JavaBean 3.0 MDB with JBoss Messaging.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><filename>docs/example/stateless</filename></term>
+ <listitem>
+ <para>
+ This example demonstrates an Enterprise JavaBean 2.1 stateless session bean interacting with JBoss Messaging.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><filename>docs/example/mdb-failure</filename></term>
+ <listitem>
+ <para>
+ This example demonstrates rollback and redelivery within an Enterprise JavaBean 2.1.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><filename>docs/example/secure-socket</filename></term>
+ <listitem>
+ <para>
+ This example demonstrates a JMS client interacting with a JBoss Messaging server via SSL-encrypted transport.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><filename>docs/example/http</filename></term>
+ <listitem>
+ <para>
+ This example demonstrates a JMS client interacting with a JBoss Messaging server by tunneling traffic via HTTP.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><filename>docs/example/web-service</filename></term>
+ <listitem>
+ <para>
+ This example demonstrates the JBoss Webservice interacting with JBoss Messaging.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><filename>docs/example/distributed-queue</filename></term>
+ <listitem>
+ <para>
+ This example demonstrates a JMS client interacting with a JBoss Messaging distributed queue. Two instances of JBoss AS are required to run this example.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><filename>docs/example/distributed-topic</filename></term>
+ <listitem>
+ <para>
+ This example demonstrates a JMS client interacting with a JBoss Messaging distributed topic. Two instances of JBoss AS are required to run this example.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><filename>docs/example/stateless-clustered</filename></term>
+ <listitem>
+ <para>
+ This example demonstrates a JMS client interacting with a clustered Enterprise JavaBean 2.1 stateless session bean, which interacts in turn with JBoss Messaging. This example uses HAJNDI to locate the connection factory.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><filename>docs/example/bridge</filename></term>
+ <listitem>
+ <para>
+ This example demonstrates the use of a message bridge. It deploys a message bridge within JBoss AS, which moves messages from a source to a target queue.
+ </para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+
+ <para>We highly recommend that you familiarize yourself with the examples.</para>
+
+ <para>Remember: you must start your server or servers before you run the examples.</para>
+
+ <para>
+ The non-clustered examples expect an instance of JBoss AS to be running with all default settings.
+ </para>
+
+ <para>
+ The clustered examples expect that two instances of JBoss AS will be running with ports settings of <literal>ports-01</literal> and <literal>ports-02</literal>.
+ </para>
+
+ <para>
+ You can override the default ports of an example by editing <filename>jndi.properties</filename> in that example's root directory.</para>
+</chapter>
More information about the jboss-cvs-commits
mailing list