[jboss-cvs] JBoss Messaging SVN: r6642 - projects/eap-docs/tags/JBoss_Messaging_User_Guide_EAP_5_0_0/en-US.
jboss-cvs-commits at lists.jboss.org
jboss-cvs-commits at lists.jboss.org
Thu Apr 30 23:05:48 EDT 2009
Author: laubai
Date: 2009-04-30 23:05:47 -0400 (Thu, 30 Apr 2009)
New Revision: 6642
Modified:
projects/eap-docs/tags/JBoss_Messaging_User_Guide_EAP_5_0_0/en-US/bridge.xml
projects/eap-docs/tags/JBoss_Messaging_User_Guide_EAP_5_0_0/en-US/c_configuration.xml
projects/eap-docs/tags/JBoss_Messaging_User_Guide_EAP_5_0_0/en-US/configuration.xml
projects/eap-docs/tags/JBoss_Messaging_User_Guide_EAP_5_0_0/en-US/installation.xml
projects/eap-docs/tags/JBoss_Messaging_User_Guide_EAP_5_0_0/en-US/introduction.xml
projects/eap-docs/tags/JBoss_Messaging_User_Guide_EAP_5_0_0/en-US/recovery_config.xml
projects/eap-docs/tags/JBoss_Messaging_User_Guide_EAP_5_0_0/en-US/runningexamples.xml
Log:
Updated and edited EAP 5.0.0 book
Modified: projects/eap-docs/tags/JBoss_Messaging_User_Guide_EAP_5_0_0/en-US/bridge.xml
===================================================================
--- projects/eap-docs/tags/JBoss_Messaging_User_Guide_EAP_5_0_0/en-US/bridge.xml 2009-04-30 17:22:52 UTC (rev 6641)
+++ projects/eap-docs/tags/JBoss_Messaging_User_Guide_EAP_5_0_0/en-US/bridge.xml 2009-05-01 03:05:47 UTC (rev 6642)
@@ -13,68 +13,69 @@
queue or topic, and send them to a target queue or topic, typically on a
different server.</para>
- <para>The source and target servers do not have to be in the same cluster
+ <!--<para>The source and target servers do not have to be in the same cluster
which makes bridging suitable for reliably sending messages from one
cluster to another, for instance across a WAN, and where the connection
- may be unreliable.</para>
+ may be unreliable.</para>-->
- <para>A bridge is deployed inside a JBoss AS instance. The instance can be
- the same instance as either the source or target server. Or could be on a
- third, separate JBoss AS instance.</para>
+ <para>The source and target servers need not be in the same cluster, which makes bridging suitable for reliably 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 inside a JBoss AS instance. The instance can be the same instance as either the source or target server. Or could be on a third, separate JBoss AS instance.</para>-->
+
+ <para>A bridge is deployed within an instance of JBoss AS. This
+ instance can be the same as either the source or the target server,
+ or on a third, separate JBoss AS instance.</para>
+
<para>A bridge is deployed as an MBean inside JBoss AS. Deployment is
trivial - just drop the MBean descriptor into the deploy directory of a
JBoss configuration which contains JBoss Messaging.</para>
<para>An example in docs/example/bridge demonstrates a simple bridge being
deployed in JBoss AS, and moving messages from the source to the target
- destination</para>
+ destination.</para>
- <para>The bridge can also be used to bridge messages from other non JBoss
+ <para>The bridge can also be used to bridge messages from other non-JBoss
Messaging JMS servers, as long as they are JMS 1.1 compliant.</para>
- <para>The bridge has built in resilience to failure so if the source or
- target server connetion is lost, e.g. due to network failure, the bridge
- will retry connecting to the source and/or target until they come back
- online. When it comes back online it will resume operation as
- normal.</para>
+ <!--<para>The bridge has built in resilience to failure so if the source or target server connection is lost, e.g. due to network failure, the bridge will retry connecting to the source and/or target until they come back online. When it comes back online it will resume operation as
+ normal.</para>-->
+
+ <para>The bridge has inbuilt resilience to failure, so if the source or target server connection is lost, for example, through network failure, the bridge will keep attempting to connect to the source and/or target. When the server comes back online, the bridge will resume normal operation.</para>
<para>The bridge can be configured with an optional JMS selector, so it
- will only consume messages matching that JMS selector</para>
+ will only consume messages matching that JMS selector.</para>
- <para>It can be configured to consume from a queue or a topic. When it
- consumes from a topic it can be configured to consume using a non durable
- or durable subscription</para>
+ <!--<para>It can be configured to consume from a queue or a topic. When it
+ consumes from a topic it can be configured to consume using a non-durable
+ or durable subscription</para>-->
+ <para>The bridge can also be configured to consume from a queue or topic. When it consumes from a topic, it can be configured to consume using a durable or non-durable subscription.</para>
+
<para>The bridge can be configured to bridge messages with one of three
- levels of quality of service, they are:</para>
+ levels of quality of service. These levels are:</para>
<itemizedlist>
<listitem>
<para>QOS_AT_MOST_ONCE</para>
- <para>With this QoS mode messages will reach the destination from
- the source at most once. The messages are consumed from the source
- and acknowledged before sending to the destination. Therefore there
- is a possibility that if failure occurs between removing them from
- the source and them arriving at the destination they could be lost.
- Hence delivery will occur at most once. This mode is avilable for
- both persistent and non persistent messages.</para>
+ <!--<para>With this QoS mode messages will reach the destination from the source at most once. The messages are consumed from the source and acknowledged before sending to the destination. Therefore there is a possibility that if failure occurs between removing them from the source and them arriving at the destination they could be lost. Hence delivery will occur at most once. This mode is avilable for both persistent and non persistent messages.</para>-->
+ <para>With this QoS mode, messages will reach the destination from the source at most once. Therefore, there is a possibility that if a failure occurs between a message's removal from the source and its arrival at the destination, it could be lost. This mode is available for both persistent and non-persistent messages.</para>
</listitem>
<listitem>
<para>QOS_DUPLICATES_OK</para>
- <para>With this QoS mode, the messages are consumed from the source
+ <!--<para>With this QoS mode, the messages are consumed from the source
and then acknowledged after they have been successfully sent to the
destination. Therefore there is a possibility that if failure occurs
after sending to the destination but before acknowledging them, they
could be sent again when the system recovers. I.e. the destination
might receive duplicates after a failure. This mode is available for
- both persistent and non persistent messages.</para>
+ both persistent and non persistent messages.</para>-->
+ <para>With this QoS mode, the messages are consumed from the source and acknowledged after they are successfully sent to the destination. Therefore, there is a possibility that if a failure occurs after a message's successful arrival but before its acknowledgement, the message could be sent again when the system recovers, and the destination may receive duplicate messages after a failure. This mode is available for both persistent and non-persistent messages.</para>
</listitem>
<listitem>
<para>QOS_ONCE_AND_ONLY_ONCE</para>
- <para>This QoS mode ensures messages will reach the destination from
+ <!--<para>This QoS mode ensures messages will reach the destination from
the source once and only once. (Sometimes this mode is known as
"exactly once"). If both the source and the destination are on the
same JBoss Messaging server instance then this can be achieved by
@@ -89,9 +90,11 @@
is only available for persistent messages. This is likely to be the
slowest mode since it requires logging on both the transaction
manager and resource side for recovery. If you require this level of
- QoS, please be sure to enable XA recovery with JBoss Transactions.</para>
+ QoS, please be sure to enable XA recovery with JBoss Transactions.</para>-->
+ <para>Also known as Exactly Once mode. This QoS mode ensures that messages will reach the destination from the source once and only once. If both source and destination are on the same server instance, messages are sent and acknowledged in the same local transaction. If the source and destination are on different servers, sending and consuming sessions are enlisted in a Java Transactions API (JTA) transaction. JTA transactions are controlled by the JBoss Transactions JTA implementation, a fully recovering transaction manager which provides a high degree of durability. If JTA is required, both of the supplied connection factories need to be XAConnectionFactory implementations. This mode is likely to be the slowest, since it requires logging on both the transaction manager and resource sides for recovery. If you require this level of QoS, please be sure to enable XA recovery with JBoss Transactions.</para>
<note>
- <para>For a specific application it may possible to provide once and only once semantics without using the QOS_ONCE_AND_ONLY_ONCE QoS level. This can be done by using the QOS_DUPLICATES_OK mode and then checking for duplicates at the destination and discarding them. This may be possible to implement on the application level by maintaining a cache of received message ids on disk and comparing received messages to them. The cache would only be valid for a certain period of time so this approach is not as watertight as using QOS_ONCE_AND_ONLY_ONCE but may be a good choice depending on your specific application. </para>
+ <!--<para>For a specific application it may possible to provide once and only once semantics without using the QOS_ONCE_AND_ONLY_ONCE QoS level. This can be done by using the QOS_DUPLICATES_OK mode and then checking for duplicates at the destination and discarding them. This may be possible to implement on the application level by maintaining a cache of received message ids on disk and comparing received messages to them. The cache would only be valid for a certain period of time so this approach is not as watertight as using QOS_ONCE_AND_ONLY_ONCE but may be a good choice depending on your specific application. </para>-->
+ <para>For a specific application, it may be possible to provide once-and-only-once semantics without using the QOS_ONCE_AND_ONLY_ONCE QoS level. This can be done by using QOS_DUPLICATES_OK mode and then checking for and discarding duplicates at the destination. It may be possible to implement this on the application level by maintaining a cache of received message IDs on disk and comparing received messages to them. The cache would only be valid for a certain period of time, so this approach is not as effective as using QOS_ONCE_AND_ONLY_ONCE, but could be a good choice depending on your specific application.</para>
</note>
</listitem>
</itemizedlist>
@@ -100,107 +103,107 @@
<section id="bridge.deployment">
<title>Bridge deployment</title>
- <para>A message bridge is easily deployed by dropping the MBean descriptor
+ <!--<para>A message bridge is easily deployed by dropping the MBean descriptor
in the deploy directory of your JBoss AS installation which contains JBoss
- Messaging</para>
+ Messaging</para>-->
+ <para>A message bridge is easily deployed by dropping the MBean descriptor into the deploy directory of the JBoss AS installation that contains JBoss Messaging.</para>
</section>
<section id="bridge.configuration">
<title>Bridge configuration</title>
<para>In this section we describe how to configure the message
- bridge</para>
+ bridge.</para>
<para>Here is an example of a message bridge configuration, with all the
attributes shown. Note that some are commented out for this configuration,
- since it is not appropriate to specify them all at once. Which ones are
- specified depends on the configuration you want.</para>
+ since it is not appropriate to specify them all at once. Your configuration depends upon the attributes specified.</para>
<programlisting>
- <mbean code="org.jboss.jms.server.bridge.BridgeService"
- name="jboss.messaging:service=Bridge,name=TestBridge"
- xmbean-dd="xmdesc/Bridge-xmbean.xml">
+<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 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 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 source destination -->
+<attribute name="SourceDestinationLookup">/queue/A</attribute>
- <!-- The JNDI lookup for the target destination -->
- <attribute name="TargetDestinationLookup">/queue/B</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 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 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 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>
- -->
+<!-- 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>
+<!-- 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>
- -->
+<!-- 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 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>
+<!-- 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 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>
- -->
+<!-- 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 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>
+<!-- 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>
+<!-- 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>
+</mbean>
</programlisting>
- <para>We will now discuss each attribute</para>
+ <para>We will now discuss each attribute.</para>
<section id="bridge.configuration.sourceproviderloader">
<title>SourceProviderLoader</title>
<para>This is the object name of the JMSProviderLoader MBean that the
- bridge will use to lookup the source connection factory and source
+ bridge will use to look up the source connection factory and source
destination.</para>
<para>By default JBoss AS ships with one JMSProviderLoader, deployed in
@@ -209,24 +212,23 @@
<filename>hajndi-jms-ds.xml</filename> in a clustered
configuration)</para>
- <para>If your source destination is on different servers or even
- correspond to a different, non JBoss JMS provider, then you can deploy
+ <para>If your source destination is on a different server or even
+ corresponds to a different, non-JBoss JMS provider, then you can deploy
another JMSProviderLoader MBean instance which references the remote JMS
- provider, and reference that from this attribute. The bridge would then
- use that remote JMS provider to contact the source destination</para>
+ provider, and reference that MBean from this attribute. The bridge would then
+ use that remote JMS provider to contact the source destination.</para>
- <para>Note that if you are using a remote non JBoss Messaging source or
- target and you wish once and only once delivery then that remote JMS
+ <para>Note that if you are using a remote non-JBoss Messaging source or
+ target and you want once and only once delivery, then that remote JMS
provider must provide a fully functional JMS XA resource implementation
- that works remotely from the server - it is known that some non JBoss
- JMS providers do not provide such a resource</para>
+ that works remotely from the server. Some non-JBoss JMS providers do not provide this.</para>
</section>
<section id="bridge.configuration.targetproviderloader">
<title>TargetProviderLoader</title>
<para>This is the object name of the JMSProviderLoader MBean that the
- bridge will use to lookup the target connection factory and target
+ bridge will use to look up the target connection factory and target
destination.</para>
<para>By default JBoss AS ships with one JMSProviderLoader, deployed in
@@ -236,68 +238,67 @@
configuration)</para>
<para>If your target destination is on a different server or even
- correspond to a different, non JBoss JMS provider, then you can deploy
+ corresponds to a different, non-JBoss JMS provider, then you can deploy
another JMSProviderLoader MBean instance which references the remote JMS
provider, and reference that from this attribute. The bridge would then
- use that remote JMS provider to contact the target destination</para>
+ use that remote JMS provider to contact the target destination.</para>
<para>Note that if you are using a remote non JBoss Messaging source or
- target and you wish once and only once delivery then that remote JMS
+ target and you want once and only once delivery, then that remote JMS
provider must provide a fully functional JMS XA resource implementation
- that works remotely from the server - it is known that some non JBoss
- JMS providers do not provide such a resource</para>
+ that works remotely from the server. Some non-JBoss JMS providers do not provide this.</para>
</section>
<section id="bridge.configuration.sourcedestinationlookup">
<title>SourceDestinationLookup</title>
<para>This is the full JNDI lookup for the source destination using the
- SourceProviderLoader</para>
+ SourceProviderLoader.</para>
- <para>An example would be /queue/mySourceQueue</para>
+ <para>An example would be /queue/mySourceQueue.</para>
</section>
<section id="bridge.configuration.targetdestinationlookup">
<title>TargetDestinationLookup</title>
<para>This is the full JNDI lookup for the target destination using the
- TargetProviderLoader</para>
+ TargetProviderLoader.</para>
- <para>An example would be /topic/myTargetTopic</para>
+ <para>An example would be /topic/myTargetTopic.</para>
</section>
<section id="bridge.configuration.sourceusername">
<title>SourceUsername</title>
<para>This optional attribute is for when you need to specify the
- username for creating the source connection</para>
+ username for creating the source connection.</para>
</section>
<section id="bridge.configuration.sourcepassword">
<title>SourcePassword</title>
<para>This optional attribute is for when you need to specify the
- password for creating the source connection</para>
+ password for creating the source connection.</para>
</section>
<section id="bridge.configuration.targetusername">
<title>TargetUsername</title>
<para>This optional attribute is for when you need to specify the
- username for creating the target connection</para>
+ username for creating the target connection.</para>
</section>
<section id="bridge.configuration.targetpassword">
<title>TargetPassword</title>
<para>This optional attribute is for when you need to specify the
- password for creating the target connection</para>
+ password for creating the target connection.</para>
</section>
<section id="bridge.configuration.qualityofservicemode">
<title>QualityOfServiceMode</title>
- <para>This integer represents the desired quality of service mode</para>
+ <para>This integer represents the desired quality of service mode.</para>
<para>Possible values are: <itemizedlist>
<listitem>
@@ -323,9 +324,9 @@
<para>This optional attribute can contain a JMS selector expression used
for consuming messages from the source destination. Only messages that
match the selector expression will be bridged from the source to the
- target destination</para>
+ target destination.</para>
- <para>Please note it is always more performant to apply selectors on
+ <para>Please note that it is always more performant to apply selectors on
source topic subscriptions to source queue consumers.</para>
<para>The selector expression must follow the JMS selector syntax
@@ -346,7 +347,7 @@
<para>This attribute specifies the maximum number of milliseconds to
wait before sending a batch to target, even if the number of messages
- consumed has not reached MaxBatchSize. It's value must can be -1 to
+ consumed has not reached MaxBatchSize. Its value can be -1 to
represent 'wait forever', or >=1 to specify an actual time.</para>
</section>
@@ -354,25 +355,25 @@
<title>SubName</title>
<para>If the source destination represents a topic, and you want to
- consume from the topic using a durable subscription then this attribute
- represents the durable subscription name</para>
+ consume from the topic using a durable subscription, then this attribute
+ represents the durable subscription name.</para>
</section>
<section id="bridge.configuration.clientid">
<title>ClientID</title>
<para>If the source destination represents a topic, and you want to
- consume from the topic using a durable subscription then this attribute
- represents the the JMS client ID to use when creating/looking up the
- durable subscription</para>
+ consume from the topic using a durable subscription, then this attribute
+ represents the JMS client ID to use when creating/looking up the
+ durable subscription.</para>
</section>
<section id="bridge.configuration.failureretryinterval">
<title>FailureRetryInterval</title>
- <para>This represents the amount of time in ms to wait between trying to
+ <para>This represents the amount of time in ms to wait between attempts to
recreate connections to the source or target servers when the bridge has
- detected they have failed</para>
+ detected connection failure.</para>
</section>
<section id="bridge.configuration.maxretries">
@@ -380,8 +381,7 @@
<para>This represents the number of times to attempt to recreate
connections to the source or target servers when the bridge has detected
- they have failed. The bridge will give up after trying this number of
- times. -1 represents 'try forever'</para>
+ connection failure. The bridge will stop attempting to reconnect after trying this number of times. -1 represents 'try forever'.</para>
</section>
<section id="bridge.configuration.addmessageidinheader">
@@ -390,8 +390,7 @@
<para>If true, then the original message's message id will appended in
the message sent to the destination in the header
JBossMessage.JBOSS_MESSAGING_BRIDGE_MESSAGE_ID_LIST. If the message is
- bridged more than once each message-id will be appended. This enables a
- distributed request-response pattern to be used</para>
+ bridged more than once, each message-id will be appended, so that a destributed request-response pattern may be used.</para>
</section>
</section>
</chapter>
\ No newline at end of file
Modified: projects/eap-docs/tags/JBoss_Messaging_User_Guide_EAP_5_0_0/en-US/c_configuration.xml
===================================================================
--- projects/eap-docs/tags/JBoss_Messaging_User_Guide_EAP_5_0_0/en-US/c_configuration.xml 2009-04-30 17:22:52 UTC (rev 6641)
+++ projects/eap-docs/tags/JBoss_Messaging_User_Guide_EAP_5_0_0/en-US/c_configuration.xml 2009-05-01 03:05:47 UTC (rev 6642)
@@ -5,16 +5,12 @@
<title>JBoss Messaging Clustering Notes</title>
<section id="c_conf.serverpeerid">
- <title>Unique server peer id</title>
+ <title>Unique server peer ID</title>
- <para>JBoss Messaging clustering should work out of the box in most cases
- with no configuration changes. It is however crucial that every node is
- assigned a unique server id, as specified in the installation
- guide.</para>
+ <para>JBoss Messaging clustering should work straight out of the box in most cases, with no configuration changes. It is, however, crucial that every node is assigned a unique server ID, as specified in the installation guide.</para>
- <para>Every node deployed must have a unique id, including those in a
- particular LAN cluster, and also those only linked by mesage
- bridges.</para>
+ <para>Every node deployed must have a unique ID, including those in a
+ particular LAN cluster, and also those only linked by message bridges.</para>
</section>
<section id="c_conf.clustereddests">
@@ -22,27 +18,25 @@
<para>JBoss Messaging clusters 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 designate that a particular destination is
- clustered simply set the clustered attribute in the destination deployment
+ consumable on other nodes. To designate a particular destination as
+ clustered, simply set the clustered attribute in the destination deployment
descriptor to true.</para>
-
+
<para>JBoss Messaging balances messages between nodes, catering for faster
or slower consumers to efficiently balance processing load across the
cluster.</para>
<para>If you do not want message redistribution between nodes, but still
- want to retain the other charactereristics of clustered destinations. You
- can do this by not specifying the attribute
- ClusterPullConnectionFactoryName on the server peer</para>
+ want to retain the other charactereristics of clustered destinations, you can leave the ClusterPullConnectionFactoryName attribute on the server peer unspecified.</para>
</section>
<section id="c_conf.clustereddursubs">
<title>Clustered durable subs</title>
<para>JBoss Messaging durable subscriptions can also be clustered. This
- means multiple subscribers can consume from the same durable subscription
+ means that multiple subscribers can consume from the same durable subscription,
from different nodes of the cluster. A durable subscription will be
- clustered if it's topic is clustered</para>
+ clustered if its topic is clustered.</para>
</section>
<section id="c_conf.clusteredtempdest">
@@ -50,15 +44,15 @@
<para>JBoss Messaging also supports clustered temporary topics and queues.
All temporary topics and queues will be clustered if the post office is
- clustered</para>
+ clustered.</para>
</section>
<section id="c_conf.nonclusteredserver">
<title>Non clustered servers</title>
<para>If you don't want your nodes to participate in a cluster, or only
- have one non clustered server you can set the clustered attribute on the
- postoffice to false</para>
+ have one non-clustered server, you can set the clustered attribute on the
+ postoffice to false.</para>
</section>
<section id="c_conf.orderingincluster">
@@ -67,9 +61,7 @@
<para>If you wish to apply strict JMS ordering to messages, such that a
particular JMS consumer consumes messages in the same order as they were
produced by a particular producer, you can set the DefaultPreserveOrdering
- attribute in the server peer to true. By default this is false. The
- sideeffect of setting this to true is that messages cannot be distributed
- as freely around the cluster</para>
+ attribute in the server peer to true. This is false by default. Setting it to true means that messages cannot be distributed as freely around the cluster.</para>
</section>
<section id="c_conf.idempotentops">
@@ -77,39 +69,33 @@
<para>If the call to send a persistent message to a persistent destination
returns successfully with no exception, then you can be sure that the
- message was persisted. However if the call doesn't return successfully
- e.g. if an exception is thrown, then you *can't be sure the message wasn't
- persisted*. Since the failure might have occurred after persisting the
- message but before writing the response to the caller. This is a common
- attribute of any RPC type call: You can't tell by the call not returning
- that the call didn't actually succeed. Whether it's a web services call,
- an HTTP get request, an ejb invocation the same applies. The trick is to
- code your application so your operations are *idempotent* i.e. they can be
- repeated without getting the system into an inconsistent state. With a
- messaging system you can do this on the application level, by checking for
- duplicate messages, and discarding them if they arrive. Duplicate checking
- is a very powerful technique that can remove the need for XA transactions
- in many cases.</para>
-
- <para>In the clustered case. JBM is by default configured to detect
- duplicate automatically messages by default</para>
+ message was persisted. However, if the call does not return successfully (for example, if an exception is thrown), then you cannot be sure that the message was not persisted, since the failure might have occurred after persisting the
+ message, but before writing the response to the caller. This is a common
+ attribute of any RPC type call: you cannot assume, by the call not returning,
+ that the call did not actually succeed. The same applies whether it is a web services call, an HTTP get request, or an ejb invocation. The trick is to
+ code your application so that your operations are idempotent: that they can be
+ repeated without causing the system to become inconsistent. With a
+ messaging system, you can do this on the application level by checking for
+ duplicate messages and discarding duplicates if the messages arrive. Duplicate checking is a very powerful technique that can remove the need for XA transactions in many cases.</para>
+
+ <para>In the clustered case, JBM is configured by default to detect duplicate messages automatically.</para>
</section>
<section id="c_conf.clusteredcfs">
<title>Clustered connection factories</title>
<para>If the supportsLoadBalancing attribute of the connection factory is
- set to true then consecutive create connection attempts will round robin
- between available servers. The first node to try is chosen randomly</para>
+ set to true then consecutive attempts to create a connection will round robin
+ between available servers. The first node to try is chosen randomly.</para>
<para>If the supportsFailover attribute of the connection factory is set
to true then automatic failover is enabled. This will automatically
failover from one server to another, transparently to the user, in case of
failure.</para>
- <para>If automatic failover is not required or you wish to do manual
- failover (JBoss MQ style) this can be set to false, and you can supply a
- standard JMS ExceptionListener on the connection which will be called in
+ <para>If automatic failover is not required, or you wish to do manual
+ failover (JBoss MQ style), this can be set to false and you can supply a
+ standard JMS ExceptionListener on the connection, which will be called in
case of connection failure. You would then need to manually close the
connection, lookup a new connection factory from HA JNDI and recreate the
connection.</para>
Modified: projects/eap-docs/tags/JBoss_Messaging_User_Guide_EAP_5_0_0/en-US/configuration.xml
===================================================================
--- projects/eap-docs/tags/JBoss_Messaging_User_Guide_EAP_5_0_0/en-US/configuration.xml 2009-04-30 17:22:52 UTC (rev 6641)
+++ projects/eap-docs/tags/JBoss_Messaging_User_Guide_EAP_5_0_0/en-US/configuration.xml 2009-05-01 03:05:47 UTC (rev 6642)
@@ -22,7 +22,7 @@
<filename>messaging-service.xml</filename>,
<filename>remoting-bisocket-service.xml</filename>,
<filename>xxx-persistence-service.xml</filename> (where xx is the name of
- your databse) , <filename>connection-factories-service.xml</filename> and
+ your databse), <filename>connection-factories-service.xml</filename>, and
<filename>destinations-service.xml</filename>.</para>
<para>The AOP client-side and server-side interceptor stacks are configured
@@ -37,100 +37,101 @@
<title>Configuring the ServerPeer</title>
<para>The Server Peer is the heart of the JBoss Messaging JMS facade. The
- server's configuration, resides in
+ server's configuration resides in the
<filename>messaging-service.xml</filename> configuration file.</para>
- <para>All JBoss Messaging services are rooted at the server peer</para>
+ <para>All JBoss Messaging services are rooted at the server peer.</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>
+ example.</para>
- <programlisting> <!-- ServerPeer MBean configuration
- ============================== -->
- <mbean code="org.jboss.jms.server.ServerPeer"
- name="jboss.messaging:service=ServerPeer"
- xmbean-dd="xmdesc/ServerPeer-xmbean.xml">
+ <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 -->
+<!-- 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="ServerPeerID">0</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>
- -->
+<!-- The default JNDI context to use for queues when they are deployed without specifying one -->
- <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>
+<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">
@@ -142,9 +143,9 @@
<section id="conf.serverpeer.attributes.serverpeerid">
<title>ServerPeerID</title>
- <para>The unique id of the server peer. Every node you deploy MUST
- have a unique id. This applies whether the different nodes form a
- cluster, or are only linked via a message bridge. The id must be a
+ <para>The unique ID of the server peer. Every node you deploy MUST
+ have a unique ID. This applies whether the different nodes form a
+ cluster, or are only linked via a message bridge. The ID must be a
valid integer.</para>
</section>
@@ -158,7 +159,7 @@
<section id="conf.serverpeer.attributes.defaultopicjndicontext">
<title>DefaultTopicJNDIContext</title>
- <para>The default JNDI context to use when binding topics.wa Defaults
+ <para>The default JNDI context to use when binding topics. Defaults
to /topic.</para>
</section>
@@ -174,12 +175,12 @@
<section id="conf.serverpeer.attributes.defaultdlq">
<title>DefaultDLQ</title>
- <para>This is the name of the default DLQ (Dead Letter Queue) the
+ <para>This is the name of the default DLQ (Dead Letter Queue) that the
server peer will use for destinations. The DLQ can be overridden on a
per destination basis - see the destination MBean configuration for
more details. A DLQ is a special destination where messages are sent
when the server has attempted to deliver them unsuccessfully more than
- a certain number of times. If the DLQ is not specified at all then the
+ a certain number of times. If the DLQ is not specified at all, the
message will be removed after the maximum number of delivery attempts.
The maximum number of delivery attempts can be specified using the
attribute DefaultMaxDeliveryAttempts for a global default or
@@ -202,22 +203,21 @@
<section id="conf.serverpeer.attributes.defaultexpiryqueue">
<title>DefaultExpiryQueue</title>
- <para>This is the name of the default expiry queue the server peer
+ <para>This is the name of the default expiry queue that the server peer
will use for destinations. The expiry can be overridden on a per
destination basis - see the destination MBean configuration for more
details. An expiry queue is a special destination where messages are
sent when they have expired. Message expiry is determined by the value
- of Message::getJMSExpiration() If the expiry queue is not specified at
- all then the message will be removed after it is expired.</para>
+ of Message::getJMSExpiration(). If the expiry queue is not specified at
+ all, the message will be removed after it has expired.</para>
</section>
<section id="conf.serverpeer.attributes.defaultredliverydelay">
<title>DefaultRedeliveryDelay</title>
- <para>When redelivering a message after failure of previous delivery
- it is often beneficial to introduce a delay perform redelivery in
- order to prevent thrashing of delivery-failure, delivery-failure
- etc</para>
+ <para>When redelivering a message after failure of previous delivery,
+ it is often beneficial to introduce a redelivery delay in
+ order to prevent recurring delivery failures.</para>
<para>The default value is <literal>0</literal> which means there will
be no delay.</para>
@@ -230,8 +230,8 @@
<section id="conf.serverpeer.attributes.messagecountersampleperiod">
<title>MessageCounterSamplePeriod</title>
- <para>Periodically the server will query each queue to gets its
- statistics. This is the period.</para>
+ <para>Periodically the server will query each queue to get its
+ statistics. This attribute sets the period.</para>
<para>The default value is <literal>10000</literal>
milliseconds.</para>
@@ -262,7 +262,7 @@
<title>DefaultMessageCounterHistoryDayLimit</title>
<para>JBoss Messaging provides a message counter history which shows
- the number of messages arriving on each queue of a certain number of
+ the number of messages arriving in each queue over a certain number of
days. This attribute represents the maxiumum number of days for which
to store message counter history. It can be overridden on a per
destination basis.</para>
@@ -274,9 +274,9 @@
<para>The name of the connection factory to use for pulling messages
between nodes.</para>
- <para>If you wish to turn off message sucking between queues
- altogether, but retain failover, then you can ommit this attribute
- altogether</para>
+ <para>If you wish to turn off pulling messages between queues
+ altogether, but retain failover, then you can omit this attribute
+ altogether.</para>
</section>
<section id="conf.serverpeer.attributes.defaultpreserveordering">
@@ -285,7 +285,7 @@
<para>If true, then strict JMS ordering is preserved in the cluster.
See the cluster configurations section for more details. Default is
false.</para>
- </section>
+ </section>sucking
<section id="conf.serverpeer.attributes.recoverdeliveriestimeout">
<title>RecoverDeliveriesTimeout</title>
@@ -294,14 +294,15 @@
aside, waiting for clients to reconnect. In the case that clients
never reconnect (e.g. the client is dead) then eventually these
messages will timeout and be added back to the queue. The value is in
- ms. The default is 5 mins.</para>
+ ms. The default is <literal>300000</literal> (five
+ minutes).</para>
</section>
<section id="conf.serverpeer.attributes.enablemessagecounters">
<title>EnableMessageCounters</title>
<para>Set this to true to enable message counters when the server
- starts</para>
+ starts.</para>
</section>
<section id="conf.serverpeer.attributes.suckerpassword">
@@ -309,19 +310,19 @@
<para>JBoss Messaging internally makes connections between nodes in
order to redistribute messages between clustered destinations. These
- connections are made with the user name of a special reserved user. On
+ connections are made with the user name of a special reserved user. With
this parameter you define the password used as these connections are
made. After JBossMessaging 1.4.1.GA you will need to define the Sucker
- Password on the ServerPeer and on the SecurityMetadataStore.
+ Password on the ServerPeer and on the SecurityMetadataStore.</para>
<warning>
- <para>This must be specified at install time, or the default password will be used. Any one who then knows the default password will be able to gain access to any destinations on the server. This value MUST be changed at install time.</para>
- </warning></para>
+ <para>This must be specified at install time, or the default password will be used. Anyone who then knows the default password will be able to gain access to any destinations on the server. This value MUST be changed at install time.</para>
+ </warning>
</section>
<section id="conf.serverpeer.attributes.stricttck">
<title>StrictTCK</title>
- <para>Set to true if you want strict JMS TCK semantiocs</para>
+ <para>Set to true if you want strict JMS TCK semantics.</para>
</section>
<section id="conf.serverpeer.attributes.destinations">
@@ -355,14 +356,14 @@
<section id="conf.serverpeer.attributes.persistencemanager">
<title>PersistenceManager</title>
- <para>This is the persistence manager that the ServerPeer uses. You
+ <para>This is the persistence manager used by the ServerPeer. You
will not normally need to change this attribute.</para>
</section>
<section id="conf.serverpeer.attributes.jmsusermanager">
<title>JMSUserManager</title>
- <para>This is the JMS user manager that the ServerPeer uses. You will
+ <para>This is the JMS user manager used by the ServerPeer. You will
not normally need to change this attribute.</para>
</section>
@@ -385,17 +386,12 @@
<para>This operation lets you programmatically deploy a
queue.</para>
- <para>There are two overloaded versions of this operation</para>
+ <para>There are two overloaded versions of this operation. If the queue already exists, but is undeployed, it is deployed. Otherwise, it is created and deployed.</para>
+
+ <para>The <literal>name</literal> parameter represents the name of the destination to deploy.</para>
- <para>If the queue already exists but is undeployed it is deployed.
- Otherwise it is created and deployed.</para>
-
- <para>The <literal>name</literal> parameter represents the name of
- the destination to deploy.</para>
-
<para>The <literal>jndiName</literal> parameter (optional)
- represents the full jndi name where to bind the destination. If this
- is not specified then the destination will be bound in
+ represents the full jndi name of where the destination should be bound. If this is not specified, the destination will be bound in
<DefaultQueueJNDIContext>/<name>.</para>
<para>The first version of this operation deploys the destination
@@ -415,7 +411,7 @@
storage.</para>
<para>This operation returns <literal>true</literal> if the queue
- was successfull undeployed. otherwise it returns
+ was successfully undeployed. Otherwise, it returns
<literal>false</literal>.</para>
</section>
@@ -425,15 +421,15 @@
<para>This operation lets you programmatically destroy a
queue.</para>
- <para>The queue is undeployed and then all its data is destroyed
- from the database.</para>
+ <para>The queue is undeployed and all its data is removed
+ from the database and destroyed.</para>
<warning>
<para>Be careful 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 successfully destroyed. otherwise it returns
+ was successfully destroyed. Otherwise, it returns
<literal>false</literal>.</para>
</section>
@@ -443,17 +439,13 @@
<para>This operation lets you programmatically deploy a
topic.</para>
- <para>There are two overloaded versions of this operation.</para>
+ <para>There are two overloaded versions of this operation. If the topic already exists, but is undeployed, it is deployed. Otherwise, it is created and deployed.</para>
- <para>If the topic already exists but is undeployed it is deployed.
- Otherwise it is created and deployed.</para>
-
<para>The <literal>name</literal> parameter represents the name of
the destination to deploy.</para>
<para>The <literal>jndiName</literal> parameter (optional)
- represents the full jndi name where to bind the destination. If this
- is not specified then the destination will be bound in
+ represents the full jndi name of where the destination should be bound. If this is not specified, the destination will be bound in
<DefaultTopicJNDIContext>/<name>.</para>
<para>The first version of this operation deploys the destination
@@ -469,11 +461,11 @@
<para>This operation lets you programmatically undeploy a
topic.</para>
- <para>The queue is undeployed but is NOT removed from persistent
+ <para>The queue is undeployed, but is NOT removed from persistent
storage.</para>
<para>This operation returns <literal>true</literal> if the topic
- was successfully undeployed. otherwise it returns
+ was successfully undeployed. Otherwise, it returns
<literal>false</literal>.</para>
</section>
@@ -483,22 +475,22 @@
<para>This operation lets you programmatically destroy a
topic.</para>
- <para>The topic is undeployed and then all its data is destroyed
- from the database.</para>
+ <para>The topic is undeployed, and all its data is removed
+ from the database and destroyed.</para>
<warning>
- <para>Be careful when using this method since it will delete all data for the topic. </para>
+ <para>Be careful when using this method, since it will delete all data for the topic. </para>
</warning>
<para>This operation returns <literal>true</literal> if the topic
- was successfully destroyed. otherwise it returns
+ was successfully destroyed. Otherwise, it returns
<literal>false</literal>.</para>
</section>
<section id="conf.serverpeer.operations.listmessagecountersashtml">
<title>ListMessageCountersHTML</title>
- <para>This operation returns message counters in an easy to display
+ <para>This operation returns message counters in an easily-displayed
HTML format.</para>
</section>
@@ -540,7 +532,7 @@
<title>ShowPreparedTransactions</title>
<para>Retrieves a list of the Xids for all transactions currently in
- a prepared state on the node in an easy to display HTML
+ a prepared state on the node in an easily-displayed HTML
format.</para>
</section>
</section>
@@ -551,27 +543,23 @@
<title>Changing the Database</title>
<para>Several JBoss Messaging services interact with persistent storage.
- They include: The Persistence Manager, The PostOffice and the JMS User
- Manager. The Persistence Manager is used to handle the message-related
+ They include: The Persistence Manager, The PostOffice, and the JMS User
+ Manager. The Persistence Manager is used to handle message-related
persistence. The Post Office handles binding related persistence. The JMS
- User manager handles user related persistence The configuration for all
+ User manager handles user-related persistence The configuration for all
these MBeans is handled in the
<filename>xxx-persistence-service.xml</filename> file.</para>
- <para>If the database you want to switch to is one of MySQL, Oracle,
- PostgreSQL, MS SQL Sever or Sybase, persistence configuration files are
- already available in the <filename>examples/config</filename> directory of
- the release bundle.</para>
+ <para>If you want to change to a MySQL, Oracle, PostgreSQL, MS SQL Sever or Sybase database, persistence configuration files are already available in the <filename>examples/config</filename> directory of the release bundle.</para>
<para>In order to enable support for one of these databases, just replace
the default <filename>hsqldb-persistence-service.xml</filename>
configuration file with the database-specific configuration file and
restart the server.</para>
- <para>Also, be aware that by default, the Messaging services relying on a
- datastore are referencing <literal>"java:/DefaultDS"</literal> for the
- datasource. If you are deploying a datasource with a different JNDI name,
- you need to update all the <literal>DataSource</literal> attribute in the
+ <para>Also, be aware that the Messaging services relying on a
+ datastore reference <literal>"java:/DefaultDS"</literal> for the
+ datasource by default. If you are deploying a datasource with a different JNDI name, you need to update all the <literal>DataSource</literal> attribute in the
persistence configuration file. Example data source configurations for
each of the popular databases are available in the distribution.</para>
</section>
@@ -579,22 +567,19 @@
<section id="conf.postoffice">
<title>Configuring the Post office</title>
- <para>It is the job of the post office to route messages to their
- destination(s).</para>
+ <para>The post office routes messages to their destination(s).</para>
- <para>The post office maintains the mappings between addresses to which
- messages can be sent and their final queues.</para>
+ <para>The post office maintains the mappings between valid addresses and their final queues.</para>
- <para>For example when sending a message with an address that represents a
+ <para>For example, when sending a message with an address that represents a
JMS queue name, the post office will route this to a single queue - the
JMS queue. When sending a message with an address that repesents a JMS
topic name, the post office will route this to a set of queues - one for
each JMS subscription.</para>
- <para>The post office also handles the persistence for the mapping of
- addresses.</para>
+ <para>The post office also handles the persistence for address mapping.</para>
- <para>JBoss Messaging post-offices are also cluster aware. In a cluster
+ <para>JBoss Messaging post offices are also cluster-aware. In a cluster,
they will automatically route and pull messages between them in order to
provide fully distributed JMS queues and topics.</para>
@@ -605,168 +590,169 @@
<para>Here is an example of a post office configuration:</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[
+<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>
+]]></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>The post office has the following attributes</title>
+ <title>The post office has the following attributes:</title>
<section id="conf.postoffice.attributes.datasource">
<title>DataSource</title>
@@ -787,38 +773,37 @@
<section id="conf.postoffice.attributes.createtables">
<title>CreateTablesOnStartup</title>
- <para>Set this to <literal>true</literal> if you wish the post office
+ <para>Set this to <literal>true</literal> if you want the post office
to attempt to create the tables (and indexes) when it starts. If the
- tables (or indexes) already exist a <literal>SQLException</literal>
+ tables (or indexes) already exist, a <literal>SQLException</literal>
will be thrown by the JDBC driver and ignored by the Persistence
Manager, allowing it to continue.</para>
<para>By default the value of <literal>CreateTablesOnStartup</literal>
- attribute is set to <literal>true</literal></para>
+ attribute is set to <literal>true</literal>.</para>
</section>
<section id="conf.postoffice.attributes.detectdups">
<title>DetectDuplicates</title>
- <para>Set this to <literal>true</literal> if you wish the post office
- detect duplicate messages that may sent when a send is retried on a
- different node after server failure.</para>
+ <para>Set this to <literal>true</literal> if you want the post office to
+ detect duplicate messages waiting to be resent after server failure.</para>
<para>By default the value of <literal>DetectDuplicates</literal>
- attribute is set to <literal>true</literal></para>
+ attribute is set to <literal>true</literal>.</para>
</section>
<section id="conf.postoffice.attributes.idcachesize">
<title>IDCacheSize</title>
- <para>If duplicate detection is enabled. (See
- <literal>DetectDuplicates</literal>), then the server will rememeber
- the last <literal>n</literal> message ids sent, to prevent duplicate
- messages sent after failover has occurred. The value of
+ <para>If duplicate detection is enabled (See
+ <literal>DetectDuplicates</literal>), the server will remember
+ the last <literal>n</literal> message IDs sent, to prevent duplicate
+ messages being sent after failover has occurred. The value of
<literal>n</literal> is determined by this attribute.</para>
- <para>By default the value of <literal>IDCacheSize</literal> attribute
- is set to <literal>500</literal></para>
+ <para>By default the value of the <literal>IDCacheSize</literal> attribute
+ is set to <literal>500</literal>.</para>
</section>
<section id="conf.postoffice.attributes.postofficename">
@@ -830,31 +815,29 @@
<section id="conf.postoffice.attributes.nodeidview">
<title>NodeIDView</title>
- <para>This returns set containing the node ids of all the nodes in the
- cluster.</para>
+ <para>This returns a dataset containing the node IDs of all nodes in a cluster.</para>
</section>
<section id="conf.postoffice.attributes.groupname">
<title>GroupName</title>
<para>All post offices in the cluster with the same group name will
- form a cluster together. Make sure the group name matches with all the
- nodes in the cluster you want to form a cluster with.</para>
+ form a cluster together. When forming a cluster, make sure that all desired nodes have a matching group name.</para>
</section>
<section id="conf.postoffice.attributes.clustered">
<title>Clustered</title>
- <para>If true the post office will take part in a cluster to form
- distributed queues and topics. If false then it will not participate
- in the cluster. If false, then all the cluster related attributes will
+ <para>If true, the post office will take part in a cluster to form
+ distributed queues and topics. If false, it will not participate
+ in a cluster, and all cluster-related attributes will
be ignored.</para>
</section>
<section id="conf.postoffice.attributes.statetimeout">
<title>StateTimeout</title>
- <para>The maximum time to wait when waiting for the group state to
+ <para>The maximum time to wait for the group state to
arrive when a node joins a pre-existing cluster.</para>
<para>The default value is <literal>5000</literal>
@@ -874,36 +857,30 @@
<section id="conf.postoffice.attributes.failoveronnodeleave">
<title>FailoverOnNodeLeave</title>
- <para>If this attribute is <literal>true</literal> then if a server
- node is shut down cleanly, then this will cause any connections on the
- shutting down node to failover onto another node.</para>
+ <para>If this attribute is <literal>true</literal>, when a server
+ node is shut down cleanly, any connections on the node will failover onto another node.</para>
<para>The default value for this is attribute is
- <literal>false</literal></para>
+ <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 for replies to come back. This prevents us
- overwhelming JGroups. This is rarely a good reason to change
- this.</para>
-
- <para>The default value is <literal>50</literal></para>
+ <para>The maximum number of concurrent replication requests to make before replies are blocked. This prevents us overwhelming JGroups. There is rarely a good reason to change this.</para>
+
+ <para>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
- contains the JGroups stack configuration for the control
- channel.</para>
+ <para>JBoss Messaging uses JGroups for all group management. ControlChannelConfig contains the JGroups stack configuration for the control channel.</para>
- <para>The control channel is used for sending request/receiving
- responses from other nodes in the cluster</para>
+ <para>The control channel is used to send request/receiving
+ responses from other nodes in the cluster.</para>
- <para>The details of the JGroups configuration won't be discussed here
+ <para>The details of the JGroups configuration won't be discussed here,
since it is standard JGroups configuration. Detailed information on
JGroups can be found in JGroups release documentation or on-line at
<ulink url="http://www.jgroups.org">http://www.jgroups.org</ulink> or
@@ -934,15 +911,11 @@
<section id="conf.persistencemanager">
<title>Configuring the Persistence Manager</title>
- <para>It is the job of the persistence manager to manage all message
- related persistence.</para>
+ <para>It is the job of the persistence manager to manage all message-related persistence.</para>
- <para>JBoss Messaging ships with a JDBC Persistence Manager used for
- handling persistence of message data in a relational database accessed via
+ <para>JBoss Messaging ships with a JDBC Persistence Manager, which is used to handle persistence of message data in a relational database accessed via
JDBC. The Persistence Manager implementation is pluggable (the Persistence
- Manager is a Messaging server plug-in), this making possible to provide
- other implementations for persisting message data in non relational
- stores, file stores etc.</para>
+ Manager is a Messaging server plug-in), so it is possible to provide other implementations for persisting message data in non-relational stores, file stores etc.</para>
<para>The configuration of "persistent" services is grouped in a
<filename>xxx-persistence-service.xml</filename> file, where xxx
@@ -952,16 +925,14 @@
by default with any JBossAS instance.</para>
<warning>
- <para>The default Persistence Manager configuration works out of the
- box with Hypersonic, however it must be stressed that Hypersonic should
- not be used in a production environment mainly due to its limited
+ <para>The default Persistence Manager configuration works with Hypersonic out of the box. However, it must be stressed that Hypersonic should
+ not be used in a production environment, mainly due to its limited
support for transaction isolation and its propensity to behave
erratically under high load.</para>
<para>The <ulink
url="http://wiki.jboss.org/wiki/Wiki.jsp?page=ConfigJBossMQDB">Critique
- of Hypersonic</ulink> wiki page outlines some of the well-known issues
- occuring when using this database.</para>
+ of Hypersonic</ulink> wiki page outlines some well-known issues that occur when using this database.</para>
</warning>
<para>JBoss Messaging also ships with pre-made Persistence Manager
@@ -976,13 +947,7 @@
available in the <filename>examples/config</filename> directory of the
release bundle.</para>
- <para>Users are encouraged to contribute their own configuration files
- where we will thoroughly test them before certifying them for suppported
- use with JBoss Messaging. The JDBC Persistence Manager has been designed
- to use standard SQL for the DML so writing a JDBC Persistence Manager
- configuration for another database is usually only a fairly simple matter
- of changing DDL in the configuration which is likely to be different for
- different databases.</para>
+ <para>Users are encouraged to submit their own configuration files for testing, so they can be certified for suppported use with JBoss Messaging. The JDBC Persistence Manager has been designed to use standard SQL for the DML, so writing a JDBC Persistence Manager configuration for another database usually only involves changing DDL, which is likely to change depending on the database.</para>
<para>JBoss Messaging also ships with a Null Persistence Manager config -
this can be used when you don't want any persistence at all.</para>
@@ -991,108 +956,108 @@
below:</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>
+<mbean code="org.jboss.messaging.core.jmx.JDBCPersistenceManagerService"
+name="jboss.messaging:service=PersistenceManager"
+xmbean-dd="xmdesc/JDBCPersistenceManager-xmbean.xml">
- <attribute name="UseNDBFailoverStrategy">true</attribute>
-
- </mbean>
-
- </programlisting>
+<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>
<section id="conf.persistencemanager.sybasemssqlnotes">
<title>Important notes for Sybase and Microsoft SQL Server users</title>
- <note><para>When a database is created in Sybase the maximum size of text and image datatypes is set to the default page size of 2 KB. Any longer message payload is truncated without any information or warning. The database parameters have to be updated to set the @@TEXTSIZE parameter to a higher value. The truncation behaviour may also be observed in MSSQL Server if @@TEXTSIZE is changed from its default value to a smaller one. Further information: <ulink url="http://jira.jboss.com/jira/browse/SOA-554"/>.</para></note>
- <note><para>Sybase database may fail to insert a row if the total size of the row exceeds the page size allocated for the database. A command line option passed to the dataserver command used to start the database can be used to change the page size. Further information: <ulink url="http://jira.jboss.com/jira/browse/SOA-553"/></para></note>
+ <note><para>When a database is created in Sybase, the maximum page size, including text and image datatypes, is 2 KB by default. Larger message payloads are truncated without explanation or warning. To avoid truncation, the @@TEXTSIZE parameter must be set to a higher value. Truncation may also occur in MSSQL Server if @@TEXTSIZE is changed from its default value to a smaller one. Further information: <ulink url="http://jira.jboss.com/jira/browse/SOA-554"/>.</para></note>
+ <note><para>Sybase databases may fail to insert a row if the total size of the row exceeds allocated page size. A command line option passed to the dataserver command used to start the database can be used to change the page size. Further information: <ulink url="http://jira.jboss.com/jira/browse/SOA-553"/></para></note>
<note><para>Microsoft SQL Server does not automatically de-allocate the hard-drive space occupied by data in a database when that data is deleted. If used as a data-store for services that temporarily store many records, such as a messaging service, the disk space used will grow to be much greater than the amount of data actually being stored. Your database administrator should implement database maintenance plans to ensure that unused space is reclaimed. Please refer to your Microsoft SQL Server documentation for the DBCC commands ShrinkDatabase and UpdateUsage for guidance. <ulink url="https://jira.jboss.org/jira/browse/SOA-629"/></para></note>
</section>
<section id="conf.persistencemanager.attributes">
<title>We now discuss the MBean attributes of the PersistenceManager
- MBean</title>
-
+ MBean.</title>
+
<section id="conf.persistencemanager.attributes.createtables">
<title>CreateTablesOnStartup</title>
-
- <para>Set this to <literal>true</literal> if you wish the Persistence
+
+ <para>Set this to <literal>true</literal> if you wish the Persistence
Manager to attempt to create the tables (and indexes) when it starts.
- If the tables (or indexes) already exist a
+ If the tables (or indexes) already exist, a
<literal>SQLException</literal> will be thrown by the JDBC driver and
ignored by the Persistence Manager, allowing it to continue.</para>
- <para>By default the value of <literal>CreateTablesOnStartup</literal>
- attribute is set to <literal>true</literal></para>
+ <para>By default, the value of the <literal>CreateTablesOnStartup</literal>
+ attribute is set to <literal>true</literal>.</para>
</section>
<section id="conf.persistencemanager.attributes.batchupdates">
@@ -1102,46 +1067,38 @@
JDBC batch updates. The JDBC Persistence Manager will then group
multiple database updates in batches to aid performance.</para>
- <para>By default the value of <literal>UsingBatchUpdates</literal>
- attribute is set to <literal>false</literal></para>
+ <para>By default, the value of the <literal>UsingBatchUpdates</literal>
+ attribute is set to <literal>false</literal>.</para>
</section>
<section id="conf.persistencemanager.attributes.binarystream">
<title>UsingBinaryStream</title>
<para>Set this to <literal>true</literal> if you want messages to be
- store and read using a JDBC binary stream rather than using
- getBytes(), setBytes(). Some database has limits on the maximum number
+ stored and read using a JDBC binary stream rather than using
+ getBytes(), setBytes(). Some databases have limits on the maximum number
of bytes that can be get/set using getBytes()/setBytes().</para>
- <para>By default the value of <literal>UsingBinaryStream</literal>
- attribute is set to <literal>true</literal></para>
+ <para>By default, the value of the <literal>UsingBinaryStream</literal>
+ attribute is set to <literal>true</literal>.</para>
</section>
<section id="conf.persistencemanager.attributes.trailingbyte">
<title>UsingTrailingByte</title>
- <para>Certain version of Sybase are known to truncate blobs if they
- have trailing zeros. To prevent this if this attribute is set to
- <literal>true</literal> then a trailing non zero byte will be added
- and removed to each blob before and after persistence to prevent the
- database from truncating it. Currently this is only known to be
- necessary for Sybase.</para>
+ <para>Certain versions of Sybase are known to truncate blobs with trailing zeros. To prevent this, set the attribute to <literal>true</literal>: a trailing non-zero byte will be added and removed to each blob before and after persistence to prevent the database from truncating it. Currently this is only known to be necessary for Sybase.</para>
- <para>By default the value of <literal>UsingTrailingByte</literal>
- attribute is set to <literal>false</literal></para>
+ <para>By default, the value of the <literal>UsingTrailingByte</literal>
+ attribute is set to <literal>false</literal>.</para>
</section>
<section id="conf.persistencemanager.attributes.supportsblobonselect">
<title>SupportsBlobOnSelect</title>
- <para>Oracle (and possibly other databases) is known to not allow
- BLOBs to be inserted using a INSERT INTO ... SELECT FROM statement,
- and requires a two stage conditional insert of messages. If this value
- is false then such a two stage insert will be used.</para>
+ <para>Oracle (and possibly other databases) does not allow blobs to be inserted using a INSERT INTO ... SELECT FROM statement, and requires a two-stage conditional insert of messages. If this attribute is set to <literal>false</literal>, this two-stage insert will be used.</para>
- <para>By default the value of <literal>SupportsBlobOnSelect</literal>
- attribute is set to <literal>true</literal></para>
+ <para>By default, the value of the <literal>SupportsBlobOnSelect</literal>
+ attribute is set to <literal>true</literal>.</para>
</section>
<section id="conf.persistencemanager.attributes.sqlproperties">
@@ -1149,37 +1106,28 @@
<para>This is where the DDL and DML for the particular database is
specified. If a particular DDL or DML statement is not overridden, the
- default Hypersonic configuration will be used for that
- statement.</para>
+ default Hypersonic configuration will be used for that statement.</para>
</section>
<section id="conf.persistencemanager.attributes.maxparams">
<title>MaxParams</title>
- <para>When loading messages the persistence manager will generate
+ <para>When loading messages, the persistence manager will generate
prepared statements with many parameters. This value tells the
- persistence manager what the absolute maximum number of parameters are
- allowable per prepared statement.</para>
+ persistence manager the absolute maximum number of parameters allowable per prepared statement.</para>
- <para>By default the value of <literal>MaxParams</literal> attribute
- is set to <literal>100</literal></para>
+ <para>By default, the value of the <literal>MaxParams</literal> attribute
+ is set to <literal>100</literal>.</para>
</section>
<section id="conf.persistencemanager.attributes.usendbfailoverstrategy">
<title>UseNDBFailoverStrategy</title>
- <para>When running in a clustered database environment it is possible
- that some databases, MySQL for instance, can fail during the commit of
- a database transaction. This can happen if the database node dies
- whilst committing meaning that the final state of the transaction is
- unknown. If this attribute is set to true and the above happens then
- the SQL statement will be re-executed, however if there is a further
- error an assumption is made that this is because the previous
- transaction committed successfully and the error is ignored.</para>
+ <para>When running in a clustered database environment, some databases (mySQL, for instance), can fail during the commit of a database transaction. This can happen if the database node dies during commit, leaving the final state of the transaction unknown. If this attribute is set to true when this occurs, the SQL statement will be re-executed. However, if there is a further error, the system assumes that the previous transaction committed successfully and the error is ignored.</para>
- <para>By default the value of
+ <para>By default, the value of the
<literal>UseNDBFailoverStrategy</literal> attribute is set to
- <literal>false</literal></para>
+ <literal>false</literal>.</para>
</section>
</section>
@@ -1192,50 +1140,50 @@
<title>Configuring the JMS user manager</title>
<para>The JMS user manager handles the mapping of pre-configured client
- IDs to users and also managers the user and role tables which may or may
- not be used depending on which login module you have configured</para>
+ IDs to users, and manages the user and role tables which may or may
+ not be used depending on your configured login module.</para>
- <para>Here is an example JMSUserManager configuration</para>
+ <para>Here is an example JMSUserManager 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>
+<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>We now discuss the MBean attributes of the JMSUserManager
- MBean</title>
+ MBean.</title>
<section id="conf.jmsusermanager.attributes.createtables">
<title>CreateTablesOnStartup</title>
<para>Set this to <literal>true</literal> if you wish the JMS user
manager to attempt to create the tables (and indexes) when it starts.
- If the tables (or indexes) already exist a
+ If the tables (or indexes) already exist, a
<literal>SQLException</literal> will be thrown by the JDBC driver and
ignored by the Persistence Manager, allowing it to continue.</para>
- <para>By default the value of <literal>CreateTablesOnStartup</literal>
- attribute is set to <literal>true</literal></para>
+ <para>By default, the value of the <literal>CreateTablesOnStartup</literal>
+ attribute is set to <literal>true</literal>.</para>
</section>
<section id="conf.jmsusermanager.attributes.batchupdates">
@@ -1245,8 +1193,8 @@
JDBC batch updates. The JDBC Persistence Manager will then group
multiple database updates in batches to aid performance.</para>
- <para>By default the value of <literal>UsingBatchUpdates</literal>
- attribute is set to <literal>false</literal></para>
+ <para>By default, the value of <literal>UsingBatchUpdates</literal>
+ attribute is set to <literal>false</literal>.</para>
</section>
<section id="conf.jmsusermanager.attributes.sqlproperties">
@@ -1258,8 +1206,8 @@
statement.</para>
<para>Default user and role data can also be specified here. Any data
- to be inserted must be specified with property names starting with
- <literal>POPULATE.TABLES</literal> as in the above example.</para>
+ to be inserted must be specified with property names beginning with
+ <literal>POPULATE.TABLES</literal>, as in the above example.</para>
</section>
</section>
@@ -1281,149 +1229,149 @@
listed below:</para>
<programlisting>
- <!--
- The Default Dead Letter Queue. This destination is a dependency of an EJB MDB container.
- -->
+<!--
+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.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=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.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=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>
+<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 -->
+<!-- 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=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=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.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=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=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>
+<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>
@@ -1434,39 +1382,39 @@
<title>Configuring queues</title>
<section id="conf.destination.queue.attributes">
- <title>We now discuss the attributes of the Queue MBean</title>
+ <title>We now discuss the attributes of the Queue MBean.</title>
<section id="conf.destination.queue.attributes.name">
<title>Name</title>
- <para>The name of the queue</para>
+ <para>The name of the queue.</para>
</section>
<section id="conf.destination.queue.attributes.jndiName">
<title>JNDIName</title>
- <para>The JNDI name where the queue is bound</para>
+ <para>The JNDI name where the queue is bound.</para>
</section>
<section id="conf.destination.queue.attributes.dlq">
<title>DLQ</title>
- <para>The DLQ used for this queue. Overrides any value set on the
- ServerPeer config</para>
+ <para>The DLQ used for this queue. Overrides any value set in the
+ ServerPeer configuration.</para>
</section>
<section id="conf.destination.queue.attributes.expiryqueue">
<title>ExpiryQueue</title>
<para>The Expiry queue used for this queue. Overrides any value set
- on the ServerPeer config</para>
+ in the ServerPeer configuration.</para>
</section>
<section id="conf.destination.queue.attributes.redeliverydelay">
<title>RedeliveryDelay</title>
<para>The redelivery delay to be used for this queue. Overrides any
- value set on the ServerPeer config</para>
+ value set in the ServerPeer configuration.</para>
</section>
<section id="conf.destination.queue.attributes.maxdeliveryattempts">
@@ -1474,15 +1422,15 @@
<para>The maximum number of times delivery of a message will be
attempted before sending the message to the DLQ, if configured. If
- set to -1 (the default), the value from the ServerPeer config is
- used. Any other setting overrides the value set on the ServerPeer
- config.</para>
+ set to -1 (the default), the value from the ServerPeer configuration is
+ used. Any other setting overrides the value set in the ServerPeer
+ configuration.</para>
</section>
<section id="conf.destination.queue.attributes.security">
<title>Destination Security Configuration</title>
- <para><literal>SecurityConfig</literal> - allows you to determine
+ <para><literal>SecurityConfig</literal> allows you to determine
which roles are allowed to read, write and create on the
destination. It has exactly the same syntax and semantics as the
security configuration in JBossMQ destinations.</para>
@@ -1495,15 +1443,15 @@
particular role.</para>
<para>If the <literal>read</literal> attribute is
- <literal>true</literal> then that role will be able to read (create
- consumers, receive messaages or browse) this destination.</para>
+ <literal>true</literal>, that role will be able to read (create
+ consumers, receive messages, or browse) this destination.</para>
<para>If the <literal>write</literal> attribute is
- <literal>true</literal> then that role will be able to write (create
+ <literal>true</literal>, that role will be able to write (create
producers or send messages) to this destination.</para>
<para>If the <literal>create</literal> attribute is
- <literal>true</literal> then that role will be able to create
+ <literal>true</literal>, that role will be able to create
durable subscriptions on this destination.</para>
<para>Note that the security configuration for a destination is
@@ -1519,47 +1467,45 @@
in JBoss Messaging.</para>
<para>If your application needs to support very large queues or
- subscriptions containing potentially millions of messages, then it's
+ subscriptions potentially containing millions of messages, then it is
not possible to store them all in memory at once.</para>
<para>JBoss Messaging solves this problem but letting you specify
the maximum number of messages that can be stored in memory at any
- one time, on a queue-by-queue, or topic-by-topic basis. JBoss
- Messaging then pages messages to and from storage transparently in
+ one time, on a queue-by-queue or topic-by-topic basis. JBoss
+ Messaging then pages messages to and from storage transparently, in
blocks, allowing queues and subscriptions to grow to very large
sizes without any performance degradation as channel size
increases.</para>
- <para>This has been tested with in excess of 10 million 2K messages
- on very basic hardware and has the potential to scale to much larger
- number of messages.</para>
+ <para>This has been tested with over 10 million 2 KB messages on very basic hardware and has the potential to scale to much greater of message numbers.</para>
<para>The individual parameters are:</para>
- <para><literal>FullSize</literal> - this is the maximum number of
+ <para><literal>FullSize</literal>: The maximum number of
messages held by the queue or topic subscriptions in memory at any
one time. The actual queue or subscription can hold many more
- messages than this but these are paged to and from storage as
+ messages than this, but these are paged to and from storage as
necessary as messages are added or consumed.</para>
- <para><literal>PageSize</literal> - When loading messages from the
- queue or subscrition this is the maximum number of messages to
+ <para><literal>PageSize</literal>: When loading messages from the
+ queue or subscrition, this is the maximum number of messages to
pre-load in one operation.</para>
- <para><literal>DownCacheSize</literal> - When paging messages to
- storage from the queue they first go into a "Down Cache" before
+ <para><literal>DownCacheSize</literal>: When paging messages to
+ storage from the queue, messages move to a "Down Cache" before
being written to storage. This enables the write to occur as a
- single operation thus aiding performance. This setting determines
+ single operation, thus aiding performance. This setting determines
the max number of messages that the Down Cache will hold before they
are flushed to storage.</para>
<para>If no values for <literal>FullSize</literal>,
<literal>PageSize</literal>, or <literal>DownCacheSize</literal> are
- specified they will default to values 75000, 2000, 2000
+ specified, they will default to values 75000, 2000, 2000
respectively.</para>
<para>If you want to specify the paging parameters used for
- temporary queues then you need to specify them on the appropriate
+ temporary queues, then you need to specify them on the appropriate
connection factory. See connection factory configuration for
details.</para>
</section>
@@ -1568,7 +1514,7 @@
<title>CreatedProgrammatically</title>
<para>Returns <literal>true</literal> if the queue was created
- programmatically</para>
+ programmatically.</para>
</section>
<section id="conf.destination.queue.attributes.messagecount">
@@ -1576,7 +1522,7 @@
<para>Returns the total number of messages in the queue = number not
being delivered + number being delivered + number being
- scheduled</para>
+ scheduled.</para>
</section>
<section id="conf.destination.queue.attributes.scheduledmessagecount">
@@ -1586,24 +1532,23 @@
the number of messages scheduled to be delivered at a later
date.</para>
- <para>Scheduled delivery is a feature of JBoss Messaging where you
- can send a message and specify the earliest time at which it will be
- delivered. E.g. you can send a message now, but the message won't
- actually be delivered until 2 hours time.</para>
+ <para>Scheduled delivery is a feature of JBoss Messaging that allows you to send a message and specify the earliest time at which it will be
+ delivered. For example, you can send a message now, but the message won't
+ actually be delivered for 2 hours.</para>
- <para>To do this, you just need to set the following header in the
+ <para>To do this, set the following header in the
message before sending:</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);
+
+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>
@@ -1611,9 +1556,9 @@
<section id="conf.destination.queue.attributes.maxsize">
<title>MaxSize</title>
- <para>A maximum size (in number of messages) can be specified for a
+ <para>A maximum size (for number of messages) can be specified for a
queue. Any messages that arrive beyond this point will be dropped.
- The default is <literal>-1</literal> which is unbounded.</para>
+ The default is <literal>-1</literal>, which is unbounded.</para>
</section>
<section id="conf.destination.queue.attributes.clustered">
@@ -1632,14 +1577,13 @@
<section id="conf.destination.queue.attributes.messagecounterstats">
<title>MessageCounterStatistics</title>
- <para>The statistics for the message counter</para>
+ <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 to hold message counter history
- for. Overrides any value set on the ServerPeer.</para>
+ <para>The maximum number of days to hold message counter history. Overrides any value set on the ServerPeer.</para>
</section>
<section id="conf.destination.queue.attributes.consumercount">
@@ -1651,49 +1595,49 @@
</section>
<section id="conf.destination.queue.operations">
- <title>We now discuss the MBean operations of the Queue MBean</title>
+ <title>We now discuss the MBean operations of the Queue MBean.</title>
<section id="conf.destination.queue.operations.removeallmessages">
<title>RemoveAllMessages</title>
- <para>Remove (and delete) all messages from the queue.
+ <para>Remove (and delete) all messages from the queue.</para>
<warning>
- <para>Use this with caution. It will permanently delete all messages from the queue </para>
- </warning>.</para>
+ <para>Use this with caution. It will permanently delete all messages from the queue.</para>
+ </warning>
</section>
<section id="conf.destination.queue.operations.listallmessages">
<title>ListAllMessages</title>
- <para>List all messages currently in the queue</para>
+ <para>List all messages currently in the queue.</para>
- <para>There are two overloaded versions of this operation: One takes
+ <para>There are two overloaded versions of this operation: one takes
a JMS selector as an argument, the other does not. By using the
- selector you can retrieve a subset of the messages in the queue that
- match the criteria</para>
+ selector, you can retrieve a subset of messages in the queue that
+ match the criteria.</para>
</section>
<section id="conf.destination.queue.operations.listdurablemessages">
<title>ListDurableMessages</title>
- <para>As listAllMessages but only lists the durable messages</para>
+ <para>Works similarly to ListAllMessages, but only lists durable messages.</para>
- <para>There are two overloaded versions of this operation: One takes
+ <para>There are two overloaded versions of this operation: one takes
a JMS selector as an argument, the other does not. By using the
- selector you can retrieve a subset of the messages in the queue that
- match the criteria</para>
+ selector, you can retrieve a subset of messages in the queue that
+ match the criteria.</para>
</section>
<section id="conf.destination.queue.operations.listnondurablemessages">
<title>ListNonDurableMessages</title>
- <para>As listAllMessages but only lists the non durable
- messages</para>
+ <para>Works similarly to ListAllMessages, but only lists the non-durable
+ messages.</para>
- <para>There are two overloaded versions of this operation: One takes
+ <para>There are two overloaded versions of this operation: one takes
a JMS selector as an argument, the other does not. By using the
- selector you can retrieve a subset of the messages in the queue that
- match the criteria</para>
+ selector you can retrieve a subset of messages in the queue that
+ match the criteria.</para>
</section>
<section id="conf.destination.queue.operations.resetmessagecounter">
@@ -1711,15 +1655,15 @@
<section id="conf.destination.queue.operations.listmessagecounterashtml">
<title>ListMessageCounterAsHTML</title>
- <para>Lists the message counter in an easy to display HTML
- format</para>
+ <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 easy to display HTML
- format</para>
+ <para>Lists the message counter history in an easily-displayed HTML
+ format.</para>
</section>
</section>
</section>
@@ -1728,55 +1672,55 @@
<title>Configuring topics</title>
<section id="conf.destination.topic.attributes">
- <title>We now discuss the MBean attributes of the Topic MBean</title>
+ <title>We now discuss the MBean attributes of the Topic MBean.</title>
<section id="conf.destination.topic.attributes.name">
<title>Name</title>
- <para>The name of the topic</para>
+ <para>The name of the topic.</para>
</section>
<section id="conf.destination.topic.attributes.jndiName">
<title>JNDIName</title>
- <para>The JNDI name where the topic is bound</para>
+ <para>The JNDI name where the topic is bound.</para>
</section>
<section id="conf.destination.topic.attributes.dlq">
<title>DLQ</title>
- <para>The DLQ used for this topic. Overrides any value set on the
- ServerPeer config</para>
+ <para>The DLQ used for this topic. Overrides any value set in the
+ ServerPeer configuration.</para>
</section>
<section id="conf.destination.topic.attributes.expiryqueue">
<title>ExpiryQueue</title>
<para>The Expiry queue used for this topic. Overrides any value set
- on the ServerPeer config</para>
+ oin the ServerPeer configuration.</para>
</section>
<section id="conf.destination.topic.attributes.redeliverydelay">
<title>RedeliveryDelay</title>
<para>The redelivery delay to be used for this topic. Overrides any
- value set on the ServerPeer config</para>
+ value set in the ServerPeer configuration.</para>
</section>
<section id="conf.destination.topic.attributes.maxdeliveryattempts">
<title>MaxDeliveryAttempts</title>
- <para>The maximum number of times delivery of a message will be
- attempted before sending the message to the DLQ, if configured. If
- set to -1 (the default), the value from the ServerPeer config is
- used. Any other setting overrides the value set on the ServerPeer
- config.</para>
+ <para>The maximum number of times message delivery will be
+ attempted before the message is sent to the DLQ, if configured. If
+ set to -1 (the default), the value from the ServerPeer configuration is
+ used. Any other setting overrides the value set in the ServerPeer
+ configuration.</para>
</section>
<section id="conf.destination.topic.attributes.security">
<title>Destination Security Configuration</title>
- <para><literal>SecurityConfig</literal> - allows you to determine
+ <para><literal>SecurityConfig</literal>: Allows you to determine
which roles are allowed to read, write and create on the
destination. It has exactly the same syntax and semantics as the
security configuration in JBossMQ destinations.</para>
@@ -1789,8 +1733,8 @@
particular role.</para>
<para>If the <literal>read</literal> attribute is
- <literal>true</literal> then that role will be able to read (create
- consumers, receive messaages or browse) this destination.</para>
+ <literal>true</literal>, that role will be able to read (create
+ consumers, receive messages or browse) this destination.</para>
<para>If the <literal>write</literal> attribute is
<literal>true</literal> then that role will be able to write (create
@@ -1802,7 +1746,7 @@
<para>Note that the security configuration for a destination is
optional. If a <literal>SecurityConfig</literal> element is not
- specifed then the default security configuration from the Server
+ specifed, then the default security configuration from the Server
Peer will be used.</para>
</section>
@@ -1824,36 +1768,36 @@
sizes without any performance degradation as channel size
increases.</para>
- <para>This has been tested with in excess of 10 million 2K messages
- on very basic hardware and has the potential to scale to much larger
+ <para>This has been tested with over 10 million 2 KB messages
+ on very basic hardware, and has the potential to scale to a much greater
number of messages.</para>
<para>The individual parameters are:</para>
- <para><literal>FullSize</literal> - this is the maximum number of
+ <para><literal>FullSize</literal>: The maximum number of
messages held by the queue or topic subscriptions in memory at any
one time. The actual queue or subscription can hold many more
- messages than this but these are paged to and from storage as
+ messages than this, but these are paged to and from storage as
necessary as messages are added or consumed.</para>
- <para><literal>PageSize</literal> - When loading messages from the
- queue or subscrition this is the maximum number of messages to
+ <para><literal>PageSize</literal>: When loading messages from the
+ queue or subscription, this is the maximum number of messages to
pre-load in one operation.</para>
- <para><literal>DownCacheSize</literal> - When paging messages to
- storage from the queue they first go into a "Down Cache" before
+ <para><literal>DownCacheSize</literal> - When messages are paged to
+ storage from the queue, they are moved into a "Down Cache" before
being written to storage. This enables the write to occur as a
- single operation thus aiding performance. This setting determines
+ single operation, thus aiding performance. This setting determines
the max number of messages that the Down Cache will hold before they
are flushed to storage.</para>
<para>If no values for <literal>FullSize</literal>,
<literal>PageSize</literal>, or <literal>DownCacheSize</literal> are
- specified they will default to values 75000, 2000, 2000
+ specified, they will default to values 75000, 2000, 2000
respectively.</para>
<para>If you want to specify the paging parameters used for
- temporary queues then you need to specify them on the appropriate
+ temporary queues, then you need to specify them on the appropriate
connection factory. See connection factory configuration for
details.</para>
</section>
@@ -1862,15 +1806,15 @@
<title>CreatedProgrammatically</title>
<para>Returns <literal>true</literal> if the topic was created
- programmatically</para>
+ programmatically.</para>
</section>
<section id="conf.destination.topic.attributes.maxsize">
<title>MaxSize</title>
- <para>A maximum size (in number of messages) can be specified for a
+ <para>A maximum size (for number of messages) can be specified for a
topic subscription. Any messages that arrive beyond this point will
- be dropped. The default is <literal>-1</literal> which is
+ be dropped. The default is <literal>-1</literal>, which is
unbounded.</para>
</section>
@@ -1878,14 +1822,13 @@
<title>Clustered</title>
<para>Clustered destinations must have this set to
- <literal>true</literal></para>
+ <literal>true</literal>.</para>
</section>
<section id="conf.destination.topic.attributes.messagecounterhistorydaylimit">
<title>MessageCounterHistoryDayLimit</title>
- <para>The maximum number of days to hold message counter history
- for. Overrides any value set on the ServerPeer.</para>
+ <para>The maximum number of days to hold message counter history. Overrides any value set on the ServerPeer.</para>
</section>
<section id="conf.destination.topic.attributes.messagecounters">
@@ -1919,73 +1862,71 @@
<section id="conf.destination.topic.attributes.allsubscriptionscount">
<title>AllSubscriptionsCount</title>
- <para>The count of all subscriptions on this topic</para>
+ <para>The count of all subscriptions on this topic.</para>
</section>
<section id="conf.destination.topic.attributes.durablesubscriptionscount">
<title>DurableSubscriptionsCount</title>
- <para>The count of all durable subscriptions on this topic</para>
+ <para>The count of all durable subscriptions on this topic.</para>
</section>
<section id="conf.destination.topic.attributesnon.durablesubscriptionscount">
<title>NonDurableSubscriptionsCount</title>
<para>The count of all non durable subscriptions on this
- topic</para>
+ topic.</para>
</section>
</section>
<section id="conf.destination.topic.operations">
- <title>We now discuss the MBean operations of the Topic MBean</title>
+ <title>We now discuss the MBean operations of the Topic MBean.</title>
<section id="conf.destination.topic.operations.removeallmessages">
<title>RemoveAllMessages</title>
- <para>Remove (and delete) all messages from the subscriptions of
- this topic.
+ <para>Removes (and deletes) all messages from the subscriptions of
+ this topic.</para>
<warning>
- <para>Use this with caution. It will permanently delete all messages from the topic </para>
- </warning></para>
+ <para>Use this with caution. It will permanently delete all messages from the topic.</para>
+ </warning>
</section>
<section id="conf.destination.topic.operations.listallsubscriptions">
<title>ListAllSubscriptions</title>
- <para>List all subscriptions of this topic</para>
+ <para>List all subscriptions of this topic.</para>
</section>
<section id="conf.destination.topic.operations.listdurablesubscriptions">
<title>ListDurableSubscriptions</title>
- <para>List all durable subscriptions of this topic</para>
+ <para>List all durable subscriptions of this topic.</para>
</section>
<section id="conf.destination.topic.operations.listnondurablesubscriptions">
<title>ListNonDurableSubscriptions</title>
- <para>List all non durable subscriptions of this topic</para>
+ <para>List all non-durable subscriptions of this topic.</para>
</section>
<section id="conf.destination.topic.operations.listallsubscriptionsashtml">
<title>ListAllSubscriptionsAsHTML</title>
- <para>List all subscriptions of this topic in an easy to display
- HTML format</para>
+ <para>List all subscriptions of this topic in an easily-displayed
+ HTML format.</para>
</section>
<section id="conf.destination.topic.operations.listdurablesubscriptionsashtml">
<title>ListDurableSubscriptionsAsHTML</title>
- <para>List all durable subscriptions of this topic in an easy to
- display HTML format</para>
+ <para>List all durable subscriptions of this topic in an easily-displayed HTML format.</para>
</section>
<section id="conf.destination.topic.operations.listnondurablesubscriptionsashtml">
<title>ListNonDurableSubscriptionsAsHTML</title>
- <para>List all non durable subscriptions of this topic in an easy to
- display HTML format</para>
+ <para>List all non durable subscriptions of this topic in an easily-displayed HTML format.</para>
</section>
<section id="conf.destination.topic.operations.listallmessages">
@@ -1993,8 +1934,8 @@
<para>Lists all messages for the specified subscription.</para>
- <para>There are two overloaded versions of this operation. One that
- takes a selector and one that does not. By specifyingthe selector
+ <para>There are two overloaded versions of this operation: one that
+ takes a selector and one that does not. By specifying the selector,
you can limit the messages returned.</para>
</section>
@@ -2004,8 +1945,8 @@
<para>Lists all non durable messages for the specified
subscription.</para>
- <para>There are two overloaded versions of this operation. One that
- takes a selector and one that does not. By specifyingthe selector
+ <para>There are two overloaded versions of this operation: one that
+ takes a selector and one that does not. By specifying the selector,
you can limit the messages returned.</para>
</section>
@@ -2015,8 +1956,8 @@
<para>Lists all durable messages for the specified
subscription.</para>
- <para>There are two overloaded versions of this operation. One that
- takes a selector and one that does not. By specifyingthe selector
+ <para>There are two overloaded versions of this operation: one that
+ takes a selector and one that does not. By specifying the selector,
you can limit the messages returned.</para>
</section>
</section>
@@ -2028,128 +1969,122 @@
<section id="conf.connectionfactory">
<title>Configuring Connection Factories</title>
- <para>With the default configuration JBoss Messaging binds two connection
- factories in JNDI at start-up.</para>
+ <para>With the default configuration, JBoss Messaging binds two connection
+ factories in JNDI at startup.</para>
<para>The first connection factory is the default non-clustered connection
- factory and is bound into the following JNDI contexts:
+ factory, and is bound into the following JNDI contexts:
<literal>/ConnectionFactory, /XAConnectionFactory,
java:/ConnectionFactory, java:/XAConnectionFactory</literal>. This
connection factory is provided to maintain compatibility with applications
- originally written against JBoss MQ which has no automatic failover or
+ originally written against JBoss MQ, which has no automatic failover or
load balancing. This connection factory should be used if you do not
- require client side automatic failover or load balancing.</para>
+ require client-side automatic failover or load balancing.</para>
<para>The second connection factory is the default clustered connection
- factory and is bound into the following JNDI contexts
+ factory, and is bound into the following JNDI contexts
<literal>/ClusteredConnectionFactory, /ClusteredXAConnectionFactory,
java:/ClusteredConnectionFactory,
java:/ClusteredXAConnectionFactory</literal>.</para>
<para>You may want to configure additional connection factories, for
- instance if you want to provide a default client id for a connection
- factory, or if you want to bind it in different places in JNDI, if you
- want different connection factories to use different transports, or if you
- want to selective enable or disable load-balancing and/or automatic
+ instance, if you want to provide a default client ID for a connection
+ factory; if you want to bind it in different places in JNDI; if you
+ want different connection factories to use different transports; or if you
+ want to selectively enable or disable load-balancing and/or automatic
failover for a particular connection factory. Deploying a new connection
- factory is equivalent with adding a new ConnectionFactory MBean
- configuration to
- <filename>connection-factories-service.xml</filename>.</para>
+ factory is equivalent to adding a new ConnectionFactory MBean
+ configuration to <filename>connection-factories-service.xml</filename>.</para>
<para>It is also possible to create an entirely new service deployment
- descriptor <filename>xxx-service.xml</filename> altogether and deploy it
+ descriptor <filename>xxx-service.xml</filename> and deploy it
in <filename>$JBOSS_HOME/server/messaging/deploy</filename>.</para>
<para>Connection factories can support automatic failover and/or
- load-balancing by setting the corresponding attributes</para>
+ load-balancing by setting the corresponding attributes.</para>
<para>An example connection factory configuration is presented
below:</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>
+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="JNDIBindings">
+<bindings>
+<binding>/MyConnectionFactory</binding>
+<binding>/factories/cf</binding>
+</bindings>
+</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="ClientID">myClientID</attribute>
- <attribute name="SlowConsumers">false</attribute>
-
- <attribute name="StrictTck">true</attribute>
-
- <attribute name="SendAcksAsync">false</attribute>
+<attribute name="SupportsFailover">true</attribute>
- <attribute name="DefaultTempQueueFullSize">50000</attribute>
-
- <attribute name="DefaultTempQueuePageSize">1000</attribute>
-
- <attribute name="DefaultTempQueueDownCacheSize">1000</attribute>
-
- <attribute name="DupsOKBatchSize">10000</attribute>
- </mbean>
-
+<attribute name="SupportsLoadBalancing">false</attribute>
- </programlisting>
+<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 above example would create a connection factory with
- pre-configured client ID <literal>myClientID</literal> and bind the
+ pre-configured client ID <literal>myClientID</literal>, and bind the
connection factory in two places in the JNDI tree:
<literal>/MyConnectionFactory</literal> and
<literal>/factories/cf</literal>. The connection factory overrides the
default values for PreFetchSize, DefaultTempQueueFullSize,
- DefaultTempQueuePageSize, DefaultTempQueueDownCacheSize and
- DupsOKBatchSize, SupportsFailover, SupportsLoadBalancing and
- LoadBalancingFactory. 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
+ DefaultTempQueuePageSize, DefaultTempQueueDownCacheSize, DupsOKBatchSize, SupportsFailover, SupportsLoadBalancing, and LoadBalancingFactory. 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>We now discuss the MBean attributes of the ConnectionFactory
- MBean</title>
+ MBean.</title>
<section id="conf.connectionfactory.attributes.clientid">
<title>ClientID</title>
- <para>Connection factories can be pre-configured with a client id. Any
+ <para>Connection factories can be pre-configured with a client ID. Any
connections created using this connection factory will obtain this
- client id</para>
+ client ID.</para>
</section>
<section id="conf.connectionfactory.attributes.jndibindings">
<title>JNDIBindings</title>
- <para>The list of the JNDI bindings for this connection factory</para>
+ <para>The list of the JNDI bindings for this connection factory.</para>
</section>
<section id="conf.connectionfactory.attributes.prefetchsize">
<title>PrefetchSize</title>
- <para>This parameter specifies the window size in numbers of messages,
+ <para>This parameter specifies the window size, in number of messages,
for consumer flow control. The window size determines the number of
- messages a server can send to a consumer without blocking. Each
+ messages a server can send to a consumer before being blocked. Each
consumer maintains a buffer of messages from which it consumes. Please
note that TCP also implements its own flow control, so if you set this
to too large a number, then the TCP window size may be hit before the
@@ -2160,9 +2095,9 @@
<title>SlowConsumers</title>
<para>If you have very slow consumers, then you probably want to make
- sure they don't buffer any messages. Since this can prevent them from
+ sure they don't buffer any messages, since this can prevent them from
being consumed by faster consumers. Setting this to true is equivalent
- to setting PrefetchSize to 1</para>
+ to setting PrefetchSize to 1.</para>
</section>
<section id="conf.connectionfactory.attributes.tckstrictbehavior">
@@ -2176,37 +2111,33 @@
<title>SendAcksAsync</title>
<para>Set this to true if you want acknowledgements to be sent
- asynchronously. This can speed up performance especially if you are
- using auto_acknowledge mode</para>
+ asynchronously. This can increase performance speed, especially if you are
+ using auto_acknowledge mode.</para>
</section>
<section id="conf.connectionfactory.attributes.tempqueuepaging">
<title>Temporary queue paging parameters</title>
-
- <para>DefaultTempQueueFullSize, DefaultTempQueuePageSize,
+
+ <para>DefaultTempQueueFullSize, DefaultTempQueuePageSize, and
DefaultTempQueueDownCacheSize are optional attributes that determine
- the default paging parameters to be used for any temporary
- destinations scoped to connections created using this connection
- factory. See the section on paging channels for more information on
- what these values mean. They will default to values of 200000, 2000
- and 2000 respectively if ommitted.</para>
+ the default paging parameters for any temporary destinations scoped to connections created using this connection factory. See the section on paging channels for more information on what these values mean. They will default to values of 200000, 2000 and 2000 respectively, if omitted.</para>
</section>
<section id="conf.connectionfactory.attributes.dupsokbatchsize">
<title>DupsOKBatchSize</title>
<para>When using a session with acknowledge mode of
- DUPS_OK_ACKNOWLEDGE this setting determines how many acknowledgments
+ DUPS_OK_ACKNOWLEDGE, this setting determines how many acknowledgments
it will buffer locally before sending. The default value is
- <literal>2000</literal></para>
+ <literal>2000</literal>.</para>
</section>
<section id="conf.connectionfactory.attributes.supportsloadbalancing">
<title>SupportsLoadBalancing</title>
<para>When using a connection factory with a clustered JBoss Messaging
- installation you can choose whether to enable client side connection
- load-balancing. This is determined by setting the attribute
+ installation, you can choose whether to enable client-side connection
+ load balancing. This is determined by setting the attribute
supportsLoadBalancing on the connection factory.</para>
<para>If load balancing is enabled on a connection factory then any
@@ -2214,38 +2145,34 @@
across the nodes of the cluster. Once a connection is created on a
particular node, it stays on that node.</para>
- <para>The exact policy that determines how connections are load
- balanced is determined by the LoadBalancingFactory attribute</para>
+ <para>The exact policy that determines how connections are load-balanced is determined by the LoadBalancingFactory attribute.</para>
- <para>The default value is <literal>false</literal></para>
+ <para>The default value is <literal>false</literal>.</para>
</section>
<section id="conf.connectionfactory.attributes.supportsfailover">
<title>SupportsFailover</title>
<para>When using a connection factory with a clustered JBoss Messaging
- installation you can choose whether to enable client side automatic
+ installation, you can choose whether to enable client-side automatic
failover. This is determined by setting the attribute supportsFailover
on the connection factory.</para>
<para>If automatic failover is enabled on a connection factory, then
- if a connection problem is detected with the connection then JBoss
- Messaging will automatically and transparently failover to another
- node in the cluster.</para>
+ if a connection problem is detected, JBoss Messaging will automatically and transparently failover to another node in the cluster.</para>
- <para>The failover is transparent meaning the user can carry on using
- the sessions, consumers, producers and connection objects as
- before.</para>
+ <para>The failover is transparent, meaning that the user can carry on using
+ the sessions, consumers, producers and connection objects as before.</para>
- <para>If automatic failover is not required, then this attribute can
- be set to false. With automatic failover disabled it is up to the user
- code to catch connection exceptions in synchronous JMS operations and
+ <para>If automatic failover is not required, this attribute can
+ be set to false. With automatic failover disabled, it is up to the user
+ code to catch connection exceptions in synchronous JMS operations, and
install a JMS ExceptionListener to catch exceptions asynchronously.
- When a connection is caught, the client side code should lookup a new
+ When a connection is caught, the client-side code should lookup a new
connection factory using HAJNDI and recreate the connection using
that.</para>
- <para>The default value is <literal>false</literal></para>
+ <para>The default value is <literal>false</literal>.</para>
</section>
<section id="conf.connectionfactory.attributes.disableremotingchecks">
@@ -2253,28 +2180,26 @@
<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 the values and for many
- of them there's rarely a good reason to change them. To disable such
- sanity checking set this to false.
+ values. JBoss Messaging is very sensitive to its values, and few of them need ever be changed. To disable such sanity checking, set this to false.
<warning>
- <para>There is rarely a good reason to disable checking. Only do so if you are absolutely sure in what you are doing </para>
+ <para>There is rarely a good reason to disable checking. Only do so if you are absolutely sure in what you are doing.</para>
</warning></para>
- <para>The default value is <literal>false</literal></para>
+ <para>The default value is <literal>false</literal>.</para>
</section>
<section id="conf.connectionfactory.attributes.loadbalancingfactory">
<title>LoadBalancingFactory</title>
- <para>If you are using a connection factory with client side load
- balancing then you can specify how the load balancing is implemented
+ <para>If you are using a connection factory with client-side load
+ balancing, you can specify how the load balancing is implemented
by overriding this attribute. The value must correspond to the name of
a class which implements the interface
org.jboss.jms.client.plugin.LoadBalancingFactory</para>
<para>The default value is
org.jboss.jms.client.plugin.RoundRobinLoadBalancingFactory, which load
- balances connetions across the cluster in a round-robin fashion</para>
+ balances connections across the cluster in a round-robin fashion.</para>
</section>
<section id="conf.connectionfactory.attributes.connector">
@@ -2282,12 +2207,8 @@
<para>This specifies which remoting connector this connection factory
uses. Different connection factories can use different
- connectors.</para>
-
- <para>For instance you could deploy one connection factory that
- creates connections that use the HTTP transport to communicate to the
- server and another that creates connections that use the bisocket
- transport to communicate.</para>
+ connectors. For instance, you could deploy one connection factory that
+ creates HTTP transport connections to the server, and another that creates bisocket transport connections.</para>
</section>
</section>
@@ -2299,9 +2220,9 @@
<section id="conf.connector">
<title>Configuring the remoting connector</title>
- <para>JBoss Messaging uses JBoss Remoting for all client to server
- communication. For full details of what JBoss Remoting is capable of and
- how it is configured please consult the JBoss Remoting
+ <para>JBoss Messaging uses JBoss Remoting for all client-to-server
+ communication. For full details of JBoss Remoting capabilities and
+ configuration information, please consult the JBoss Remoting
documentation.</para>
<para>The default configuration includes a single remoting connector which
@@ -2309,11 +2230,11 @@
can be configured to use its own connector.</para>
<para>The default connector is configured to use the remoting bisocket
- transport. The bisocket transport is a TCP socket based transport which
- only listens and accepts connections on the server side. I.e. connections
+ transport. The bisocket transport is a TCP socket-based transport which
+ only listens and accepts connections on the server side. That is, connections
are always initiated from the client side. This means it works well in
- typical firewall scenarios where only inbound connections are allowed on
- the server. Or where onlu outbound connections are allowed from the
+ 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 where a higher
@@ -2321,101 +2242,101 @@
<para>The other supported transport is the HTTP transport. This uses the
HTTP protocol to communicate between client and server. Data is received
- on the client by the client periodically polling the server for messages.
- This transport is well suited to situations where there is a firewall
- between client and server which only allows incoming HTTP traffic on the
- server. Please note this transport will not be as performant as the
- bisocket transport due to the nature of polling and the HTTP protocl. Also
- please note it is not designed for high load situations.</para>
+ when the client polls the server for messages periodically. This transport is well suited to situations where there is a firewall between client and server that only allows incoming HTTP traffic on the server. Please note that this transport will not be as performant as the bisocket transport due to the nature of polling and the HTTP protocol. Also please note that it is not designed for high-load situations.</para>
<para>No other remoting transports are currently supported by JBoss
- Messaging</para>
+ Messaging.</para>
<para>You can look at remoting configuration under:</para>
<para><JBoss>/server/<YourMessagingServer>/deploy/jboss-messaging.sar/remoting-bisocket-service.xml</para>
- <para>Here is an example bisocket remoting configuration: <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>
+ <para>Here is an example bisocket remoting configuration:</para>
+<programlisting>
+<config>
+<invoker transport="bisocket">
- <!-- Number of seconds to wait for a connection in the client pool to become free -->
- <attribute name="numberOfRetries" isParam="true">10</attribute>
+<!-- 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>
- <!-- 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>
+<!-- Periodicity of client pings. Server window by default is twice this figure -->
+<attribute name="clientLeasePeriod" isParam="true">10000</attribute>
- <para>Please note that some of the attributes should not be changed unless
- you know exactly what you are doing. We will discuss the attributes that
- you may have a good reason to change:</para>
+<!-- Number of seconds to wait for a connection in the client pool to become free -->
+<attribute name="numberOfRetries" isParam="true">10</attribute>
- <itemizedlist>
- <listitem>
- <para>clientLeasePeriod - Clients periodically send heartbeats to the server to tell the server they are still alive. If the server does not receive a heartbeat after a certain time it will close down the connection and remove all resources on the server corresponding to the client's session. The clientLeasePeriod determines the period of heartbeats. The server will (by default) close a client if it does not receive a heartbeat in 2 * clientLeasePeriod ms. The actual factor gets automatically resized according to system load. The value is in milliseconds. The defaut value is 10000 ms. </para>
- </listitem>
+<!-- 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>
- <listitem>
- <para>numberOfRetries - This effectively corresponds to the number of seconds JBoss Remoting will block on the client connection pool waiting for a connection to become free. If you have a very large number of sessions concurrently accessing the server from a client and you are experiencing issues due to not being able to obtain connections from the pool, you may want to consider increasing this value. </para>
- </listitem>
+<!-- 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>
+-->
- <listitem>
- <para>clientMaxPoolSize - JBoss Remoting maintains a client side pool of TCP connections on which to service requests. If you have a very large number of sessions concurrently accessing the server from a client and you are experiencing issues due to not being able to obtain connections from the pool in a timely manner, you may want to consider increasing this value. </para>
- </listitem>
+</invoker>
+<handlers>
+<handler subsystem="JMS">org.jboss.jms.server.remoting.JMSServerInvocationHandler</handler>
+</handlers>
+</config>
+ </programlisting>
- <listitem>
- <para>secondaryBindPort - The bisocket transport uses control connections to pass control messages between server and client. If you want to work behind a firewall you may want to specify a particular value for this according to your firewall configuration. This is the address the secondary ServerSocket binds to </para>
- </listitem>
+ <para>Please note that some of the attributes should not be changed unless
+ you know exactly what you are doing. Some attributes that you may have good reason to change are:</para>
+
+ <variablelist>
+ <varlistentry>
+ <term>clientLeasePeriod</term>
+ <listitem><para>Clients periodically send heartbeats to the server to inform the server that they are still alive. If the server does not receive a heartbeat after a certain time period, it will close down the connection and remove all resources on the server corresponding to the client's session. The clientLeasePeriod determines the period between heartbeats. The server will (by default) close a client if it does not receive a heartbeat in 2 * clientLeasePeriod ms. The actual factor is automatically resized according to system load. The value is in milliseconds. The default value is 10000 ms.</para></listitem>
+ </varlistentry>
- <listitem>
- <para>secondaryConnectPort - This is the port the client uses to connect. You may want to specify this to allow clients to work with NAT routers. </para>
- </listitem>
+ <varlistentry>
+ <term>numberOfRetries</term>
+ <listitem><para>This effectively corresponds to the number of seconds JBoss Remoting will block on the client connection pool when waiting for a connection to become free. If you have a very large number of sessions concurrently accessing the server from a client, and you are experiencing difficulty in obtaining connections from the pool, you may wish to increase this value.</para></listitem>
+ </varlistentry>
- <listitem>
- <para>maxPoolSize - This is the number of threads used on the server side to service requests. </para>
- </listitem>
- </itemizedlist>
+ <varlistentry>
+ <term>clientMaxPoolSize</term>
+ <listitem><para>JBoss Remoting maintains a client-side pool of TCP connections on which to service requests. If you have a very large number of sessions concurrently accessing the server from a client and you are experiencing difficulty in obtaining connections from the pool in a timely manner, you may wish to increase this value. </para></listitem>
+ </varlistentry>
- <para>By default JBoss Messaging binds to ${jboss.bind.address} which can
+ <varlistentry>
+ <term>secondaryBindPort</term>
+ <listitem><para>The bisocket transport uses control connections to pass control messages between server and client. If you want to work behind a firewall, you may want to specify a particular value for this, according to your firewall configuration. The secondary ServerSocket binds to this address.</para></listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>secondaryConnectPort</term>
+ <listitem><para>This is the port the client uses to connect. You may want to specify this to allow clients to work with NAT routers. </para></listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>maxPoolSize</term>
+ <listitem><para>This is the number of threads used on the server side to service requests. </para></listitem>
+ </varlistentry>
+ </variablelist>
+
+ <para>By default, JBoss Messaging binds to ${jboss.bind.address}, which can
be defined by: ./run.sh -c <yourconfig> -b yourIP.</para>
- <para>You can change remoting-bisocket-service.xml if you want for example
- use a different communication port.</para>
+ <para>If necessary, you can change remoting-bisocket-service.xml, for example, if you want to use a different communication port.</para>
<warning>
- <para>There is rarely a good reason to change values in the the bisocket or sslbisocket connector configuration apart from clientLeasePeriod, clientMaxPoolSize, maxRetries, numberOfRetries, secondaryBindPort or secondaryConnectPort. Changing them can cause JBoss Messaging to stop functioning correctly. </para>
+ <para>There is rarely a good reason to change values in the the bisocket or sslbisocket connector configuration, apart from clientLeasePeriod, clientMaxPoolSize, maxRetries, numberOfRetries, secondaryBindPort or secondaryConnectPort. Changing values other than those listed can cause JBoss Messaging to cease functioning correctly.</para>
</warning>
</section>
@@ -2424,19 +2345,17 @@
<section id="conf.servicebindingmanager">
<title>ServiceBindingManager</title>
- <para>The service binding manager on JBoss is used to provide multiple application servers instances running on the same IP using different port ranges,
- which is very useful during development. You could have multiple IPs on the same server and bind each server on a different IP if you wanted to deal with OS configs,
- but case you prefer not dealing with OS configs you have the option of using the ServiceBindingManager.</para>
+ <para>The ServiceBindingManager on JBoss is used to provide multiple application server instances running on the same IP using different port ranges. This is very useful during development: if you want to deal with OS configurations, you can have multiple IPs on the same server and bind each server on a different IP. Otherwise, use the ServiceBindingManager.</para>
- <para>On JBoss4 you must match the remoting configs accordingly to remoting-bisocket-service.xml. </para>
+ <para>On JBoss4 you must match the remoting configurations accordingly to remoting-bisocket-service.xml. </para>
- <para>If you are using a newer version of JBM in an older version of JBAS
+ <para>If you are using a newer version of JBM in an older version of JBAS,
then the example bindings in the AS distribution may well be out of date.
It is therefore imperative that the relevant sections are overwritten with
the remoting configuration from the JBM distribution.</para>
- <para>See the chapter on installation for a description of how to set-up
- the service binding manager for JBoss Messaging</para>
+ <para>See the chapter on installation for a description of how to set up
+ the service binding manager for JBoss Messaging.</para>
</section>
<!-- End conf.callback -->
Modified: projects/eap-docs/tags/JBoss_Messaging_User_Guide_EAP_5_0_0/en-US/installation.xml
===================================================================
--- projects/eap-docs/tags/JBoss_Messaging_User_Guide_EAP_5_0_0/en-US/installation.xml 2009-04-30 17:22:52 UTC (rev 6641)
+++ projects/eap-docs/tags/JBoss_Messaging_User_Guide_EAP_5_0_0/en-US/installation.xml 2009-05-01 03:05:47 UTC (rev 6642)
@@ -8,28 +8,28 @@
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.
+ Please note that JBoss EAP 4.3 and JBoss 5 comes with JBoss Messaging pre-installed as the default JMS provider. If you are using either of these, 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.
+ However, JBoss AS 4.2 ships with JBossMQ as the default JMS provider. In order to use the JBoss AS instance with JBoss Messaging, you need to perform the installation procedure described below.
</para>
<note>
- <para>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.</para>
+ <para>A JBossMQ and a JBoss Messaging instance cannot coexist 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.</para>
</note>
<note>
<para>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.</para>
</note>
<note>
- <para>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. </para>
+ <para>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. </para>
</note>
<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>
+ <para>In this section, we present two different methods of installing JBoss Messaging in JBoss AS 4.2.</para>
<itemizedlist>
<listitem>
- <para>If you have a completely clean JBoss AS 4.2.0 installation then you can do an <xref linkend="install.automated" />. </para>
+ <para>If you have a completely clean JBoss AS 4.2.0 installation then you can do an <xref linkend="install.automated" />.</para>
</listitem>
<listitem>
<para>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" />.</para>
@@ -44,67 +44,64 @@
</note>
<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>Set up the <literal>JBOSS_HOME</literal> environment variable such that it points 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>
+ <para>If you want to create a simple non-clustered installation 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>
+ <para>If you want to create a clustered installation based on the all configuration, or to 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
+ <literal>messaging-node0</literal> with your preferred name for the configuration. If you want several cluster nodes on
+ the same machine, for example, 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>
+ <para>The messaging.config.source variable determines which JBoss AS configuration (for example, default or all) to use as the base for installation.</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>
</itemizedlist>
- <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>For the rest of the procedure, we assume JBOSS_CONFIG refers to your new messaging configuration (for example, messaging-node0 or messaging).</para>
- <para>You don't actually have to create an environment variable
+ <note><para>You do not actually have to create an environment variable
<literal>JBOSS_CONFIG</literal>, this is just used in the installation
- instructions to describe the steps</para>
+ instructions to describe the steps.</para></note>
<itemizedlist>
<listitem>
<warning>
- <para>For a clustered installation it is mandatory that a
+ <para>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
+ 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.</para>
+ not replaced, clustering will not work.</para>
</warning>
<itemizedlist>
<listitem>
<para>Replace
<literal>$JBOSS_CONFIG/deploy/jboss-messaging.sar/hsqldb-persistence-service.xml</literal>
- by the <literal>databasename>-persistence-service</literal>
+ with the <literal>databasename>-persistence-service</literal>
from
- <literal><downloadPackage>/examples/config.</literal>. For
- instance <literal>mysql-persistence-service.xml</literal>
+ <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>
+ <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><para> and
- copying to <literal>$JBOSS_CONFIG/deploy</literal> JBoss
- Messaging uses <literal>DefaultDS</literal> by default so you
- should configure your datasource to bind to that</para>
+ <para>Configure a JCA datasource by using an example from
+ <literal>$JBOSS_HOME/docs/examples/jca</literal> and
+ copying to <literal>$JBOSS_CONFIG/deploy</literal>. 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
@@ -114,7 +111,7 @@
<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>
+ database provider's web site.</para>
</listitem>
</itemizedlist>
</listitem>
@@ -122,7 +119,7 @@
<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
+ node MUST have a unique ID, including those just connected by
message bridges.</para>
<warning><para>Each node must have a unique
<literal>ServerPeerID</literal> irrespective of whether you are
@@ -130,11 +127,11 @@
</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>
+ box using the same IP address, for example, for development purposes, then
+ you can use the ServiceBindingManager as follows:</para>
<warning>
<para>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.
+ You should refer to the JBoss5 documentation about how to administer the new BindingManager if you are using JBoss5.
</para>
</warning>
<itemizedlist>
@@ -143,7 +140,7 @@
$JBOSS_CONFIG/conf/jboss-service.xml</para>
</listitem>
<listitem>
- <para>Specify the desired port rage (e.g. ports-01, ports-02...
+ <para>Specify the desired port range (e.g. ports-01, ports-02...
etc)</para>
</listitem>
<listitem>
@@ -151,69 +148,64 @@
$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>
+<service-config name="jboss.messaging:service=Connector,transport=bisocket"
- <!-- Number of seconds to wait for a connection in the client pool to become free -->
- <attribute name="numberOfRetries" isParam="true">10</attribute>
+delegateClass="org.jboss.services.binding.AttributeMappingDelegate">
+<delegate-config>
+<attribute name="Configuration"><![CDATA[
+<config>
+<invoker transport="bisocket">
- <!-- 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>
+<!-- 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>
- <para>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</para>
+ <para>The above configuration only applies to JBoss 4.2 and EAP 4.3. On EAP4.3 and JBOSS 4.2, you must ensure that the configuration (like above) is identical to that in
+ <literal>remoting-bisocket-service.xml</literal>, with the
+ exception of the actual serverBindPort which must be
+ different for each port range. Please note that the default
+ JBoss Messaging service binding manager configuration shipped with JBAS 4.2.0 in <literal>sample-bindings.xml</literal> may be out of date, and you will need to copy the config from <literal>remoting-bisocket-service.xml</literal>. DO NOT just copy and paste from the above example - copy it from the JBoss Messaging
+ distribution. On JBoss5, the ports are controlled by
+ system-property substitution, hence you do not need to worry about copying the configuration into bindings.xml</para>
</warning>
<para>You should ensure that each node is configured to use a
different ports range.</para>
@@ -223,22 +215,22 @@
<listitem>
<para>There are few extra steps at <xref linkend="install.extra-steps" /></para>
</listitem>
- <listitem><para>That's it</para></listitem>
+ <listitem><para>That's it.</para></listitem>
</itemizedlist>
</section>
<section id="install.manual">
<title>Manual Installation</title>
<note>
- <para>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 </para>
+ <para>This installation procedure should be performed if you are installing into a JBoss AS configuration that you have altered 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.</para>
</note>
<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
+ <note><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>
+ instructions to describe the steps.</para></note>
<itemizedlist>
<listitem>
<para>Move
@@ -258,23 +250,23 @@
</listitem>
<listitem>
<para>Add a security policy called "messaging" on
- $JBOSS_CONFIG/config/login-config.xml. You could use this as an
+ $JBOSS_CONFIG/config/login-config.xml. You could use the following 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>
+<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
+ <para>In case you are using the above policy, you should also create
+ <literal>messaging-users.properties</literal> and
+ <literal>messaging-roles.properties</literal> files in the
<literal>$JBOSS_CONFIG/config/props/</literal> directory.</para>
<note>
<para>You can find an example
@@ -285,38 +277,38 @@
directory.</para>
</note>
<programlisting>
- # messaging-roles.properties
- # Add roles as you like
- # user=role1,role2,...
- #
- guest=guest
+# messaging-roles.properties
+# Add roles as you like
+# user=role1,role2,...
+#
+guest=guest
</programlisting>
<programlisting>
- # messaging-users.properties
+# messaging-users.properties
- # Add users as you like
- # user=password
- #
- guest=guest
+# 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>
+ <para>JBoss Messaging should be deployed unzipped (exploded) so that you
+ have easy access to the configuration files 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>
+ accessible to other services, for example, the JBoss Transactions Recovery
+ Manager.</para>
</listitem>
<listitem>
<warning>
- <para>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.</para>
+ <para>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, clustering will not work.</para>
</warning>
<itemizedlist>
<listitem>
@@ -326,14 +318,14 @@
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>
+ <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> and copying to <literal>$JBOSS_CONFIG/deploy</literal></para>
+ <para>Configure a JCA datasource using an example from <literal>$JBOSS_HOME/docs/examples/jca</literal>, and copy to <literal>$JBOSS_CONFIG/deploy</literal></para>
<para>JBoss Messaging uses <literal>DefaultDS</literal> by
- default so you should configure your datasource to bind to
- that</para>
+ default, so you should configure your datasource to bind to
+ that.</para>
</listitem>
<listitem>
<para>Remove hsqldb-ds.xml from
@@ -344,7 +336,7 @@
<literal>$JBOSS_CONFIG/lib</literal></para>
<para>Your database driver can probably be downloaded from your
- database provider's web site</para>
+ database provider's web site.</para>
</listitem>
</itemizedlist>
</listitem>
@@ -360,7 +352,7 @@
</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
+ box using the same IP address, for example, for development purposes, then
you can use the ServiceBindingManager to do this as follows:</para>
<itemizedlist>
<listitem>
@@ -369,8 +361,7 @@
</listitem>
<listitem>
- <para>Specify the desired port rage (e.g. ports-01, ports-02...
- etc)</para>
+ <para>Specify the desired port range (for example, ports-01, ports-02... etc.)</para>
</listitem>
<listitem>
@@ -380,72 +371,63 @@
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>
+<service-config name="jboss.messaging:service=Connector,transport=bisocket"
- <!-- Number of seconds to wait for a connection in the client pool to become free -->
- <attribute name="numberOfRetries" isParam="true">10</attribute>
+delegateClass="org.jboss.services.binding.AttributeMappingDelegate">
+<delegate-config>
+<attribute name="Configuration"><![CDATA[
+<config>
+<invoker transport="bisocket">
- <!-- 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>
- <para>You must ensure that the config (like above) is identical to that in
+<!-- 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>
- <literal>remoting-bisocket-service.xml</literal>
+<!-- Periodicity of client pings. Server window by default is twice this figure -->
+<attribute name="clientLeasePeriod" isParam="true">10000</attribute>
- 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
+<!-- Number of seconds to wait for a connection in the client pool to become free -->
+<attribute name="numberOfRetries" isParam="true">10</attribute>
- <literal>sample-bindings.xml</literal>
+<!-- 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>
- shipped with JBAS 4.2.0 may be out of date and you will need to copy the config from
+<!-- 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>
+-->
- <literal>remoting-bisocket-service.xml. DO NOT just copy and
+</invoker>
+<handlers>
+<handler subsystem="JMS">org.jboss.jms.server.remoting.JMSServerInvocationHandler</handler>
+</handlers>
+</config>
+]]></attribute>
+</delegate-config>
+<binding port="4657"/>
+</service-config>
+ </programlisting>
+ <warning>
+ <para>You must ensure that the configuration (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 port range. Please note that the default JBoss Messaging service binding manager configuration in <literal>sample-bindings.xml</literal> shipped with JBAS 4.2.0 may be out of date and you will need to copy the configuration from <literal>remoting-bisocket-service.xml. DO NOT just copy and
paste from the above example - copy it from the JBoss
Messaging distribution.</literal></para>
</warning>
<para>You should ensure that each node is configured to use a
- different ports range.</para>
+ different port range.</para>
</listitem>
</itemizedlist>
</listitem>
@@ -453,7 +435,7 @@
<para>There are few extra steps at <xref linkend="install.extra-steps" /></para>
</listitem>
<listitem>
- <para>That's it </para>
+ <para>That's it.</para>
</listitem>
</itemizedlist>
</section>
@@ -462,19 +444,21 @@
<title>Extra steps to complete your installation</title>
<itemizedlist>
<listitem>
- <warning><para>SECURITY RISK! To avoid a security risk, you MUST specify
+ <warning>
+ <title>Security Risk!</title>
+ <para>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
+ configuration file (messaging-service.xml). If you do not specify a value, the
+ default value will be used. Any person who knows the default
value will be able to access to all destinations on the server.
The password chosen should only be exposed to
- administrators</para>
+ administrators.</para>
</warning>
</listitem>
<listitem>
<note>
- <para>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:
+ <para>JBoss Messaging 1.4.3.GA requires specific versions
+ of jboss-remoting.jar if used outside 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.</para>
</note>
@@ -485,9 +469,9 @@
<itemizedlist>
<listitem>
<para>Edit <literal>$JBOSS_CONFIG/deploy/jms-ds.xml</literal> and
- replace jboss.mq by jboss.messaging on every occurrence</para>
+ replace jboss.mq with jboss.messaging on every occurrence.</para>
- <para>If you are in a clustered installation, then do the above with
+ <para>If you are in a clustered installation, then do the same with
the file
<literal>$JBOSS_CONFIG/deploy/hajndi-jms-ds.xml</literal></para>
</listitem>
@@ -495,7 +479,7 @@
<listitem>
<para>Edit <literal>$JBOSS_CONFIG/conf/standardjboss.xml</literal>
and set <literal>CreateJBossMQDestination</literal> to false on
- every occurrence</para>
+ every occurrence.</para>
<para>Make sure it looks like this:</para>
@@ -503,8 +487,8 @@
<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
+ <para>Those proxies will try to create a destination on JBossMQ if
+ they can't find it on JNDI, which could cause some errors related to
JBoss MQ.</para>
</listitem>
@@ -513,13 +497,13 @@
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"
+<!-- ==================================================================== -->
+<!-- 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>
+... Remove this line ...
+<attribute name="JMSService">jboss.mq:service=DestinationManager</attribute>
</programlisting>
</listitem>
@@ -528,34 +512,34 @@
and remove jboss-mq security policies</para>
<programlisting>
- ### Remove these lines:
+### 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 -->
+<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>
- -->
+<!-- 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>
@@ -566,110 +550,106 @@
<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>
+ <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>
+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>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>
+ similar to that of a non-clustered installation. (For a clustered installation,
+ you will also see extra cluster-related output.)</para>
<programlisting>
- ....
- 13:19:14,914 WARN [JDBCPersistenceManager]
+....
+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.
+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
+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>
- <para>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.</para>
+ <para>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 issues that occur when using this database.</para>
</note>
<warning>
- <para>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 Section 6.2, <emphasis>Changing the Database</emphasis> for details about replacing Hypersonic. </para>
+ <para>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 Section 6.2, <emphasis>Changing the Database</emphasis> for details about replacing Hypersonic. </para>
</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
+ "out of the box" and could be used to validate a new installation. These
+ examples send 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
+ <para>To run the example and validate the installation, open a 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
@@ -679,73 +659,70 @@
<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
+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
+[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
+identify:
+[echo] ###########################################################################
+[echo] # Running the QUEUE example #
+[echo] ###########################################################################
+[echo] The queue: testQueue
+[echo] The client jar: ../../../output/lib/jboss-messaging-client.jar
- sanity-check:
+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
+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
+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)
+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] #####################
+[java] #####################
+[java] ### SUCCESS! ###
+[java] #####################
- BUILD SUCCESSFUL
- Total time: 5 seconds
- [tim at Vigor14 queue]$
+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 Chapter 5, <emphasis>Running the Examples</emphasis>, we will have a look at each of those
- examples.</para>
+ <filename>mdb</filename>, <filename>stateless</filename>, etc.). In Chapter 5, <emphasis>Running the Examples</emphasis>, we will 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
+ application server, you will need to ensure the following jar files are on the
client classpath:</para>
- <itemizedlist>
- <listitem>
- <note>
+ <note>
<para>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.</para>
- </note>
- </listitem>
+ </note>
+ <itemizedlist>
<listitem>
<para>jboss-messaging-client.jar - This is available in the messaging
- distribution</para>
+ distribution.</para>
</listitem>
<listitem>
<para>jbossall-client.jar - This is available in your
@@ -755,8 +732,7 @@
<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>
+ <para>(For AOP, sometimes a specific JAR is necessary for your particular JVM. Use the most convenient for you.)</para>
</listitem>
<listitem>
<para>$JBOSS_HOME/server/<SERVER_NAME>/lib/javassist.jar</para>
@@ -778,7 +754,7 @@
<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
+ application server, you will need to ensure the following jar files are on the
client classpath:</para>
<itemizedlist>
<listitem>
@@ -829,243 +805,214 @@
<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>
+ JBossMQ to JBM (JBoss Messaging). Many Enterprise systems are complex, with multiple applications, and cannot be migrated from JBossMQ to JBM all at once.</para>
+
+ <para>For example, suppose your business sells items. Some are made by you directly, and some are farmed out to other distributors. If your ordering system is JBossMQ-based, customer orders will be queued for processing with JBossMQ, but you will also need a queue for orders produced directly by you, and orders produced by your other distributors. Therefore, you will use MDBs in three separate places in your operation. If you want to perform a staged migration from JBossMQ to JBM, both programs are required to work together, and that is where the JBM bridge comes in: it takes messages from one queue/topic and transfers them to another queue/topic. This assists migration in that it allows you to automatically pull messages from your JBossMQ queues and push them into your JBM queues - or vice versa. In this case, to replace the ordering side (producer) with JBM, we push messages into the JBM order queue, and set up JBM bridge to send those messages to the JBossMQ order qu!
eue. (The rest of your processing is handled as normal.) If you want to leave your ordering system intact, but want JBM and EJB3 MDBs to process the orders, you can simply set the bridge to pull messages from your old client and push them ito the JBM order queue.</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
+ <para>The bridge 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>
<para>You have one JBoss instance set up for JBoss Messaging and One
- Jboss instance set up that has your old JBoss MQ on it.</para>
+ JBoss instance set up that has your old JBoss MQ on it.</para>
</listitem>
<listitem><para>We are copying messages from JBossMQ(Source) to
JBM(Target)</para></listitem>
</itemizedlist>
<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>
+<?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
+ <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 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
+ <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>
+ JBM machine (server/messaging/lib).</para>
- <note><para>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</para></note>
+ <note><para>Substitute your messaging server configuration. 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 be unable to start.</para></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>
+ server/messaging/deploy directory on your target (JBM) machine.</para>
- <para>Here is an example of the provider to add.</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>
+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><para>you will need to change the java.naming.provider.url so that
+ <note><para>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.</para></note>
+ same. Keep your jms-ds.xml file open, because you will be adding
+ to it in the next step.</para></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>
+ 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>
+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><para>my target is the current JBM JMS Provider and the source is
- the JBossMQ remote provider. If you have a pretty stock system and
+ <note><para>The example target is the current JBM JMS Provider and the source is
+ the JBossMQ remote provider. If you have a basic 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
+ from JBM to JBossMQ, just switch the source and target
definitions.</para></note>
</listitem>
</itemizedlist>
- <para>Start the JBossMQ system and then just start the JBM system and
+ <para>Start the JBossMQ system and then 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
+ <!--<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 (that is, JBM has been installed using the default configuration), then
+ you can just copy the jms-ds.xml file and use it to replace the jms-ds.xml 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>
+ JBM and JBossMQ.</para>-->
</section>
</section>
</chapter>
\ No newline at end of file
Modified: projects/eap-docs/tags/JBoss_Messaging_User_Guide_EAP_5_0_0/en-US/introduction.xml
===================================================================
--- projects/eap-docs/tags/JBoss_Messaging_User_Guide_EAP_5_0_0/en-US/introduction.xml 2009-04-30 17:22:52 UTC (rev 6641)
+++ projects/eap-docs/tags/JBoss_Messaging_User_Guide_EAP_5_0_0/en-US/introduction.xml 2009-05-01 03:05:47 UTC (rev 6642)
@@ -7,13 +7,13 @@
<para>JBoss Messaging provides an open source and standards-based messaging
platform that brings enterprise-class messaging to the mass market.</para>
- <para>JBoss Messaging implements a high performance, robust messaging core
- that is designed to support the largest and most heavily utilized SOAs,
- enterprise service buses (ESBs) and other integration needs ranging from the
+ <para>JBoss Messaging implements a high-performance, robust messaging core
+ designed to support the largest and most heavily utilized SOAs,
+ enterprise service buses (ESBs) and other integration needs, ranging from the
simplest to the highest demand networks.</para>
<para>It will allow you to smoothly distribute your application load across
- your cluster, intelligently balancing and utilizing each nodes CPU cycles,
+ your cluster, intelligently balancing and utilizing each node's CPU cycles,
with no single point of failure, providing a highly scalable and performant
clustering implementation.</para>
@@ -28,18 +28,18 @@
<itemizedlist>
<listitem>
- <para>A fully compatible and Sun certified JMS 1.1 implementation,
+ <para>a fully compatible and Sun certified JMS 1.1 implementation,
that currently works with a standard 4.2 or later JBoss Application
- Server installation.</para>
+ Server installation;</para>
</listitem>
<listitem>
- <para>A strong focus on performance, reliability and scalability with
- high throughput and low latency.</para>
+ <para>a strong focus on performance, reliability and scalability with
+ high throughput and low latency; and</para>
</listitem>
<listitem>
- <para>A foundation for JBoss ESB for SOA initiatives; JBoss ESB uses
+ <para>a foundation for JBoss ESB for SOA initiatives. JBoss ESB uses
JBoss Messaging as its default JMS provider.</para>
</listitem>
</itemizedlist>
@@ -48,61 +48,60 @@
<itemizedlist>
<listitem>
- <para>Publish-subscribe and point-to-point messaging models</para>
+ <para>publish-subscribe and point-to-point messaging models;</para>
</listitem>
<listitem>
- <para>Persistent and non-persistent messages</para>
+ <para>persistent and non-persistent messages;</para>
</listitem>
<listitem>
- <para>Guaranteed message delivery that ensures that messages arrive
- once and only once where required</para>
+ <para>guaranteed message delivery that ensures messages arrive
+ once and only once where required;</para>
</listitem>
<listitem>
- <para>Transactional and reliable - supporting ACID semantics</para>
+ <para>transactional and reliable systems - supporting ACID semantics;</para>
</listitem>
<listitem>
- <para>Customizable security framework based on JAAS</para>
+ <para>a customizable security framework based on JAAS;</para>
</listitem>
<listitem>
- <para>Fully integrated with JBoss Transactions (formerly known as
- Arjuna JTA) for full transaction recoverability.</para>
+ <para>full integration with JBoss Transactions (formerly known as
+ Arjuna JTA) for full transaction recoverability;</para>
</listitem>
<listitem>
- <para>Extensive JMX management interface</para>
+ <para>an extensive JMX management interface;</para>
</listitem>
<listitem>
- <para>Support for most major databases including Oracle, DB2, Sybase, MS
- SQL Server, PostgreSQL and MySQL</para>
+ <para>support for most major databases, including Oracle, DB2, Sybase, MS
+ SQL Server, PostgreSQL, and MySQL;</para>
</listitem>
<listitem>
- <para>HTTP transport to allow use through firewalls that only allow
- HTTP traffic</para>
+ <para>HTTP transport, to allow use through firewalls that only allow
+ HTTP traffic;</para>
</listitem>
<listitem>
- <para>SSL transport</para>
+ <para>SSL transport;</para>
</listitem>
<listitem>
- <para>Configurable DLQs (Dead Letter Queues) and Expiry Queues</para>
+ <para>configurable DLQs (Dead Letter Queues) and Expiry Queues;</para>
</listitem>
<listitem>
- <para>Message statistics. Gives you a rolling historical view of what
- messages were delivered to what queues and subscriptions</para>
+ <para>message statistics, which allows a rolling historical view of which
+ messages were delivered to which queues and subscriptions; and</para>
</listitem>
<listitem>
- <para>Automatic paging of messages to storage. Allows the use of very
- large queues - too large to fit in memory at once</para>
+ <para>automatic paging of messages to storage, which enables the use of queues too large to fit in memory at once time.</para>
</listitem>
</itemizedlist>
@@ -145,9 +144,9 @@
<listitem>
<para>Fully transparent failover. When a server fails, your sessions
continue without exceptions on a new node as if nothing happened.
- (Fully configurable - If you don't want this you can fall back to
- exceptions being thrown and manually recreation of connections on
- another node)</para>
+ (Fully configurable - if you don't want this you can fall back to
+ exceptions being thrown and the manual recreation of connections on
+ another node.)</para>
</listitem>
<listitem>
@@ -161,7 +160,7 @@
<listitem>
<para>Message bridge. JBoss Messaging contains a message bridge
component which enables you to bridge messages between any two JMS1.1
- destinations on the same or physical separate locations. (E.g.
+ destinations on the local or physically separate locations (for example, those
separated by a WAN). This allows you to connect geographically
separate clusters, forming huge globally distributed logical queues
and topics.</para>
@@ -179,14 +178,14 @@
<para>JBoss Messaging does not have wire format compatibility with JBoss
MQ so it would be necessary to upgrade JBoss MQ clients with JBoss
- Messaging client jars</para>
+ Messaging client jars.</para>
<important>
- <para>Even if JBoss Messaging deployment descriptors are very similar to JBoss MQ deployment descriptors, they are
+ <para>Although JBoss Messaging deployment descriptors are very similar to JBoss MQ deployment descriptors, they are
<emphasis>not</emphasis>
- identical, so they will require some simple adjustments to get them to work with JBoss Messaging. Also, the database data model is completely different, so don't attempt to use JBoss Messaging with a JBoss MQ data schema and vice-versa. </para>
+ identical, so they will require some simple adjustments to work with JBoss Messaging. The database data models are completely incompatible, so do not attempt to use JBoss Messaging with a JBoss MQ data schema, or vice-versa. </para>
</important>
</section>
</chapter>
\ No newline at end of file
Modified: projects/eap-docs/tags/JBoss_Messaging_User_Guide_EAP_5_0_0/en-US/recovery_config.xml
===================================================================
--- projects/eap-docs/tags/JBoss_Messaging_User_Guide_EAP_5_0_0/en-US/recovery_config.xml 2009-04-30 17:22:52 UTC (rev 6641)
+++ projects/eap-docs/tags/JBoss_Messaging_User_Guide_EAP_5_0_0/en-US/recovery_config.xml 2009-05-01 03:05:47 UTC (rev 6642)
@@ -8,57 +8,57 @@
4.2.0 to handle XA recovery for JBoss Messaging resources.</para>
<para>JBoss Transactions recovery manager can easily be configured to
- continually poll for and recover JBoss Messaging XA resources, this provides
- an extremely high level of durability of transactions.</para>
+ continually poll for and recover JBoss Messaging XA resources. This provides
+ an extremely high level of transaction durability.</para>
<para>Enabling JBoss Transactions Recovery Manager to recover JBoss
Messaging resources is a very simple matter and involves adding a line to
the file ${JBOSS_CONFIG}/conf/jbossjta-properties.xml</para>
- <para>Here's an example section of a jbossjta-properties.xml file with the
- line added (note the whole file is not shown)</para>
+ <para>Here is an example section of a jbossjta-properties.xml file with the
+ line added. (The whole file is not shown.)</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 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>
+</properties>
</programlisting>
- <para>In the above example the recovery manager will attempt to recover JMS
- resources using the JMSProviderLoader "DefaultJMSProvider"</para>
+ <para>In the above example, the recovery manager will attempt to recover JMS
+ resources using the JMSProviderLoader "DefaultJMSProvider".</para>
<para>DefaultJMSProvider is the default JMS provider loader that ships with
- JBoss AS and is defined in jms-ds.xml (or hajndi-jms-ds.xml in a clustered
- configuration). If you want to recovery using a different JMS provider
- loader - e.g. one corresponding to a remote JMS provider then just add
+ JBoss AS, and is defined in jms-ds.xml (or hajndi-jms-ds.xml in a clustered
+ configuration). If you want to recover using a different JMS provider
+ loader, for example, one corresponding to a remote JMS provider, sjust add
another line and instead of DefaultJMSProvider specify the name of the
- remote JMS provider as specified in it's MBean configuration.</para>
+ remote JMS provider as specified in its MBean configuration.</para>
<para>For each line you add, the name must be unique, so you could specify
"com.arjuna.ats.jta.recovery.XAResourceRecovery.JBMESSAGING1",
"com.arjuna.ats.jta.recovery.XAResourceRecovery.JBMESSAGING2, ..."
etc.</para>
- <para>In actual fact, the recovery also should work with any JMS provider
- that implements recoverable XAResources (i.e. it properly implements
- XAResource.recover()) , not just JBoss Messaging</para>
+ <para>The recovery should also work with any JMS provider
+ that implements recoverable XAResources. (That is, it properly implements
+ XAResource.recover()) , not just JBoss Messaging.)</para>
- <para>Please note that to configure the recovery manager to recovery
- transactions from any node of the cluster it will be necessary to specify a
- line in the configuration for every node of the cluster</para>
+ <para>Please note that to configure the recovery manager to recover
+ transactions from any node of the cluster, it will be necessary to specify a
+ line in the configuration for every node of the cluster.</para>
</chapter>
\ No newline at end of file
Modified: projects/eap-docs/tags/JBoss_Messaging_User_Guide_EAP_5_0_0/en-US/runningexamples.xml
===================================================================
--- projects/eap-docs/tags/JBoss_Messaging_User_Guide_EAP_5_0_0/en-US/runningexamples.xml 2009-04-30 17:22:52 UTC (rev 6641)
+++ projects/eap-docs/tags/JBoss_Messaging_User_Guide_EAP_5_0_0/en-US/runningexamples.xml 2009-05-01 03:05:47 UTC (rev 6642)
@@ -15,96 +15,94 @@
<para>docs/example/queue</para>
<para>This example shows a simple send and receive to a remote queue
- using a JMS client</para>
+ using a JMS client.</para>
</listitem>
<listitem>
<para>docs/example/topic</para>
<para>This example shows a simple send and receive to a remote topic
- using a JMS client</para>
+ using a JMS client.</para>
</listitem>
<listitem>
<para>docs/example/mdb</para>
- <para>This example demonstrates usage of an EJB2.1 MDB with JBoss
- Messaging</para>
+ <para>This example demonstrates the use of an EJB2.1 MDB with JBoss
+ Messaging.</para>
</listitem>
<listitem>
<para>docs/example/ejb3mdb</para>
<para>This example demonstrates usage of an EJB3 MDB with JBoss
- Messaging</para>
+ Messaging.</para>
</listitem>
<listitem>
<para>docs/example/stateless</para>
<para>This example demonstrates an EJB2.1 stateless session bean
- interacting with JBoss Messaging</para>
+ interacting with JBoss Messaging.</para>
</listitem>
<listitem>
<para>docs/example/mdb-failure</para>
<para>This example demonstrates rollback and redelivery occuring with
- an EJB2.1 MDB</para>
+ an EJB2.1 MDB.</para>
</listitem>
<listitem>
<para>docs/example/secure-socket</para>
<para>This example demonstrates a JMS client interacting with a JBoss
- Messaging server using SSL encrypted transport</para>
+ Messaging server using SSL encrypted transport.</para>
</listitem>
<listitem>
<para>docs/example/http</para>
<para>This example demonstrates a JMS client interacting with a JBoss
- Messaging server tunneling traffic over the HTTP protocol</para>
+ Messaging server tunneling traffic over HTTP protocol.</para>
</listitem>
<listitem>
<para>docs/example/web-service</para>
<para>This example demonstrates JBoss web-service interacting with
- JBoss Messaging</para>
+ JBoss Messaging.</para>
</listitem>
<listitem>
<para>docs/example/distributed-queue</para>
<para>This example demonstrates a JMS client interacting with a JBoss
- Messaging distributed queue - it requires two JBoss AS instances to be
- running</para>
+ Messaging distributed queue. It requires two running JBoss AS instances.</para>
</listitem>
<listitem>
<para>docs/example/distributed-topic</para>
<para>This example demonstrates a JMS client interacting with a JBoss
- Messaging distributed topic - it requires two JBoss AS instances to be
- running</para>
+ Messaging distributed topic. It requires two running JBoss AS instances.</para>
</listitem>
<listitem>
<para>docs/example/stateless-clustered</para>
<para>This example demonstrates a JMS client interacting with
- clustered EJB2.1 stateless session bean, which in turn interactes with
+ clustered EJB2.1 stateless session bean, which in turn interacts with
JBoss Messaging. The example uses HAJNDI to lookup the connection
- factory</para>
+ factory.</para>
</listitem>
<listitem>
<para>docs/example/bridge</para>
<para>This example demonstrates using a message bridge. It deploys a
- message bridge in JBoss AS which then proceeds to move messages from a
- source to a target queue</para>
+ message bridge in JBoss AS, which then proceeds to move messages from a
+ source to a target queue.</para>
</listitem>
</itemizedlist></para>
@@ -114,13 +112,13 @@
<para>Make sure you start the JBoss server(s) before running the
examples!</para>
- <para>The non clustered examples expect a JBoss AS instance to be running
- with all the default settings</para>
+ <para>The non-clustered examples expect a JBoss AS instance to be running
+ with all the default settings.</para>
<para>The clustered examples expect two JBoss AS instances to running with
ports settings as per ports-01 and ports-02.</para>
<para>For each example, you can always override the default ports it will
try to connect to by editing jndi.properties in the particular example
- directory</para>
+ directory.</para>
</chapter>
\ No newline at end of file
More information about the jboss-cvs-commits
mailing list