[jboss-cvs] JBoss Messaging SVN: r2533 - in trunk/docs: userguide-1.2/en and 1 other directories.
jboss-cvs-commits at lists.jboss.org
jboss-cvs-commits at lists.jboss.org
Thu Mar 1 12:38:57 EST 2007
Author: timfox
Date: 2007-03-01 12:38:57 -0500 (Thu, 01 Mar 2007)
New Revision: 2533
Removed:
trunk/docs/clustering/
trunk/docs/gettingstarted/
trunk/docs/userguide-1.2/en/modules/CLUST_introduction.xml
Modified:
trunk/docs/userguide-1.2/en/master.xml
trunk/docs/userguide-1.2/en/modules/CLUST_configuration.xml
trunk/docs/userguide-1.2/en/modules/CLUST_overview.xml
trunk/docs/userguide-1.2/en/modules/UG12_configuration.xml
trunk/docs/userguide-1.2/en/modules/UG12_gettingstarted.xml
trunk/docs/userguide-1.2/en/modules/UG12_introduction.xml
trunk/docs/userguide-1.2/en/modules/UG12_runningexamples.xml
Log:
Updated docs
Modified: trunk/docs/userguide-1.2/en/master.xml
===================================================================
--- trunk/docs/userguide-1.2/en/master.xml 2007-03-01 10:52:35 UTC (rev 2532)
+++ trunk/docs/userguide-1.2/en/master.xml 2007-03-01 17:38:57 UTC (rev 2533)
@@ -1,46 +1,55 @@
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.3CR3//EN"
"../../../lib/docbook-support/support/docbook-dtd/docbookx.dtd" [
-<!ENTITY UG12_about SYSTEM "modules/UG12_about.xml">
-<!ENTITY UG12_introduction SYSTEM "modules/UG12_introduction.xml">
-<!ENTITY UG12_gettingstarted SYSTEM "modules/UG12_gettingstarted.xml">
-<!ENTITY UG12_installation SYSTEM "modules/UG12_installation.xml">
-<!ENTITY UG12_runningexamples SYSTEM "modules/UG12_runningexamples.xml">
-<!ENTITY UG12_configuration SYSTEM "modules/UG12_configuration.xml">
-<!ENTITY UG12_performance SYSTEM "modules/UG12_performance.xml">
-<!ENTITY C_about SYSTEM "modules/CLUST_about.xml">
-<!ENTITY C_introduction SYSTEM "modules/CLUST_introduction.xml">
+<!ENTITY about SYSTEM "modules/UG12_about.xml">
+<!ENTITY introduction SYSTEM "modules/UG12_introduction.xml">
<!ENTITY C_overview SYSTEM "modules/CLUST_overview.xml">
+<!ENTITY gettingstarted SYSTEM "modules/UG12_gettingstarted.xml">
+<!ENTITY NC_installation SYSTEM "modules/UG12_installation.xml">
<!ENTITY C_installation SYSTEM "modules/CLUST_installation.xml">
+<!ENTITY runningexamples SYSTEM "modules/UG12_runningexamples.xml">
+<!ENTITY configuration SYSTEM "modules/UG12_configuration.xml">
<!ENTITY C_configuration SYSTEM "modules/CLUST_configuration.xml">
+<!ENTITY performance SYSTEM "modules/UG12_performance.xml">
+
+
+<!ENTITY C_about SYSTEM "modules/CLUST_about.xml">
+<!ENTITY C_introduction SYSTEM "modules/CLUST_introduction.xml">
+
+
+
]>
<book lang="en">
<bookinfo>
<title>JBoss Messaging 1.2 User's Guide</title>
- <subtitle>A high performance JMS server for JBoss</subtitle>
+ <subtitle>The next generation enterprise messaging solution from JBoss</subtitle>
+
</bookinfo>
<toc></toc>
-
- &UG12_about;
-
- &UG12_introduction;
- &UG12_gettingstarted;
+ &about;
- &UG12_installation;
+ &introduction;
- &UG12_runningexamples;
+ &C_overview;
- &UG12_configuration;
-
- &UG12_performance;
+ &gettingstarted;
- &C_overview;
-
+ &NC_installation;
+
&C_installation;
-
+
+ &runningexamples;
+
+ &configuration;
+
&C_configuration;
+
+ &performance;
+
+
+
</book>
Modified: trunk/docs/userguide-1.2/en/modules/CLUST_configuration.xml
===================================================================
--- trunk/docs/userguide-1.2/en/modules/CLUST_configuration.xml 2007-03-01 10:52:35 UTC (rev 2532)
+++ trunk/docs/userguide-1.2/en/modules/CLUST_configuration.xml 2007-03-01 17:38:57 UTC (rev 2533)
@@ -3,208 +3,113 @@
<title>JBoss Messaging Clustering Configuration</title>
<para>
- In order to understand JBoss Messaging clustering configuration, we will start with a
- short clustering architectural overview, where we will identify "configuration areas",
- meaning architectural elements that have corresponding configuration files, and whose
- behavior can be changed through configuration.
+ In this chapter we will discuss how to configure JBoss Messaging clustering for different types of applications
</para>
- <section id="clustered_postoffice_configuration">
- <title>Clustered Post Office Configuration</title>
+ <para>
+ Most of JBoss messaging clustering configuration revolves around the following variable:
+ </para>
+ <itemizedlist>
+
+ <listitem>Choosing the cluster router policy</listitem>
+
+ <listitem>Choosing the message redistributon policy</listitem>
+
+ </itemizedlist>
+
+ <section id="clusterrouter">
+
+ <title>Choosing the cluster router policy</title>
+
<para>
- In JBoss Messaging 1.2.0, the JGroups configuration for each clustered Post Office instance
- is specified in the Post Office MBean service configuration element. The Post Office configuration
- is present in the persistence configuration file corresponding to the specific database you're using
- for the cluster instance.
+
+ When a message is sent to a queue on particular node of the cluster, the system must decide whether the current node will handle it or whether it should send
+ it to another node to handle.
</para>
- <para>
- So, if you are using a MySQL database instance as shared persistent storage for your cluster, the
- Post Office configuration for a specific node instance is available in
- <filename>$JBOSS_HOME/server/messaging-nodeX/deploy/jboss-messaging.sar/clustered-mysql-persistence-service.xml</filename>
+ <para> The same applies if there are shared durable subscriptions on a topic and the message is being sent to a topic
</para>
- <para>An example of a Clustered Post Office configuration is shown below:</para>
+ <para>The correct decision to make depends on your application topology.</para>
+ <para>If your application consists of a set of servers with the same MDBs deployed on each server, and you have many well distributed producers sending
+ messages on all the nodes of the cluster, then the best policy is to always favour the local queue, since extra network trips are more expensive and the other
+ nodes are also havng local messages sent to them</para>
+
+ <para>However if your application consists of a set of homogenous MDBs but you have few or badly distributed producers, then always favouring the local producer
+ will mean the other nodes are being starved of messages and not using their CPUs cycles efficiently for messaging processing.</para>
+
+ <para>In this case, a good policy is to use a round robin routing policy where messages are round robin distributed to different nodes as they arrive.</para>
+
+ <para>In general, use the DefaultRoutingPolicy (this always favours the local queue) if you have many well distributed producers, and use the
+ RoundRobinRoutingPolicy if you have few or badly distributed producers.</para>
+
+ <para>This are specified in the clustered post office config, by specifying the following attribute</para>
+
+ <para>To favour the local queue:</para>
+
<programlisting>
-<mbean code="org.jboss.messaging.core.plugin.ClusteredPostOfficeService"
-name="jboss.messaging:service=PostOffice"
-xmbean-dd="xmdesc/ClusteredPostOffice-xmbean.xml">
-<depends optional-attribute-name="ServerPeer">
- jboss.messaging:service=ServerPeer</depends>
-<depends>jboss.jca:service=DataSourceBinding,name=DefaultDS</depends>
-<depends optional-attribute-name="TransactionManager">
- jboss:service=TransactionManager</depends>
-<attribute name="PostOfficeName">Clustered JMS</attribute>
-<attribute name="DataSource">java:/DefaultDS</attribute>
-<attribute name="CreateTablesOnStartup">true</attribute>
-<attribute name="SqlProperties"><!![CDATA[
-CREATE_POSTOFFICE_TABLE=CREATE TABLE JBM_POSTOFFICE (POSTOFFICE_NAME VARCHAR(255),
- NODE_ID INTEGER, QUEUE_NAME VARCHAR(1023), COND VARCHAR(1023), SELECTOR VARCHAR(1023),
- CHANNEL_ID BIGINT, IS_FAILED_OVER CHAR(1), FAILED_NODE_ID INTEGER)
-INSERT_BINDING=INSERT INTO JBM_POSTOFFICE (POSTOFFICE_NAME, NODE_ID, QUEUE_NAME, COND,
- SELECTOR, CHANNEL_ID, IS_FAILED_OVER, FAILED_NODE_ID) VALUES (?, ?, ?, ?, ?, ?, ?, ?)
-DELETE_BINDING=DELETE FROM JBM_POSTOFFICE WHERE POSTOFFICE_NAME=? AND NODE_ID=? AND
-QUEUE_NAME=?
-LOAD_BINDINGS=SELECT NODE_ID, QUEUE_NAME, COND, SELECTOR, CHANNEL_ID, IS_FAILED_OVER,
- FAILED_NODE_ID FROM JBM_POSTOFFICE WHERE POSTOFFICE_NAME = ?
-]]></attribute>
-<attribute name="GroupName">DefaultPostOffice</attribute>
-<attribute name="StateTimeout">5000</attribute>
-<attribute name="CastTimeout">5000</attribute>
-<attribute name="StatsSendPeriod">10000</attribute>
-<attribute name="MessagePullPolicy">
- org.jboss.messaging.core.plugin.postoffice.cluster.NullMessagePullPolicy</attribute>
-<attribute name="ClusterRouterFactory">
- org.jboss.messaging.core.plugin.postoffice.cluster.DefaultRouterFactory</attribute>
+ <attribute name="ClusterRouterFactory">org.jboss.messaging.core.plugin.postoffice.cluster.DefaultRouterFactory</attribute>
+ </programlisting>
-<attribute name="AsyncChannelConfig">
-<config>
-<UDP mcast_recv_buf_size="500000" down_thread="false" ip_mcast="true"
-mcast_send_buf_size="32000" mcast_port="45567" ucast_recv_buf_size="500000"
-use_incoming_packet_handler="false" mcast_addr="228.8.8.8"
-use_outgoing_packet_handler="true" loopback="true" ucast_send_buf_size="32000"
-ip_ttl="32" bind_addr="127.0.0.1"/>
-<AUTOCONF down_thread="false" up_thread="false"/>
-<PING timeout="2000" down_thread="false" num_initial_members="3" up_thread="false"/>
-<MERGE2 max_interval="10000" down_thread="false" min_interval="5000" up_thread="false"/>
-<FD timeout="2000" max_tries="3" down_thread="false" up_thread="false" shun="true"/>
-<VERIFY_SUSPECT timeout="1500" down_thread="false" up_thread="false"/>
-<pbcast.NAKACK max_xmit_size="8192" down_thread="false" use_mcast_xmit="true" gc_lag="50"
- up_thread="false"
-retransmit_timeout="100,200,600,1200,2400,4800"/>
-<UNICAST timeout="1200,2400,3600" down_thread="false" up_thread="false"/>
-<pbcast.STABLE stability_delay="1000" desired_avg_gossip="20000" down_thread="false"
- max_bytes="0" up_thread="false"/>
-<FRAG frag_size="8192" down_thread="false" up_thread="false"/>
-<VIEW_SYNC avg_send_interval="60000" down_thread="false" up_thread="false" />
-<pbcast.GMS print_local_addr="true" join_timeout="3000" down_thread="false"
-join_retry_timeout="2000" up_thread="false" shun="true"/>
-</config>
-</attribute>
+ <para>To round robin:</para>
-<attribute name="SyncChannelConfig">
-<config>
-<UDP mcast_recv_buf_size="500000" down_thread="false" ip_mcast="true"
-mcast_send_buf_size="32000" mcast_port="45568" ucast_recv_buf_size="500000"
-use_incoming_packet_handler="false" mcast_addr="228.8.8.8"
-use_outgoing_packet_handler="true" loopback="true" ucast_send_buf_size="32000"
-ip_ttl="32" bind_addr="127.0.0.1"/>
-<AUTOCONF down_thread="false" up_thread="false"/>
-<PING timeout="2000" down_thread="false" num_initial_members="3" up_thread="false"/>
-<MERGE2 max_interval="10000" down_thread="false" min_interval="5000" up_thread="false"/>
-<FD timeout="2000" max_tries="3" down_thread="false" up_thread="false" shun="true"/>
-<VERIFY_SUSPECT timeout="1500" down_thread="false" up_thread="false"/>
-<pbcast.NAKACK max_xmit_size="8192" down_thread="false" use_mcast_xmit="true" gc_lag="50"
- up_thread="false"
-retransmit_timeout="100,200,600,1200,2400,4800"/>
-<UNICAST timeout="1200,2400,3600" down_thread="false" up_thread="false"/>
-<pbcast.STABLE stability_delay="1000" desired_avg_gossip="20000" down_thread="false"
- max_bytes="0" up_thread="false"/>
-<FRAG frag_size="8192" down_thread="false" up_thread="false"/>
-<VIEW_SYNC avg_send_interval="60000" down_thread="false" up_thread="false" />
-<pbcast.GMS print_local_addr="true" join_timeout="3000" down_thread="false"
-join_retry_timeout="2000" up_thread="false" shun="true"/>
-<pbcast.STATE_TRANSFER down_thread="false" up_thread="false"/>
-</config>
-</attribute>
-</mbean>
+ <programlisting>
+ <attribute name="ClusterRouterFactory">org.jboss.messaging.core.plugin.postoffice.cluster.RoundRobinRouterFactory</attribute>
</programlisting>
- <para>Relevant clustered Post Office configuration attributes are discussed below:</para>
+ </section>
- <section id="conf.groupname">
- <title><literal>GroupName</literal></title>
- <para>
- This identifies the JGroups group the clustered Post Office will connect to.
- All clustered Post Office instances with the same group name will connect to that group.
- </para>
- </section>
- <section id="conf.statetimeout">
- <title><literal>StateTimeout</literal></title>
- <para>
- The maximum amount of time in milliseconds to wait when making a request
- to get the group state and waiting for the result. You will not normally need
- to change this value. Default is 5000 ms.
- </para>
- </section>
+ <section id="messagepull">
- <section id="conf.casttimeout">
- <title><literal>CastTimeout</literal></title>
- <para>
- The maximum amount of time in milliseconds to wait when casting a message
- and waiting for a result. You will not normally need to change this value.
- Default is 5000 ms.
- </para>
- </section>
+ <title>Choosing the message pull policy</title>
- <section id="conf.statssend">
- <title><literal>StatsSendPeriod</literal></title>
- <para>
- The period in milliseconds between much statistics for each queue will be cast
- across the cluster.
- </para>
- </section>
+ <para>Once messages have arrived on queues in a cluster, in an ideal world they will all be consumed at the same rate, and there will be consumers on each node.
+ </para>
- <section id="conf.clusterrouterfactory">
- <title><literal>ClusterRouterFactory</literal></title>
- <para>
- The fully qualified class name of the class that implements a factory for creating
- message routers. For different message routing policies this can be changed.
- Default is <literal>org.jboss.messaging.core.plugin.postoffice.cluster.DefaultRouterFactory</literal>.
- This factory creates routers that always favor local queues.
- </para>
- </section>
+ <para>However, in some application topologies, consumes may close on queues on a node, leaving messages otherwise stranded, or perhaps consumers
+ on some nodes are fast than consumers on other nodes causing messages to build up on one node or another and adversely effecting latency.
+ </para>
- <section id="conf.messagepullpolicy">
- <title><literal>MessagePullPolicy</literal></title>
- <para>
- The fully qualified class name of the class that implements the MessagePullPolicy.
- The message pull policy specifies how messages are redistributed after they leave
- the Post Office and are delivered to queues. You can find more on message redistribution
- policy in the dedicated section below. By default, the message redistribution policy
- is <literal>org.jboss.messaging.core.plugin.postoffice.cluster.DefaultMessagePullPolicy</literal>.
- </para>
- </section>
+ <para>JBoss Messaging allows messages to pulled from one node to another as load dictates in order to cope with such situations</para>
- </section>
+ <para>Whether or not you should activate message pulling (message redistribution) depends on your application topology</para>
- <section id="jgroups_configuration">
- <title>JGroups Stack Configuration</title>
- <para>
- The details of the JGroups configuration won't be discussed here since it is standard JGroups configuration.
- Detailed information on JGroups can be found in JGroups release documentation or on-line at
- <ulink url="http://www.jgroups.org">http://www.jgroups.org</ulink> or
- <ulink url="http://wiki.jboss.org/wiki/Wiki.jsp?page=JGroups">http://wiki.jboss.org/wiki/Wiki.jsp?page=JGroups</ulink>
+ <para>For an application that consists of a set of servers with a heterogenous bank of MDBs (or other consumers) deployed on each node, consuming at
+ approximately the same rate, then message redistribution is not necessary.
</para>
- </section>
- <section id="message_redistribution_configuration">
- <title>Message Redistribution Configuration</title>
- <para>
- Each clustered Post Office instance can be configured to use a customizable
- <emphasis>message redistribution policy</emphasis>. The message redistribution
- policy dictates what happens with messages that are delivered to a local queue
- that is part of a distributed queue or a distributed subscription. In order to use
- a specific message redistribution policy, use the fully qualified class name of the
- class that implements the MessagePullPolicy.
- </para>
+ <para>However, if your application consists of different numbers or rates of consumers on different nodes then message redistribution may help</para>
- <para>
- By default, the message redistribution policy is
- <literal>org.jboss.messaging.core.plugin.postoffice.cluster.DefaultMessagePullPolicy</literal>
- which tries to redistribute messages depending on receivers's consumption speed.
+ <warning>By its nature, message redistribution can result in messages being delivered in an order different to the strict ordering imposed by JMS. I.e.
+ messages can, sometimes be delivered in an order different to that which they were produced by their producer. If this ordering is important to you
+ then don't use message redistribution</warning>
+
+ <para>In general, use message redistribution when your consumers are not well distributed across the cluster or if they have greatly varying rates.</para>
+
+ <para>Message redistribution is set by setting the following attribute in the clustered post office configuration:
</para>
<para>
- To disable message redistribution completely, specify
- <literal>org.jboss.messaging.core.plugin.postoffice.cluster.NullMessagePullPolicy</literal>
- as the value of <literal>MessagePullPolicy</literal> attribute. In this case, a message is
- not redistributed, even if the local queue that has been delivered to has no consumers.
+ For no message redistribution:
</para>
+ <programlisting>
+ <attribute name="MessagePullPolicy">org.jboss.messaging.core.plugin.postoffice.cluster.NullMessagePullPolicy</attribute>
+ </programlisting>
+
+ <para>For message redistribution:</para>
+
+ <programlisting>
+ <attribute name="MessagePullPolicy">org.jboss.messaging.core.plugin.postoffice.cluster.DefaultMessagePullPolicy</attribute>
+ </programlisting>
+
+ <para>When selecting message redistribution you should also choose a value of <literal>StatsSendPeriod</literal> appropriately.</para>
+
</section>
+
+
</chapter>
\ No newline at end of file
Deleted: trunk/docs/userguide-1.2/en/modules/CLUST_introduction.xml
===================================================================
--- trunk/docs/userguide-1.2/en/modules/CLUST_introduction.xml 2007-03-01 10:52:35 UTC (rev 2532)
+++ trunk/docs/userguide-1.2/en/modules/CLUST_introduction.xml 2007-03-01 17:38:57 UTC (rev 2533)
@@ -1,125 +0,0 @@
-<chapter id="CLUST_introduction">
-
- <title>Introduction</title>
-
- <para>
- JBoss Messaging 1.2 GA will provide a highly sophisticated clustering implementation, far
- more sophisticated than you'll find in the vast majority of other messaging systems.
- </para>
- <para>
- It will allow you to smoothly distribute your application load across your cluster,
- intelligently balancing and utilizing each nodes CPU cycles, with no single point of failure,
- providing a highly scalable and performant clustering implementation.
- </para>
-
- <section id="c_features">
- <title>JBoss Messaging 1.2 GA features:</title>
-
- <para>
- JBoss Messaging 1.2 GA Clustering will provide the following features:
- </para>
-
- <itemizedlist>
- <listitem>
- <para>
- Distributed queues. Messages sent to a distributed queue while attached to a
- particular node will be routed to a queue instance on a particular node according
- to a routing policy.
- </para>
- </listitem>
- <listitem>
- <para>
- Distributed topics. Messages sent to a distributed topic while attached at a
- particular node will be received by subscriptions on other nodes.
- </para>
- </listitem>
- <listitem>
- <para>
- Fully reliable message distribution. Once and only once delivery is fully guaranteed.
- When sending messages to a topic with multiple durable subscriptions
- across a cluster we guarantee that message reaches all the subscriptions
- (or none of them in case of failure).
- </para>
- </listitem>
- <listitem>
- <para>
- Persistent level reliability guarantee without persistence! By replicating persistent messages between nodes in memory,
- we can obtain comparable reliability levels to persistenting messages to disk, without actually storing them to disk.
- </para>
- </listitem>
- <listitem>
- <para>
- Pluggable routing implementation. The policy for routing messages to a queue is fully pluggable and easily replaceable.
- The default policy always chooses a queue at the local node if there is one, and if not, it round robins between queues on different nodes.
- </para>
- </listitem>
- <listitem>
- <para>
- Intelligent message redistribution policy. Messages are automatically distributed between nodes depending on how fast or slow consumers are on certain nodes.
- If there are no or slow consumers on a particular queue node, messages will be pulled from that queue to a queue with faster consumers on a different node.
- The policy is fully pluggable.
- </para>
- </listitem>
- <listitem>
- <para>
- Shared durable subscriptions. Consumers can connect to the same durable subscription while attached to different nodes.
- This allows processing load from durable subscriptions to be distributed across the cluster in a similar way to queues.
- </para>
- </listitem>
- <listitem>
- <para>
- High availability and seamless failover.
- If the node you are connected to fails, you will automatically fail over to another node and will not lose any
- persistent messages.
- You can carry on with your session seamlessly where you left off.
- Once and only once delivery of persistent messages is respected at all times.
- </para>
- </listitem>
- </itemizedlist>
-
-
- </section>
-
- <section id="alphafeatures">
- <title>JBoss Messaging 1.2.0.CR1 features:</title>
-
- <para> What's in the CR1 release?</para>
-
- <para>
- JBoss Messaging 1.2.0.CR1 contains all features planned for the GA release, with the exception
- of the "unreliable link scenario" (http://jira.jboss.org/jira/browse/JBMESSAGING-676),
- whose development is still on-going on a parallel branch.
- </para>
-
- <para>
- Please note that this is a candidate release and it possible to contain bugs!
- We are releasing it to the community, so you can try it out, get familiar with it
- and feedback your experiences to us so we can improve it and stabilise it.
- </para>
-
- <para>
- Thanks for your support!
- </para>
-
- <para>
- All the final features are available apart from:
- </para>
-
- <itemizedlist>
- <listitem>
- <para>
- Persistent level reliability guarantee without persistence. There is no option for
- in memory replication of persistent messages in this release.
- </para>
- </listitem>
-
- </itemizedlist>
-
- <para>
- Bear in mind you will need to get a bit more "down and dirty" with the configuration in
- this release, than you would with a GA release.
- </para>
-
- </section>
-
-</chapter>
Modified: trunk/docs/userguide-1.2/en/modules/CLUST_overview.xml
===================================================================
--- trunk/docs/userguide-1.2/en/modules/CLUST_overview.xml 2007-03-01 10:52:35 UTC (rev 2532)
+++ trunk/docs/userguide-1.2/en/modules/CLUST_overview.xml 2007-03-01 17:38:57 UTC (rev 2533)
@@ -6,8 +6,7 @@
<para>
This section of the userguide gives a brief overview of the features available in
JBoss Messaging Clustering 1.2.0.GA. It gives a high level explanation of how
- clustering works and shows you how to set up a simple cluster of JBoss Messaging
- servers.
+ clustering works.
</para>
<section id="clustering_overview">
@@ -17,16 +16,10 @@
Here's a brief overview of how clustering works in JBoss Messaging 1.2.
</para>
- <para>As mentioned in the previous chapter, please note that not all this functionality is
- available in this release.
- </para>
<para>
Clustered destinations (queues and topics) can be deployed at all or none of the nodes of
the cluster.
- </para>
-
- <para>
A JMS client uses HA JNDI to lookup the connection factory. A client side load balancing
policy will automatically chose a node to connect to (This is similar to
how EJB clustering chooses a node).
@@ -36,9 +29,6 @@
The JMS client has now made a connection to a node where it can create sessions, message
producers and message consumers and browsers and send or consume messages,
using the standard JMS api.
- </para>
-
- <para>
When a distributed queue is deployed across the cluster, individual partial queues are
deployed on each node.
</para>
@@ -47,14 +37,8 @@
When a message is sent from a message producer attached to a particular node to a
distributed queue, a routing policy determines which partial queue will receive
the message.
- </para>
-
- <para>
By default the router will always pass the message to a local queue, if there is one,
this is so we avoid unnecessary network traffic.
- </para>
-
- <para>
If there is no local queue then a partial queue on a different node will be chosen by the
router, by default this will be round robin between remote partial queues.
</para>
@@ -64,77 +48,41 @@
multiple subscriptions on different nodes that need to receive the
message. Depending on the number and location of subscriptions, the message may be multicast
or unicast across the cluster so the other nodes can pick it up.
+ (All group communication, unicast, multicast and group management is handled by JGroups.)
</para>
<para>
- All group communication, unicast, multicast and group management is handled by JGroups.
- </para>
-
- <para>
In the case of shared durable subscriptions, if a durable subscription with the same name
exists on more than node, then only one of the instances needs to receive the message.
- </para>
-
- <para>Which one is determined by the same routing policy used to route messages to partial queues.</para>
-
- <para>
+ Which one is determined by the same routing policy used to route messages to partial queues.
All of this is accomplished without losing the reliability guarantees required by JMS.
</para>
<para>
Subscriptions (both durable and non durable) can be created on all nodes and will receive messages sent via any node.
- </para>
-
- <para>
What happens if the consumers on one queue/subscription are faster/slower than consumers on another?
- </para>
-
- <para>
Normally this would result in messages building up on that queue and fast consumers being starved of work on another, thus wasting CPU cycles on the node that
could be put to good use.
- </para>
-
- <para>
The most degenerate example is of a queue containing many messages then the consumers being closed on that queue.
-
The messages might potentially remain stranded on the queue until another consumer attaches.
- </para>
-
- <para>
A routing policy is no use here, since the messages have already been routed to the queuee and the consumers closed / slowed down
after they were routed there.
-
- </para>
-
- <para>
- JBoss Messaging deals with this problem by intelligently pulling messages from other less
+ JBoss Messaging can deal with this problem by intelligently pulling messages from other less
busy nodes, if it detects idle consumers on the fast node and slow consumers
on another node.
</para>
<para>
- Another feature (not available in CR1) that will enable very fast, very scalable reliable
- messaging without using databases is in memory replication of reliable messages.
- </para>
-
- <para>
Normally, persistent messages are persisted in a shared database which is shared by all nodes
in the cluster.
- JBoss Messaging 2.0.GA will contain
+ JBoss Messaging 1.2.1 will contain
an option where you can choose to not persist persistent messages in a database, but instead to replicate them between nodes of the cluster.
- </para>
- <para>
The idea here is the network IO on a fast network should be much faster than persisting to disk.
- </para>
-
- <para>
This solution should also be more scalable since different nodes replicate their messages onto
different other nodes - there is no "master node".
- </para>
- <para>
If the messages are replicated onto sufficient nodes and the hardware is set-up with UPS, then we believe a comparable reliability guarantee to persisting messages to disk
can be achieved. Of course, this won't be suitable for all situations, but you use the best tool for the job.
</para>
Modified: trunk/docs/userguide-1.2/en/modules/UG12_configuration.xml
===================================================================
--- trunk/docs/userguide-1.2/en/modules/UG12_configuration.xml 2007-03-01 10:52:35 UTC (rev 2532)
+++ trunk/docs/userguide-1.2/en/modules/UG12_configuration.xml 2007-03-01 17:38:57 UTC (rev 2533)
@@ -34,18 +34,23 @@
<para>
The AOP client-side and server-side interceptor stacks are configured in
<filename>aop-messaging-client.xml</filename> and <filename>aop-messaging-server.xml</filename>.
+ Normally you will not want to change them, but you can some of the interceptors can be removed
+ to give a small performance increase, if you don't need them. Be very careful you have considered the security implications before removing the
+ security interceptor.
</para>
<section id="conf.serverpeer">
- <title>Configuring the Server</title>
+ <title>Configuring the ServerPeer</title>
<para>
The Server Peer is the "heart" of the JBoss Messaging JMS facade. The server's configuration,
resides in <filename>messaging-service.xml</filename> configuration file.
</para>
+ <para>All JBoss Messaging services are rooted at the server peer</para>
- <para>An example of a Server Peer configuration is presented below</para>
+ <para>An example of a Server Peer configuration is presented below. Note that not all values for the server peer's attributes are
+ specified in the example</para>
<programlisting>
<mbean code="org.jboss.jms.server.ServerPeer"
@@ -88,67 +93,777 @@
</mbean>
</programlisting>
- <section id="conf.serverpeer.securitydomain">
- <title>SecurityDomain</title>
+ <section id="conf.serverpeer.attributes">
- <para>
- This identifies the JBoss security domain that will be used when JBoss Messaging
- authenticates and authorizes access to JMS destinations for reading, writing or
- creating.
- </para>
+ <title>
+ We now discuss the MBean attributes of the ServerPeer MBean
+ </title>
- <para>
- It should correspond to a entry in <filename>login-config.xml</filename> where
- it is configured in exactly the same way as any other security domain in JBoss.
- </para>
+ <section id="conf.serverpeer.attributes.persistencemanager">
+ <title>PersistenceManager</title>
+
+ <para>
+ This is the persistence manager that the ServerPeer uses. You will not normally need to change this attribute.
+ </para>
+ </section>
+
+ <section id="conf.serverpeer.attributes.postoffice">
+ <title>PostOffice</title>
+
+ <para>
+ This is the post office that the ServerPeer uses. You will not normally need to change this attribute.
+ The post office is responsible for routing messages to queues and maintaining the mapping between addresses and queues.
+ </para>
+ </section>
+
+ <section id="conf.serverpeer.attributes.jmsusermanager">
+ <title>JMSUserManager</title>
+
+ <para>
+ This is the JMS user manager that the ServerPeer uses. You will not normally need to change this attribute.
+ </para>
+ </section>
+
+ <section id="conf.serverpeer.attributes.defaultdlq">
+ <title>DefaultDLQ</title>
+
+ <para>
+ This is the name of the default DLQ (Dead Letter Queue) 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 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 individually
+ on a per destination basis.
+
+ </para>
+ </section>
+
+ <section id="conf.serverpeer.attributes.defaultexpiryqueue">
+ <title>DefaultExpiryQueue</title>
+
+ <para>
+ This is the name of the default expiry queue 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>
+ </section>
+
+
+ <section id="conf.serverpeer.attributes.serverpeerid">
+ <title>ServerPeerID</title>
+
+ <para>
+ The unique id of the server. In a cluster each server MUST have a unique id.
+ </para>
+ </section>
+
+ <section id="conf.serverpeer.attributes.defaultqueuejndicontext">
+ <title>DefaultQueueJNDIContext</title>
+
+ <para>
+ The default JNDI context to use when binding queues. Defaults to /queue.
+ </para>
+ </section>
+
+ <section id="conf.serverpeer.attributes.defaultopicjndicontext">
+ <title>DefaultTopicJNDIContext</title>
+
+ <para>
+ The default JNDI context to use when binding topics. Defaults to /topic.
+ </para>
+ </section>
+
+ <section id="conf.serverpeer.attributes.destinations">
+ <title>Destinations</title>
+
+ <para>
+ Returns a list of the destinations (queues and topics) currently deployed.
+ </para>
+ </section>
+
+ <section id="conf.serverpeer.attributes.defaultmaxdeliveryattempts">
+ <title>DefaultMaxDeliveryAttempts</title>
+
+ <para>
+ The default for the maximum number of times delivery of a message will be attempted before sending the message to the DLQ, if configured.
+ </para>
+ <para>
+ The default value is <literal>10</literal >
+ </para>
+ <para>This value can also be overridden on a per destination basis</para>
+ </section>
+
+ <section id="conf.serverpeer.attributes.failoverstarttimeout">
+ <title>FailoverStartTimeout</title>
+
+ <para>
+ The maximum number of milliseconds the client will wait for failover to start on the server side when a problem is detected.
+ </para>
+ <para>
+ The default value is <literal>60000</literal> (one minute)
+ </para>
+
+ </section>
+
+ <section id="conf.serverpeer.attributes.failovercompletetimeout">
+ <title>FailoverCompleteTimeout</title>
+
+ <para>
+ The maximum number of milliseconds the client will wait for failover to complete on the server side after it has started.
+ </para>
+ <para>
+ The default value is <literal>300000</literal> (five minutes)
+ </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>
+ The default value is <literal>0</literal> which means there will be no delay.
+ </para>
+ <para>Change this if your application could benefit with a delay before redelivery. This value can also be overridden on a per destination basis</para>
+ </section>
+
+ <section id="conf.serverpeer.attributes.queuestatssampleperiod">
+ <title>QueueStatsSamplePeriod</title>
+
+ <para>
+ Periodically the server will query each queue to gets its message statistics. This is the period.
+ </para>
+ <para>
+ The default value is <literal>10000</literal> milliseconds
+ </para>
+ </section>
+
+
+ <section id="conf.serverpeer.attributes.defaultmessagecounterhistorydaylimit">
+ <title>DefaultMessageCounterHistoryDayLimit</title>
+
+ <para>
+ JBoss Messaging provides a message counter history which shows the number of messages arriving on each queue of 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>
+ </section>
+
+ <section id="conf.serverpeer.attributes.messagecounters">
+ <title>MessageCounters</title>
+
+ <para>
+ JBoss Messaging provides a message counter for each queue.
+ </para>
+ </section>
+
+ <section id="conf.serverpeer.attributes.messagecounterstatistics">
+ <title>MessageCountersStatistics</title>
+
+ <para>
+ JBoss Messaging provides statistics for each message counter for each queue.
+ </para>
+ </section>
+
+ <section id="conf.serverpeer.attributes.defaultsecurity">
+ <title>DefaultSecurityConfig</title>
+
+ <para>
+ Default security configuration is used when the security configuration for a specific
+ queue or topic has not been overridden in the destination's deployment descriptor.
+ It has exactly the same syntax and semantics as in JBossMQ.
+ </para>
+
+ <para>
+ The <literal>DefaultSecurityConfig</literal> attribute element should contain
+ one <literal><security></literal> element.
+ The <literal><security></literal> element can contain multiple
+ <literal><role></literal> elements. Each <literal><role></literal>
+ element defines the default access for that particular role.
+ </para>
+
+ <para>
+ If the <literal>read</literal> attribute is <literal>true</literal> then that role
+ will be able to read (create consumers, receive messaages or browse) destinations
+ by default.
+ </para>
+
+ <para>
+ If the <literal>write</literal> attribute is <literal>true</literal> then that role
+ will be able to write (create producers or send messages) to destinations by default.
+ </para>
+
+ <para>
+ If the <literal>create</literal> attribute is <literal>true</literal> then that role
+ will be able to create durable subscriptions on topics by default.
+ </para>
+ </section>
</section>
- <section id="conf.serverpeer.defaultsecurity">
- <title>DefaultSecurityConfig</title>
+ <section id="conf.serverpeer.operations">
+
+ <title>
+ We now discuss the MBean operations of the ServerPeer MBean
+ </title>
+
+ <section id="conf.serverpeer.operations.deployQueue">
+ <title>DeployQueue</title>
+
+ <para>
+ This operation lets you programmatically deploy a queue.
+ </para>
+
+ <para>There are two overloaded versions of this operation</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 <DefaultQueueJNDIContext>/<name></para>
+
+ <para>The first version of this operation deploys the destination with the default paging parameters. The second overloaded version deploys
+ the destination with the specified paging parameters. See the section on configuring destinations for a discussion of what the
+ paging parameters mean</para>
+
+ </section>
+
+ <section id="conf.serverpeer.operations.undeployQueue">
+ <title>UndeployQueue</title>
+
+ <para>
+ This operation lets you programmatically undeploy a queue.
+ </para>
+
+ <para>The queue is undeployed but is NOT removed from persistent storage.</para>
+
+ <para>This operation returns <literal>true</literal> if the queue was successfull undeployed. otherwise it returns <literal>false</literal></para>
+
+ </section>
+
+ <section id="conf.serverpeer.operations.destroyQueue">
+ <title>DestroyQueue</title>
+
+ <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>
+
+ <warning>Be careful when using this method since it will delete all data for the queue</warning>
+
+ <para>This operation returns <literal>true</literal> if the queue was successfully destroyed. otherwise it returns <literal>false</literal></para>
+
+ </section>
+
+ <section id="conf.serverpeer.operations.deployTopic">
+ <title>DeployTopic</title>
+
+ <para>
+ This operation lets you programmatically deploy a topic.
+ </para>
+
+ <para>There are two overloaded versions of this operation</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 <DefaultTopicJNDIContext>/<name></para>
+
+ <para>The first version of this operation deploys the destination with the default paging parameters. The second overloaded version deploys
+ the destination with the specified paging parameters. See the section on configuring destinations for a discussion of what the
+ paging parameters mean</para>
+
+ </section>
+
+ <section id="conf.serverpeer.operations.undeployTopic">
+ <title>UndeployTopic</title>
+
+ <para>
+ This operation lets you programmatically undeploy a topic.
+ </para>
+
+ <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 <literal>false</literal></para>
+
+ </section>
+
+ <section id="conf.serverpeer.operations.destroyTopic">
+ <title>DestroyTopic</title>
+
+ <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>
+
+ <warning>Be careful when using this method since it will delete all data for the topic</warning>
+
+ <para>This operation returns <literal>true</literal> if the topic 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 HTML format.
+ </para>
+ </section>
+
+ <section id="conf.serverpeer.operations.resetallmessagecounters">
+ <title>ResetAllMesageCounters</title>
+
+ <para>
+ This operation resets all message counters to zero.
+ </para>
+ </section>
+
+
+ <section id="conf.serverpeer.operations.resetallmessagecounterhistories">
+ <title>ResetAllMesageCounters</title>
+
+ <para>
+ This operation resets all message counter histories to zero.
+ </para>
+ </section>
+
+ <section id="conf.serverpeer.operations.enablemessagecounters">
+ <title>EnableMessageCounters</title>
+
+ <para>
+ This operation enables all message counters for all destinations. Message counters are disabled by default.
+ </para>
+ </section>
+
+ <section id="conf.serverpeer.operations.disablemessagecounters">
+ <title>DisableMessageCounters</title>
+
+ <para>
+ This operation disables all message counters for all destinations. Message counters are disabled by default.
+ </para>
+ </section>
+
+ <section id="conf.serverpeer.operations.retrievepreparedtransactions">
+ <title>RetrievePreparedTransactions</title>
+
+ <para>
+ Retrieves a list of the Xids for all transactions currently in a prepared state on the node.
+ </para>
+ </section>
+
+ <section id="conf.serverpeer.operations.showpreparedtransactions">
+ <title>ShowPreparedTransactions</title>
+
+ <para>
+ Retrieves a list of the Xids for all transactions currently in a prepared state on the node in an easy to display HTML format.
+ </para>
+ </section>
+
+
+ </section>
+
+ </section>
+
+ <section id="conf.changingds">
+ <title>Changing the Database</title>
+
<para>
- Default security configuration is used when the security configuration for a specific
- queue or topic has not been overridden in the destination's deployment descriptor.
- It has exactly the same syntax and semantics as in JBossMQ.
+ 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 persistence.
+ The Post Office handles binding related persistence.
+ The JMS 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>
- The <literal>DefaultSecurityConfig</literal> attribute element should contain
- one <literal><security></literal> element.
- The <literal><security></literal> element can contain multiple
- <literal><role></literal> elements. Each <literal><role></literal>
- element defines the default access for that particular role.
+ 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 the <literal>read</literal> attribute is <literal>true</literal> then that role
- will be able to read (create consumers, receive messaages or browse) destinations
- by default.
+ 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>
- If the <literal>write</literal> attribute is <literal>true</literal> then that role
- will be able to write (create producers or send messages) to destinations by default.
+ Also, be aware that by default, the Messaging services relying on a datastore
+ are referencing <literal>"java:/DefaultDS"</literal> for the datasource.
+ If you are deploying a datasource with a different JNDI name, you need to update
+ all the <literal>DataSource</literal> attribute in the persistence configuration file.
+
+ Example data source configurations for each of the popular databases are available in the distribution.
</para>
- <para>
- If the <literal>create</literal> attribute is <literal>true</literal> then that role
- will be able to create durable subscriptions on topics by default.
- </para>
</section>
- </section>
- <section id="conf.persistence">
- <title>Configuring Persistence</title>
+ <section id="conf.postoffice">
+ <title>Configuring the Post office</title>
- <para>
- JBoss Messaging interacts with a persistent store via two services: the Persistence Manager
- and the Channel Mapper. The Persistence Manager is used to handle the message-related
- functions. The Channel Mapper manages destination-related persistent
- data.
+ <para>It is the job of the post office to route 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>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>JBoss Messaging comes with two different post office implementations - depending on whether you want clustering or not. The clustered post office
+ has the ability to route messages to other nodes in the cluster</para>
+
+ <para>Whether you use the clustered post office or not depends on whether you deploy the <literal>clustered-xxx-persistence-service.xml</literal> MBean config
+ or just the non clustered <literal>xxx-persistence-service.xml</literal> file.</para>
+
+ <para>It is likely that in future releases of JBoss Messaging the clustered and non clustered post offices will be combined into a single post office for
+ ease of configuration</para>
+
+ <section id="conf.postoffice.nonclustered">
+ <title>Non clustered post office</title>
+
+ <para>The non clustered post office should be used where clustering is not required. It will be used when the
+ non clustered <literal>xxx-persistence-service.xml</literal> file is deployed.</para>
+
+ <para>Here is an example of a non clustered post office configuration:</para>
+
+ <programlisting>
+
+<mbean code="org.jboss.messaging.core.plugin.DefaultPostOfficeService"
+ name="jboss.messaging:service=PostOffice"
+ xmbean-dd="xmdesc/DefaultPostOffice-xmbean.xml">
+ <depends optional-attribute-name="ServerPeer">jboss.messaging:service=ServerPeer</depends>
+ <depends>jboss.jca:service=DataSourceBinding,name=DefaultDS</depends>
+ <depends optional-attribute-name="TransactionManager">jboss:service=TransactionManager</depends>
+ <attribute name="PostOfficeName">JMS</attribute>
+ <attribute name="DataSource">java:/DefaultDS</attribute>
+ <attribute name="CreateTablesOnStartup">true</attribute>
+ <attribute name="SqlProperties"><![CDATA[
+CREATE_POSTOFFICE_TABLE=CREATE TABLE JBM_POSTOFFICE (POSTOFFICE_NAME VARCHAR(255), NODE_ID INTEGER, QUEUE_NAME VARCHAR(1023), COND VARCHAR(1023), SELECTOR VARCHAR(1023), CHANNEL_ID BIGINT, CLUSTERED CHAR(1))
+INSERT_BINDING=INSERT INTO JBM_POSTOFFICE (POSTOFFICE_NAME, NODE_ID, QUEUE_NAME, COND, SELECTOR, CHANNEL_ID, CLUSTERED) VALUES (?, ?, ?, ?, ?, ?, ?)
+DELETE_BINDING=DELETE FROM JBM_POSTOFFICE WHERE POSTOFFICE_NAME=? AND NODE_ID=? AND QUEUE_NAME=?
+LOAD_BINDINGS=SELECT NODE_ID, QUEUE_NAME, COND, SELECTOR, CHANNEL_ID, CLUSTERED FROM JBM_POSTOFFICE WHERE POSTOFFICE_NAME = ?
+ ]]></attribute>
+ </mbean>
+
+ </programlisting>
+
+ <section id="conf.postoffice.nonclustered.attributes">
+
+ <title>The non clustered post office has the following attributes</title>
+
+ <section id="conf.postoffice.nonclustered.attributes.datasource">
+ <title>DataSource</title>
+ <para>The datasource the postoffice should use for persisting its mapping data</para>
+ </section>
+
+ <section id="conf.postoffice.nonclustered.attributes.sqlproperties">
+ <title>SQLProperties</title>
+ <para>
+ This is where the DDL and DML for the particular database is specified.
+ If a particular DDL or DML statement is not overridden, the default Hypersonic
+ configuration will be used for that statement.
+ </para>
+ </section>
+
+ <section id="conf.postoffice.nonclustered.attributes.createtables">
+ <title>CreateTablesOnStartup</title>
+
+ <para>
+ Set this to <literal>true</literal> if you wish 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> will be thrown by the JDBC driver and
+ ignored by the Persistence Manager, allowing it to continue.
+ </para>
+ <para>
+ By default the value of <literal>CreateTablesOnStartup</literal> attribute
+ is set to <literal>true</literal>
+ </para>
+ </section>
+
+ <section id="conf.postoffice.nonclustered.attributes.postofficename">
+ <title>PostOfficeName</title>
+
+ <para>
+ The name of the post office
+ </para>
+ </section>
+ </section>
+ </section>
+
+
+ <section id="conf.postoffice.clustered">
+ <title>Clustered post office</title>
+
+ <para>The clustered post office should be used where clustering is required. It will be used when the
+ clustered <literal>clustered-xxx-persistence-service.xml</literal> file is deployed.</para>
+
+ <para>Here is an example of a clustered post office configuration:</para>
+
+ <programlisting>
+
+<mbean code="org.jboss.messaging.core.plugin.ClusteredPostOfficeService"
+ name="jboss.messaging:service=PostOffice"
+ xmbean-dd="xmdesc/ClusteredPostOffice-xmbean.xml">
+ <depends optional-attribute-name="ServerPeer">jboss.messaging:service=ServerPeer</depends>
+ <depends>jboss.jca:service=DataSourceBinding,name=DefaultDS</depends>
+ <depends optional-attribute-name="TransactionManager">jboss:service=TransactionManager</depends>
+ <attribute name="PostOfficeName">Clustered JMS</attribute>
+ <attribute name="DataSource">java:/DefaultDS</attribute>
+ <attribute name="CreateTablesOnStartup">true</attribute>
+ <attribute name="SqlProperties"><![CDATA[
+CREATE_POSTOFFICE_TABLE=CREATE TABLE JBM_POSTOFFICE (POSTOFFICE_NAME VARCHAR(255), NODE_ID INTEGER, QUEUE_NAME VARCHAR(1023), COND VARCHAR(1023), SELECTOR VARCHAR(1023), CHANNEL_ID BIGINT, CLUSTERED CHAR(1))
+INSERT_BINDING=INSERT INTO JBM_POSTOFFICE (POSTOFFICE_NAME, NODE_ID, QUEUE_NAME, COND, SELECTOR, CHANNEL_ID, CLUSTERED) VALUES (?, ?, ?, ?, ?, ?, ?)
+DELETE_BINDING=DELETE FROM JBM_POSTOFFICE WHERE POSTOFFICE_NAME=? AND NODE_ID=? AND QUEUE_NAME=?
+LOAD_BINDINGS=SELECT NODE_ID, QUEUE_NAME, COND, SELECTOR, CHANNEL_ID, CLUSTERED FROM JBM_POSTOFFICE WHERE POSTOFFICE_NAME = ?
+ ]]></attribute>
+ <attribute name="GroupName">DefaultPostOffice</attribute>
+ <attribute name="StateTimeout">5000</attribute>
+ <attribute name="CastTimeout">5000</attribute>
+ <attribute name="StatsSendPeriod">10000</attribute>
+ <attribute name="MessagePullPolicy">org.jboss.messaging.core.plugin.postoffice.cluster.NullMessagePullPolicy</attribute>
+ <attribute name="ClusterRouterFactory">org.jboss.messaging.core.plugin.postoffice.cluster.DefaultRouterFactory</attribute>
+
+
+ <attribute name="ChannelFactoryName">jgroups.mux:name=Multiplexer</attribute>
+ <attribute name="SyncChannelName">udp-sync</attribute>
+ <attribute name="AsyncChannelName">udp</attribute>
+ <attribute name="ChannelPartitionName">${jboss.partition.name:DefaultPartition}-JMS</attribute>
+
+ <attribute name="AsyncChannelConfig">
+ <config>
+ <UDP mcast_recv_buf_size="500000" down_thread="false" ip_mcast="true" mcast_send_buf_size="32000"
+ mcast_port="45567" ucast_recv_buf_size="500000" use_incoming_packet_handler="false"
+ mcast_addr="228.8.8.8" use_outgoing_packet_handler="true" loopback="true" ucast_send_buf_size="32000" ip_ttl="32" bind_addr="127.0.0.1"/>
+ <AUTOCONF down_thread="false" up_thread="false"/>
+ <PING timeout="2000" down_thread="false" num_initial_members="3" up_thread="false"/>
+ <MERGE2 max_interval="10000" down_thread="false" min_interval="5000" up_thread="false"/>
+ <FD_SOCK down_thread="false" up_thread="false"/>
+ <FD timeout="20000" max_tries="3" down_thread="false" up_thread="false" shun="true"/>
+ <VERIFY_SUSPECT timeout="1500" down_thread="false" up_thread="false"/>
+ <pbcast.NAKACK max_xmit_size="8192" down_thread="false" use_mcast_xmit="true" gc_lag="50" up_thread="false"
+ retransmit_timeout="100,200,600,1200,2400,4800"/>
+ <UNICAST timeout="1200,2400,3600" down_thread="false" up_thread="false"/>
+ <pbcast.STABLE stability_delay="1000" desired_avg_gossip="20000" down_thread="false" max_bytes="0" up_thread="false"/>
+ <FRAG frag_size="8192" down_thread="false" up_thread="false"/>
+ <VIEW_SYNC avg_send_interval="60000" down_thread="false" up_thread="false" />
+ <pbcast.GMS print_local_addr="true" join_timeout="3000" down_thread="false" join_retry_timeout="2000" up_thread="false" shun="true"/>
+ </config>
+ </attribute>
+
+ <attribute name="SyncChannelConfig">
+ <config>
+ <UDP mcast_recv_buf_size="500000" down_thread="false" ip_mcast="true" mcast_send_buf_size="32000"
+ mcast_port="45568" ucast_recv_buf_size="500000" use_incoming_packet_handler="false"
+ mcast_addr="228.8.8.8" use_outgoing_packet_handler="true" loopback="true" ucast_send_buf_size="32000" ip_ttl="32" bind_addr="127.0.0.1"/>
+ <AUTOCONF down_thread="false" up_thread="false"/>
+ <PING timeout="2000" down_thread="false" num_initial_members="3" up_thread="false"/>
+ <MERGE2 max_interval="10000" down_thread="false" min_interval="5000" up_thread="false"/>
+ <FD_SOCK down_thread="false" up_thread="false"/>
+ <FD timeout="20000" max_tries="3" down_thread="false" up_thread="false" shun="true"/>
+ <VERIFY_SUSPECT timeout="1500" down_thread="false" up_thread="false"/>
+ <pbcast.NAKACK max_xmit_size="8192" down_thread="false" use_mcast_xmit="true" gc_lag="50" up_thread="false"
+ retransmit_timeout="100,200,600,1200,2400,4800"/>
+ <UNICAST timeout="1200,2400,3600" down_thread="false" up_thread="false"/>
+ <pbcast.STABLE stability_delay="1000" desired_avg_gossip="20000" down_thread="false" max_bytes="0" up_thread="false"/>
+ <FRAG frag_size="8192" down_thread="false" up_thread="false"/>
+ <VIEW_SYNC avg_send_interval="60000" down_thread="false" up_thread="false" />
+ <pbcast.GMS print_local_addr="true" join_timeout="3000" down_thread="false" join_retry_timeout="2000" up_thread="false" shun="true"/>
+ <pbcast.STATE_TRANSFER down_thread="false" up_thread="false"/>
+ </config>
+ </attribute>
+ </mbean>
+
+ </programlisting>
+
+ <section id="conf.postoffice.clustered.attributes">
+
+ <title>The nclustered post office has the following attributes</title>
+
+ <section id="conf.postoffice.clustered.attributes.datasource">
+ <title>DataSource</title>
+ <para>The datasource the postoffice should use for persisting its mapping data</para>
+ </section>
+
+ <section id="conf.postoffice.clustered.attributes.sqlproperties">
+ <title>SQLProperties</title>
+ <para>
+ This is where the DDL and DML for the particular database is specified.
+ If a particular DDL or DML statement is not overridden, the default Hypersonic
+ configuration will be used for that statement.
+ </para>
+ </section>
+
+ <section id="conf.postoffice.clustered.attributes.createtables">
+ <title>CreateTablesOnStartup</title>
+
+ <para>
+ Set this to <literal>true</literal> if you wish 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> will be thrown by the JDBC driver and
+ ignored by the Persistence Manager, allowing it to continue.
+ </para>
+ <para>
+ By default the value of <literal>CreateTablesOnStartup</literal> attribute
+ is set to <literal>true</literal>
+ </para>
+ </section>
+
+ <section id="conf.postoffice.clustered.attributes.postofficename">
+ <title>PostOfficeName</title>
+
+ <para>
+ The name of the post office
+ </para>
+ </section>
+
+ <section id="conf.postoffice.clustered.attributes.nodeidview">
+ <title>NodeIDView</title>
+
+ <para>
+ This returns set containing the node ids of all the nodes in the cluster
+ </para>
+ </section>
+
+ <section id="conf.postoffice.clustered.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>
+ </section>
+
+ <section id="conf.postoffice.clustered.attributes.messagepullpolicy">
+ <title>MessagePullPolicy</title>
+ <para>
+ JBoss Messaging has the ability for queues on one node to pull messages from other nodes when they have exhausted their local messages.
+ </para>
+ <para>This prevents messages from getting stranded on nodes with slow or no consumers, and balances out message processing across the cluster.</para>
+ <para>How, if and when messages are pulled from one node to another is determined by the MessagePullPolicy</para>
+ <para>By default this set to <literal>org.jboss.messaging.core.plugin.postoffice.cluster.NullMessagePullPolicy</literal> which is a dummy
+ implementation which never pulls messages from one node to another.</para>
+ <para>Whether you need message redistribution or not depends on your application topology - please see the section on clustering configuration for
+ more details</para>
+ <para>If you require message redistribution then set this value to <literal>org.jboss.messaging.core.plugin.postoffice.cluster.NullMessagePullPolicy</literal>
+ </para>
+ <warning>Enabling message redistribution can result in the strict JMS message ordering guarantee being lost (i.e. the order of receipt of messages from
+ a particular producer is retained). If this is not acceptable then do not enable message redistribution.</warning>
+ </section>
+
+ <section id="conf.postoffice.clustered.attributes.clusterrouterfactory">
+ <title>ClusterRouterFactory</title>
+ <para>
+ When a message arrives on a node - JBoss Messaging needs to decide whether to route it to a local queue or a remote queue on a different node.
+ </para>
+ <para>This setting allows you to specify the factory that determines this routing</para>
+ <para>By default this set to <literal>org.jboss.messaging.core.plugin.postoffice.cluster.DefaultRouterFactory</literal> which always favours
+ a local queue if one is available otherwise it round robins amongst other queues.</para>
+ <para>The particular router factory you require depends on your application topology - please see the section on clustering configuration for
+ more details</para>
+ <para>Other values this attribute can be set to are <literal>org.jboss.messaging.core.plugin.postoffice.cluster.RoundRobinRouterFactory</literal>
+ if you do not want to favour the local queue.
+ </para>
+ </section>
+
+ <section id="conf.postoffice.clustered.attributes.statetimeout">
+ <title>StateTimeout</title>
+ <para>
+ The maximum time to wait when waiting for the group state to arrive when a node joins a pre-existing cluster.
+ </para>
+ <para>The default value is <literal>5000</literal> milliseconds
+ </para>
+ </section>
+
+ <section id="conf.postoffice.clustered.attributes.casttimeout">
+ <title>CastTimeout</title>
+ <para>
+ The maximum time to wait for a reply casting message synchronously
+ </para>
+ <para>The default value is <literal>5000</literal> milliseconds
+ </para>
+ </section>
+
+ <section id="conf.postoffice.clustered.attributes.statssendperiod">
+ <title>StatsSendPeriod</title>
+ <para>
+ When clustering, each node in the cluster will broadcast statistics periodically to inform the other nodes of their queues and the number of
+ messages in them. This data is then used by the message redistribution policy to redistribute messages if necessary.
+ This value represents the number of milliseconds between statistics broadcasts.
+ </para>
+ <para>
+ The default value is <literal>10000</literal> milliseconds
+ </para>
+ </section>
+
+ <section id="conf.postoffice.clustered.attributes.syncchannelconfig">
+ <title>SyncChannelConfig</title>
+ <para>
+ JBoss Messaging uses JGroups for all group management. This contains the JGroups stack configuration for the synchronous channel.
+ </para>
+ <para>The synchronous channel is used for sending request/reeciving responses from other nodes in the cluster</para>
+ <para>
+ The details of the JGroups configuration won't be discussed here since it is standard JGroups configuration.
+ Detailed information on JGroups can be found in JGroups release documentation or on-line at
+ <ulink url="http://www.jgroups.org">http://www.jgroups.org</ulink> or
+ <ulink url="http://wiki.jboss.org/wiki/Wiki.jsp?page=JGroups">http://wiki.jboss.org/wiki/Wiki.jsp?page=JGroups</ulink>
+ </para>
+ </section>
+
+ <section id="conf.postoffice.clustered.attributes.asyncchannelconfig">
+ <title>AsyncChannelConfig</title>
+ <para>
+ JBoss Messaging uses JGroups for all group management. This contains the JGroups stack configuration for the asynchronous channel.
+ </para>
+ <para>The asynchronous channel is used for sending sending/receiving messages from other nodes in the cluster</para>
+ <para>
+ The details of the JGroups configuration won't be discussed here since it is standard JGroups configuration.
+ Detailed information on JGroups can be found in JGroups release documentation or on-line at
+ <ulink url="http://www.jgroups.org">http://www.jgroups.org</ulink> or
+ <ulink url="http://wiki.jboss.org/wiki/Wiki.jsp?page=JGroups">http://wiki.jboss.org/wiki/Wiki.jsp?page=JGroups</ulink>
+ </para>
+ </section>
+
+ <section id="conf.postoffice.clustered.attributes.threadpoolsize">
+ <title>ThreadPoolSize</title>
+ <para>
+ The post office uses a thread pool for dispatching requests/handling responses from the cluster. This attribute represents the maximum size of
+ that pool
+ </para>
+ <para>The default value of this is <literal>50</literal> threads</para>
+ </section>
+
+ </section>
+ </section>
+ </section>
+
+
+
+ <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>
JBoss Messaging ships with a JDBC Persistence Manager used for handling persistence of
message data in a relational database accessed via JDBC. The Persistence Manager
@@ -182,16 +897,17 @@
<para>
JBoss Messaging also ships with pre-made Persistence Manager configurations for MySQL,
- Oracle, PostgreSQL and Sybase. The example <filename>mysql-persistence-service.xml</filename>,
+ Oracle, PostgreSQL, Sybase and MS SQL Server. The example <filename>mysql-persistence-service.xml</filename>,
<filename>oracle-persistence-service.xml</filename>,
<filename>postgres-persistence-service.xml</filename> and
- <filename>sybase-persistence-service.xml</filename> configuration files are available
+ <filename>sybase-persistence-service.xml</filename> and
+ <filename>mssql-persistence-service.xml</filename> configuration files are available
in the <filename>examples/config</filename> directory of the release bundle.
</para>
<para>
- Configurations for MSSQL and other popular databases should be available soon. Users are
- encouraged to contribute their own configuration files. The JDBC Persistence Manager has been designed
+ 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.
@@ -201,160 +917,328 @@
The default Hypersonic persistence configuration file is listed below:
</para>
- <programlisting>
-<server>
- <mbean code="org.jboss.messaging.core.plugin.JDBCPersistenceManager"
- name="jboss.messaging:service=PersistenceManager"
- xmbean-dd="xmdesc/JDBCPersistenceManager-xmbean.xml">
- <depends>jboss.jca:service=DataSourceBinding,name=DefaultDS</depends>
- <depends optional-attribute-name="TransactionManager">
- jboss:service=TransactionManager</depends>
- <depends optional-attribute-name="ChannelMapper">
- jboss.messaging:service=ChannelMapper</depends>
- <attribute name="DataSource">java:/DefaultDS</attribute>
- <attribute name="CreateTablesOnStartup">true</attribute>
- <attribute name="UsingBatchUpdates">true</attribute>
- </mbean>
+ <programlisting>
- <mbean code="org.jboss.jms.server.plugin.JDBCChannelMapper"
- name="jboss.messaging:service=ChannelMapper"
- xmbean-dd="xmdesc/JDBCChannelMapper-xmbean.xml">
- <depends>jboss.jca:service=DataSourceBinding,name=DefaultDS</depends>
- <depends optional-attribute-name="TransactionManager">
- jboss:service=TransactionManager</depends>
- <attribute name="DataSource">java:/DefaultDS</attribute>
- </mbean>
-</server>
- </programlisting>
+ <server>
+ <mbean code="org.jboss.messaging.core.plugin.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>
+ <attribute name="DataSource">java:/DefaultDS</attribute>
+ <attribute name="CreateTablesOnStartup">true</attribute>
+ <attribute name="UsingBatchUpdates">false</attribute>
+ <attribute name="MaxParams">500</attribute>
+ </mbean>
+
+ <mbean code="org.jboss.messaging.core.plugin.DefaultPostOfficeService"
+ name="jboss.messaging:service=PostOffice"
+ xmbean-dd="xmdesc/DefaultPostOffice-xmbean.xml">
+ <depends optional-attribute-name="ServerPeer">jboss.messaging:service=ServerPeer</depends>
+ <depends>jboss.jca:service=DataSourceBinding,name=DefaultDS</depends>
+ <depends optional-attribute-name="TransactionManager">jboss:service=TransactionManager</depends>
+ <attribute name="PostOfficeName">JMS</attribute>
+ <attribute name="DataSource">java:/DefaultDS</attribute>
+ <attribute name="CreateTablesOnStartup">true</attribute>
+ </mbean>
+
+ <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[
+ POPULATE.TABLES.1=INSERT INTO JBM_USER (USER_ID,PASSWD,CLIENTID) VALUES ('dilbert','dogbert','dilbert-id')
+ ]]></attribute>
+ </mbean>
+
+ </server>
+
+ </programlisting>
+
<para>
An example of a Persistence Manager configuration for a MySQL database follows:
</para>
<programlisting>
-<server>
- <mbean code="org.jboss.messaging.core.plugin.JDBCPersistenceManager"
- name="jboss.messaging:service=PersistenceManager"
- xmbean-dd="xmdesc/JDBCPersistenceManager-xmbean.xml">
+
+ <server>
+
+ <mbean code="org.jboss.messaging.core.plugin.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>
+ <attribute name="DataSource">java:/DefaultDS</attribute>
+ <attribute name="CreateTablesOnStartup">true</attribute>
+ <attribute name="UsingBatchUpdates">true</attribute>
+ <attribute name="SqlProperties"><![CDATA[
+ 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))
+ 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, HEADERS MEDIUMBLOB, PAYLOAD LONGBLOB, CHANNEL_COUNT INTEGER, TYPE TINYINT, PRIMARY KEY (MESSAGE_ID))
+ CREATE_TRANSACTION=CREATE TABLE JBM_TX (TRANSACTION_ID BIGINT, BRANCH_QUAL VARBINARY(254), FORMAT_ID INTEGER, GLOBAL_TXID VARBINARY(254), PRIMARY KEY (TRANSACTION_ID))
+ CREATE_COUNTER=CREATE TABLE JBM_COUNTER (NAME VARCHAR(255), NEXT_ID BIGINT, PRIMARY KEY(NAME))
+ 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=SELECT MESSAGE_ID FROM JBM_MSG_REF WHERE CHANNEL_ID = ? AND MESSAGE_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, HEADERS, PAYLOAD, CHANNEL_COUNT, TYPE) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?)
+ INC_CHANNEL_COUNT=UPDATE JBM_MSG SET CHANNEL_COUNT = CHANNEL_COUNT + 1 WHERE MESSAGE_ID=?
+ DEC_CHANNEL_COUNT=UPDATE JBM_MSG SET CHANNEL_COUNT = CHANNEL_COUNT - 1 WHERE MESSAGE_ID=?
+ DELETE_MESSAGE=DELETE FROM JBM_MSG WHERE MESSAGE_ID=? AND CHANNEL_COUNT=0
+ MESSAGE_ID_COLUMN=MESSAGE_ID
+ MESSAGE_EXISTS=SELECT MESSAGE_ID FROM JBM_MSG WHERE MESSAGE_ID = ? FOR UPDATE
+ INSERT_TRANSACTION=INSERT INTO JBM_TX (TRANSACTION_ID, BRANCH_QUAL, FORMAT_ID, GLOBAL_TXID) VALUES(?, ?, ?, ?)
+ DELETE_TRANSACTION=DELETE FROM JBM_TX WHERE TRANSACTION_ID = ?
+ SELECT_PREPARED_TRANSACTIONS=SELECT TRANSACTION_ID, BRANCH_QUAL, FORMAT_ID, GLOBAL_TXID FROM JBM_TX
+ 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
+ ]]></attribute>
+ <attribute name="MaxParams">500</attribute>
+ </mbean>
+
+ <mbean code="org.jboss.messaging.core.plugin.DefaultPostOfficeService"
+ name="jboss.messaging:service=PostOffice"
+ xmbean-dd="xmdesc/DefaultPostOffice-xmbean.xml">
+ <depends optional-attribute-name="ServerPeer">jboss.messaging:service=ServerPeer</depends>
+ <depends>jboss.jca:service=DataSourceBinding,name=DefaultDS</depends>
+ <depends optional-attribute-name="TransactionManager">jboss:service=TransactionManager</depends>
+ <attribute name="PostOfficeName">JMS</attribute>
+ <attribute name="DataSource">java:/DefaultDS</attribute>
+ <attribute name="CreateTablesOnStartup">true</attribute>
+ <attribute name="SqlProperties"><![CDATA[
+ CREATE_POSTOFFICE_TABLE=CREATE TABLE JBM_POSTOFFICE (POSTOFFICE_NAME VARCHAR(255), NODE_ID INTEGER, QUEUE_NAME VARCHAR(1023), COND VARCHAR(1023), SELECTOR VARCHAR(1023), CHANNEL_ID BIGINT, CLUSTERED CHAR(1))
+ INSERT_BINDING=INSERT INTO JBM_POSTOFFICE (POSTOFFICE_NAME, NODE_ID, QUEUE_NAME, COND, SELECTOR, CHANNEL_ID, CLUSTERED) VALUES (?, ?, ?, ?, ?, ?, ?)
+ DELETE_BINDING=DELETE FROM JBM_POSTOFFICE WHERE POSTOFFICE_NAME=? AND NODE_ID=? AND QUEUE_NAME=?
+ LOAD_BINDINGS=SELECT NODE_ID, QUEUE_NAME, COND, SELECTOR, CHANNEL_ID, CLUSTERED FROM JBM_POSTOFFICE WHERE POSTOFFICE_NAME = ?
+ ]]></attribute>
+ </mbean>
+
+ <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))
+ 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))
+ 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>
+
+ </server>
+
+ </programlisting>
+
+ <section id="conf.persistencemanager.attributes">
+
+
+ <title>
+ We now discuss the MBean attributes of the PersistenceManager MBean
+ </title>
+
+ <section id="conf.persistencemanager.attributes.createtables">
+ <title>CreateTablesOnStartup</title>
+
+ <para>
+ Set this to <literal>true</literal> if you wish the Persistence Manager to attempt
+ to create the tables (and indexes) when it starts. If the tables (or indexes)
+ already exist a <literal>SQLException</literal> will be thrown by the JDBC driver and
+ ignored by the Persistence Manager, allowing it to continue.
+ </para>
+ <para>
+ By default the value of <literal>CreateTablesOnStartup</literal> attribute
+ is set to <literal>true</literal>
+ </para>
+ </section>
+
+ <section id="conf.persistencemanager.attributes.batchupdates">
+ <title>UsingBatchUpdates</title>
+
+ <para>
+ Set this to <literal>true</literal> if the database supports JDBC batch updates.
+ The JDBC Persistence Manager will then group multiple database updates in batches
+ to aid performance.
+ </para>
+ <para>
+ By default the value of <literal>UsingBatchUpdates</literal> attribute
+ is set to <literal>false</literal>
+ </para>
+ </section>
+
+ <section id="conf.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 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>
+ </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>
+ By default the value of <literal>UsingTrailingByte</literal> attribute
+ is set to <literal>false</literal>
+ </para>
+ </section>
+
+ <section id="conf.persistencemanager.attributes.sqlproperties">
+ <title>SQLProperties</title>
+
+ <para>
+ This is where the DDL and DML for the particular database is specified.
+ If a particular DDL or DML statement is not overridden, the default Hypersonic
+ configuration will be used for that statement.
+ </para>
+ </section>
+
+ <section id="conf.persistencemanager.attributes.maxparams">
+ <title>MaxParams</title>
+
+ <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>
+ <para>
+ By default the value of <literal>MaxParams</literal> attribute
+ is set to <literal>100</literal>
+ </para>
+ </section>
+
+ </section>
+
+ </section>
+
+
+ <section id="conf.jmsusermanager">
+ <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>
+
+ <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>
- <depends optional-attribute-name="ChannelMapper">
- jboss.messaging:service=ChannelMapper</depends>
+ <depends optional-attribute-name="TransactionManager">jboss:service=TransactionManager</depends>
<attribute name="DataSource">java:/DefaultDS</attribute>
<attribute name="CreateTablesOnStartup">true</attribute>
- <attribute name="UsingBatchUpdates">true</attribute>
<attribute name="SqlProperties"><![CDATA[
-CREATE_MESSAGE_REF=CREATE TABLE JMS_MESSAGE_REFERENCE
- (CHANNELID BIGINT, MESSAGEID BIGINT, TRANSACTIONID BIGINT, STATE CHAR(1),
- ORD BIGINT, DELIVERYCOUNT INTEGER, RELIABLE CHAR(1), LOADED CHAR(1),
- PRIMARY KEY(CHANNELID, MESSAGEID))
-CREATE_IDX_MESSAGE_REF_TX=CREATE INDEX JMS_MESSAGE_REF_TX ON
- JMS_MESSAGE_REFERENCE (TRANSACTIONID)
-CREATE_IDX_MESSAGE_REF_ORD=CREATE INDEX JMS_MESSAGE_REF_ORD ON JMS_MESSAGE_REFERENCE (ORD)
-CREATE_IDX_MESSAGE_REF_MESSAGEID=CREATE INDEX JMS_MESSAGE_REF_MESSAGEID ON
- JMS_MESSAGE_REFERENCE (MESSAGEID)
-CREATE_IDX_MESSAGE_REF_LOADED=CREATE INDEX JMS_MESSAGE_REF_LOADED ON
- JMS_MESSAGE_REFERENCE (LOADED)
-CREATE_IDX_MESSAGE_REF_RELIABLE=CREATE INDEX JMS_MESSAGE_REF_RELIABLE ON
- JMS_MESSAGE_REFERENCE (RELIABLE)
-INSERT_MESSAGE_REF=INSERT INTO JMS_MESSAGE_REFERENCE (CHANNELID, MESSAGEID,
- TRANSACTIONID, STATE, ORD, DELIVERYCOUNT, RELIABLE, LOADED)
- VALUES (?, ?, ?, ?, ?, ?, ?, ?)
-.... ]]>
- </attribute>
- <attribute name="MaxParams">500</attribute>
+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))
+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))
+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>
- <mbean code="org.jboss.jms.server.plugin.JDBCChannelMapper"
- name="jboss.messaging:service=ChannelMapper"
- xmbean-dd="xmdesc/JDBCChannelMapper-xmbean.xml">
- <depends>jboss.jca:service=DataSourceBinding,name=DefaultDS</depends>
- <depends optional-attribute-name="TransactionManager">
- jboss:service=TransactionManager</depends>
- <attribute name="DataSource">java:/DefaultDS</attribute>
- <attribute name="SqlProperties"><![CDATA[
-CREATE_USER_TABLE=CREATE TABLE JMS_USER (USERID VARCHAR(32) NOT NULL,
- PASSWD VARCHAR(32) NOT NULL, CLIENTID VARCHAR(128), PRIMARY KEY(USERID))
-CREATE_ROLE_TABLE=CREATE TABLE JMS_ROLE (ROLEID VARCHAR(32) NOT NULL,
- USERID VARCHAR(32) NOT NULL, PRIMARY KEY(USERID, ROLEID))
-SELECT_PRECONF_CLIENTID=SELECT CLIENTID FROM JMS_USER WHERE USERID=?
-....
- ]]>
- </attribute>
- </mbean>
-</server>
- </programlisting>
+ </programlisting>
- <section id="conf.changingds">
- <title>Changing the Database</title>
+ <section id="conf.persistencemanager.attributes">
- <para>
- If the database you want to switch to is one of MySQL, Oracle or Postgres,
- persistence configuration files are already available in
- the <filename>examples/config</filename> directory of the release bundle.
- </para>
- <para>
- In order to enable support for one of these databases, just replace the default
- <filename>hsqldb-persistence-service.xml</filename> configuration file with the
- database-specific configuration file and restart the server.
- </para>
+ <title>
+ We now discuss the MBean attributes of the PersistenceManager MBean
+ </title>
- <para>
- Also, be aware that by default, the Messaging services relying on a datastore
- are referencing <literal>"java:/DefaultDS"</literal> for the datasource.
- If you are deploying a datasource with a different JNDI name, you need to update
- all the <literal>DataSource</literal> attribute in the persistence configuration file.
- </para>
+ <section 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 <literal>SQLException</literal> will be thrown by the JDBC driver and
+ ignored by the Persistence Manager, allowing it to continue.
+ </para>
+ <para>
+ By default the value of <literal>CreateTablesOnStartup</literal> attribute
+ is set to <literal>true</literal>
+ </para>
</section>
- <section id="conf.persistence.createtables">
- <title>CreateTablesOnStartup</title>
+ <section id="conf.jmsusermanager.attributes.batchupdates">
+ <title>UsingBatchUpdates</title>
- <para>
- Set this to <literal>true</literal> if you wish the Persistence Manager to attempt
- to create the tables (and indexes) when it starts. If the tables (or indexes)
- already exist a <literal>SQLException</literal> will be thrown by the JDBC driver and
- ignored by the Persistence Manager, allowing it to continue.
- </para>
- <para>
- By default the value of <literal>CreateTablesOnStartup</literal> attribute
- is set to <literal>true</literal>
- </para>
- </section>
+ <para>
+ Set this to <literal>true</literal> if the database supports JDBC batch updates.
+ The JDBC Persistence Manager will then group multiple database updates in batches
+ to aid performance.
+ </para>
+ <para>
+ By default the value of <literal>UsingBatchUpdates</literal> attribute
+ is set to <literal>false</literal>
+ </para>
+ </section>
- <section id="conf.persistence.batchupdates">
- <title>UsingBatchUpdates</title>
- <para>
- Set this to <literal>true</literal> if the database supports JDBC batch updates.
- The JDBC Persistence Manager will then group multiple database updates in batches
- to aid performance.
- </para>
- <para>
- By default the value of <literal>UsingBatchUpdates</literal> attribute
- is set to <literal>false</literal>
- </para>
- </section>
+ <section id="conf.jmsusermanager.attributes.sqlproperties">
+ <title>SQLProperties</title>
- <section id="conf.persistence.sqlproperties">
- <title>SQLProperties</title>
+ <para>
+ This is where the DDL and DML for the particular database is specified.
+ If a particular DDL or DML statement is not overridden, the default Hypersonic
+ configuration will be used for that statement.
+ </para>
- <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>
+ <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>
+ </section>
+
+
</section>
</section>
+
<section id="conf.destination">
<title>Configuring Destinations</title>
- <section id="conf.preconf.destinations">
+<section id="conf.preconf.destinations">
<title>Pre-configured destinations</title>
<para>
@@ -365,159 +1249,760 @@
</para>
<programlisting>
+ <!--
+ The Default Dead Letter Queue. This destination is a dependency of an EJB MDB container.
+ -->
-<!-- The 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.Queue"
- name="jboss.messaging.destination:service=Queue,name=DLQ"
- xmbean-dd="xmdesc/Queue-xmbean.xml">
- <depends optional-attribute-name="ServerPeer">
- jboss.messaging:service=ServerPeer</depends>
-</mbean>
-....
+ <mbean code="org.jboss.jms.server.destination.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.Topic"
- name="jboss.messaging.destination:service=Topic,name=testTopic"
- xmbean-dd="xmdesc/Topic-xmbean.xml">
- <depends optional-attribute-name="ServerPeer">
- jboss.messaging:service=ServerPeer</depends>
- <attribute name="SecurityConfig">
- <security>
- <role name="guest" read="true" write="true"/>
- <role name="publisher" read="true" write="true" create="false"/>
- <role name="durpublisher" read="true" write="true" create="true"/>
- </security>
- </attribute>
-</mbean>
+ <mbean code="org.jboss.jms.server.destination.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.Queue"
- name="jboss.messaging.destination:service=Queue,name=testQueue"
- xmbean-dd="xmdesc/Queue-xmbean.xml">
- <depends optional-attribute-name="ServerPeer">
- jboss.messaging:service=ServerPeer</depends>
- <attribute name="SecurityConfig">
- <security>
- <role name="guest" read="true" write="true"/>
- <role name="publisher" read="true" write="true" create="false"/>
- <role name="noacc" read="false" write="false" create="false"/>
- </security>
- </attribute>
-</mbean>
+ <mbean code="org.jboss.jms.server.destination.QueueService"
+ name="jboss.messaging.destination:service=Queue,name=testQueue"
+ xmbean-dd="xmdesc/Queue-xmbean.xml">
+ <depends optional-attribute-name="ServerPeer">jboss.messaging:service=ServerPeer</depends>
+ <depends>jboss.messaging:service=PostOffice</depends>
+ <attribute name="SecurityConfig">
+ <security>
+ <role name="guest" read="true" write="true"/>
+ <role name="publisher" read="true" write="true" create="false"/>
+ <role name="noacc" read="false" write="false" create="false"/>
+ </security>
+ </attribute>
+ </mbean>
+ <mbean code="org.jboss.jms.server.destination.QueueService"
+ name="jboss.messaging.destination:service=Queue,name=A"
+ xmbean-dd="xmdesc/Queue-xmbean.xml">
+ <depends optional-attribute-name="ServerPeer">jboss.messaging:service=ServerPeer</depends>
+ <depends>jboss.messaging:service=PostOffice</depends>
+ </mbean>
+
+
+ <!-- It's possible for indiviual queues and topics to use a specific queue for
+ an expiry or DLQ -->
+
+ <mbean code="org.jboss.jms.server.destination.QueueService"
+ name="jboss.messaging.destination:service=Queue,name=PrivateDLQ"
+ xmbean-dd="xmdesc/Queue-xmbean.xml">
+ <depends optional-attribute-name="ServerPeer">jboss.messaging:service=ServerPeer</depends>
+ <depends>jboss.messaging:service=PostOffice</depends>
+ </mbean>
+
+ <mbean code="org.jboss.jms.server.destination.QueueService"
+ name="jboss.messaging.destination:service=Queue,name=PrivateExpiryQueue"
+ xmbean-dd="xmdesc/Queue-xmbean.xml">
+ <depends optional-attribute-name="ServerPeer">jboss.messaging:service=ServerPeer</depends>
+ <depends>jboss.messaging:service=PostOffice</depends>
+ </mbean>
+
+ <mbean code="org.jboss.jms.server.destination.QueueService"
+ name="jboss.messaging.destination:service=Queue,name=QueueWithOwnDLQAndExpiryQueue"
+ xmbean-dd="xmdesc/Queue-xmbean.xml">
+ <depends optional-attribute-name="ServerPeer">jboss.messaging:service=ServerPeer</depends>
+ <depends>jboss.messaging:service=PostOffice</depends>
+ <attribute name="DLQ">jboss.messaging.destination:service=Queue,name=PrivateDLQ</attribute>
+ <attribute name="ExpiryQueue">jboss.messaging.destination:service=Queue,name=PrivateExpiryQueue</attribute>
+ </mbean>
+
+ <mbean code="org.jboss.jms.server.destination.TopicService"
+ name="jboss.messaging.destination:service=Topic,name=TopicWithOwnDLQAndExpiryQueue"
+ xmbean-dd="xmdesc/Topic-xmbean.xml">
+ <depends optional-attribute-name="ServerPeer">jboss.messaging:service=ServerPeer</depends>
+ <depends>jboss.messaging:service=PostOffice</depends>
+ <attribute name="DLQ">jboss.messaging.destination:service=Queue,name=PrivateDLQ</attribute>
+ <attribute name="ExpiryQueue">jboss.messaging.destination:service=Queue,name=PrivateExpiryQueue</attribute>
+ </mbean>
+
+
+ <mbean code="org.jboss.jms.server.destination.TopicService"
+ name="jboss.messaging.destination:service=Topic,name=TopicWithOwnRedeliveryDelay"
+ xmbean-dd="xmdesc/Topic-xmbean.xml">
+ <depends optional-attribute-name="ServerPeer">jboss.messaging:service=ServerPeer</depends>
+ <depends>jboss.messaging:service=PostOffice</depends>
+ <attribute name="RedeliveryDelay">5000</attribute>
+ </mbean>
+
+
+ <mbean code="org.jboss.jms.server.destination.TopicService"
+ name="jboss.messaging.destination:service=Topic,name=testDistributedTopic"
+ xmbean-dd="xmdesc/Topic-xmbean.xml">
+ <depends optional-attribute-name="ServerPeer">jboss.messaging:service=ServerPeer</depends>
+ <depends>jboss.messaging:service=PostOffice</depends>
+ <attribute name="Clustered">true</attribute>
+ </mbean>
....
</programlisting>
+ </section>
+
+
+ <section id="conf.destination.queue">
+
+ <title>Configuring queues</title>
+
+ <section id="conf.destination.queue.attributes">
+
+ <title>
+ We now discuss the MBean attributes of the Queue MBean
+ </title>
+
+ <section id="conf.destination.queue.attributes.name">
+ <title>Name</title>
+ <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>
+ </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>
+ </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>
+ </section>
+
+ <section id="conf.destination.queue.attributes.redeliverydelay">
+ <title>RedeliveryDelay</title>
+ <para>The redlivery delay to be used for this queue. Overrides any value set on the ServerPeer config</para>
+ </section>
+
+ <section id="conf.destination.queue.attributes.security">
+ <title>Destination Security Configuration</title>
+
+ <para>
+ <literal>SecurityConfig</literal> - allows you to determine which roles are allowed
+ to read, write and create on the destination. It has exactly the same syntax and
+ semantics as the security configuration in JBossMQ destinations.
+ </para>
+
+ <para>
+ The <literal>SecurityConfig</literal> element should contain one
+ <literal><security></literal> element. The <literal><security></literal>
+ element can contain multiple <literal><role></literal> elements.
+ Each <literal><role></literal> element defines the access for that
+ particular role.
+ </para>
+
+ <para>
+ If the <literal>read</literal> attribute is <literal>true</literal> then that role
+ will be able to read (create consumers, receive messaages or browse) this destination.
+ </para>
+
+ <para>
+ If the <literal>write</literal> attribute is <literal>true</literal> then that role
+ will be able to write (create producers or send messages) to this destination.
+ </para>
+
+ <para>
+ If the <literal>create</literal> attribute is <literal>true</literal> then that role
+ will be able to create durable subscriptions on this destination.
+ </para>
+
+ <para>
+ Note that the security configuration for a destination is optional. If a
+ <literal>SecurityConfig</literal> element is not specifed then the default
+ security configuration from the Server Peer will be used.
+ </para>
+ </section>
+
+ <section id="conf.destination.queue.attributes.paging">
+ <title>Destination paging parameters</title>
+
+ <para>
+ 'Pageable Channels' are a sophisticated new feature available in JBoss Messaging.
+ </para>
+
+ <para>
+ If your application needs to support very large queues or subscriptions containing
+ potentially millions of messages, then it's not possible to store them all in
+ memory at once.
+ </para>
+
+ <para>
+ JBoss Messaging solves this problem but letting you specify the
+ maximum number of messages that can be stored in memory at any one time,
+ on a queue-by-queue, or topic-by-topic basis. JBoss Messaging then pages messages
+ to and from storage transparently in blocks, allowing queues and subscriptions to
+ grow to very large sizes without any performance degradation as channel size increases.
+ </para>
+
+ <para>
+ This has been tested with in excess of 10 million 2K messages on very basic hardware
+ and has the potential to scale to much larger number of messages.
+ </para>
+
+ <para>
+ The individual parameters are:
+ </para>
+
+ <para>
+ <literal>FullSize</literal> - this is the maximum number of messages held by the
+ queue or topic subscriptions in memory at any one time. The actual queue or
+ subscription can hold many more messages than this but these are paged to and
+ from storage as necessary as messages are added or consumed.
+ </para>
+
+ <para>
+ <literal>PageSize</literal> - When loading messages from the queue or subscrition
+ this is the maximum number of messages to pre-load in one operation.
+ </para>
+
+ <para>
+ <literal>DownCacheSize</literal> - When paging messages to storage from the queue
+ they first go into a "Down Cache" before being written to storage. This enables the
+ write to occur as a single operation thus aiding performance. This setting determines
+ the max number of messages that the Down Cache will hold before they are flushed
+ to storage.
+ </para>
+
+ <para>
+ If no values for <literal>FullSize</literal>, <literal>PageSize</literal>,
+ or <literal>DownCacheSize</literal> are specified they will default to values
+ 75000, 2000, 2000 respectively.
+ </para>
+
+ <para>
+ If you want to specify the paging parameters used for temporary queues then you need to specify them
+ on the appropriate connection factory.
+ See connection factory configuration for details.
+ </para>
+ </section>
+
+ <section id="conf.destination.queue.attributes.createdprogrammatically">
+ <title>CreatedProgrammatically</title>
+
+ <para>
+ Returns <literal>true</literal> if the queue was created programmatically
+ </para>
+ </section>
+
+ <section id="conf.destination.queue.attributes.messagecount">
+ <title>MessageCount</title>
+
+ <para>
+ Returns the total number of messages in the queue = number not being delivered + number being delivered + number being scheduled
+ </para>
+ </section>
+
+ <section id="conf.destination.queue.attributes.scheduledmessagecount">
+ <title>ScheduledMessageCount</title>
+
+ <para>
+ Returns the number of scheduled messages in the queue. This is the number of messages scheduled to be delivered at a later date.
+ </para>
+ </section>
+
+ <section id="conf.destination.queue.attributes.maxsize">
+ <title>MaxSize</title>
+
+ <para>
+ A maximum size (in 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>
+ </section>
+
+ <section id="conf.destination.queue.attributes.clustered">
+ <title>Clustered</title>
+
+ <para>
+ Clustered destinations must have this set to <literal>true</literal>
+ </para>
+ </section>
+
+ <section id="conf.destination.queue.attributes.messagecounter">
+ <title>MessageCounter</title>
+
+ <para>
+ Each queue maintains a message counter.
+ </para>
+ </section>
+
+ <section id="conf.destination.queue.attributes.messagecounterstats">
+ <title>MessageCounterStatistics</title>
+
+ <para>
+ The statistics for the message counter
+ </para>
+ </section>
+
+ <section id="conf.destination.queue.attributes.messagecounterhistorydaylimit">
+ <title>MessageCounterHistoryDayLimit</title>
+
+ <para>
+ The maximum number of days to hold message counter history for. Overrides any value set on the ServerPeer.
+ </para>
+ </section>
+
+ <section id="conf.destination.queue.attributes.consumercount">
+ <title>ConsumerCount</title>
+
+ <para>
+ The number of consumers currently consuming from the queue.
+ </para>
+ </section>
+
</section>
- <section id="conf.destination.config.paramters">
- <title>Destination Configuration Parameters</title>
- <section id="conf.destination.security">
- <title>Destination Security Configuration</title>
+ <section id="conf.destination.queue.operations">
- <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>
+ <title>
+ We now discuss the MBean operations of the Queue MBean
+ </title>
- <para>
- The <literal>SecurityConfig</literal> element should contain one
- <literal><security></literal> element. The <literal><security></literal>
- element can contain multiple <literal><role></literal> elements.
- Each <literal><role></literal> element defines the access for that
- particular role.
- </para>
+ <section id="conf.destination.queue.operations.removeallmessages">
+ <title>RemoveAllMessages</title>
- <para>
- If the <literal>read</literal> attribute is <literal>true</literal> then that role
- will be able to read (create consumers, receive messaages or browse) this destination.
- </para>
+ <para>
+ Remove (and delete) all messages from the queue.
+ <warning>Use this with caution. It will permanently delete all messages from the queue</warning>
+ </para>
+ </section>
- <para>
- If the <literal>write</literal> attribute is <literal>true</literal> then that role
- will be able to write (create producers or send messages) to this destination.
- </para>
+ <section id="conf.destination.queue.operations.listallmessages">
+ <title>ListAllMessages</title>
- <para>
- If the <literal>create</literal> attribute is <literal>true</literal> then that role
- will be able to create durable subscriptions on this destination.
- </para>
+ <para>
+ List all messages currently in the queue
+ </para>
+ <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>
+ </section>
- <para>
- Note that the security configuration for a destination is optional. If a
- <literal>SecurityConfig</literal> element is not specifed then the default
- security configuration from the Server Peer will be used.
- </para>
- </section>
+ <section id="conf.destination.queue.operations.listdurablemessages">
+ <title>ListDurableMessages</title>
- <section id="conf.destination.paging">
- <title>Destination paging parameters</title>
+ <para>
+ As listAllMessages but only lists the durable messages
+ </para>
+ <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>
+ </section>
- <para>
- 'Pageable Channels' are a sophisticated new feature available in JBoss Messaging.
- </para>
- <para>
- If your application needs to support very large queues or subscriptions containing
- potentially millions of messages, then it's not possible to store them all in
- memory at once.
- </para>
+ <section id="conf.destination.queue.operations.listnondurablemessages">
+ <title>ListNonDurableMessages</title>
- <para>
- JBoss Messaging solves this problem but letting you specify the
- maximum number of messages that can be stored in memory at any one time,
- on a queue-by-queue, or topic-by-topic basis. JBoss Messaging then pages messages
- to and from storage transparently in blocks, allowing queues and subscriptions to
- grow to very large sizes without any performance degradation as channel size increases.
- </para>
+ <para>
+ As listAllMessages but only lists the non durable messages
+ </para>
+ <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>
+ </section>
- <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>
+ <section id="conf.destination.queue.operations.resetmessagecounter">
+ <title>ResetMessageCounter</title>
- <para>
- The individual parameters are:
- </para>
+ <para>
+ Resets the message counter to zero.
+ </para>
+ </section>
- <para>
- <literal>FullSize</literal> - this is the maximum number of messages held by the
- queue or topic subscriptions in memory at any one time. The actual queue or
- subscription can hold many more messages than this but these are paged to and
- from storage as necessary as messages are added or consumed.
- </para>
+ <section id="conf.destination.queue.operations.resetmessagecounterhistory">
+ <title>ResetMessageCounterHistory</title>
- <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>
+ Resets the message counter history.
+ </para>
+ </section>
- <para>
- <literal>DownCacheSize</literal> - When paging messages to storage from the queue
- they first go into a "Down Cache" before being written to storage. This enables the
- write to occur as a single operation thus aiding performance. This setting determines
- the max number of messages that the Down Cache will hold before they are flushed
- to storage.
- </para>
+ <section id="conf.destination.queue.operations.listmessagecounterashtml">
+ <title>ListMessageCounterAsHTML</title>
- <para>
- If no values for <literal>FullSize</literal>, <literal>PageSize</literal>,
- or <literal>DownCacheSize</literal> are specified they will default to values
- 75000, 2000, 2000 respectively.
- </para>
+ <para>
+ Lists the message counter in an easy to display HTML format
+ </para>
+ </section>
- <para>
- If you want to specify the paging parameters used for temporary queues then you need to specify them
- on the appropriate connection factory.
- See connection factory configuration for details.
- </para>
+ <section id="conf.destination.queue.operations.listmessagecounterhistoryashtml">
+ <title>ListMessageCounterHistoryAsHTML</title>
+
+ <para>
+ Lists the message counter history in an easy to display HTML format
+ </para>
+ </section>
+
+
+ </section>
+
+ </section>
+
+
+
+
+ <section id="conf.destination.topics">
+
+ <title>Configuring topics</title>
+
+ <section id="conf.destination.topic.attributes">
+
+ <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>
+ </section>
+
+ <section id="conf.destination.topic.attributes.jndiName">
+ <title>JNDIName</title>
+ <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>
+ </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>
+ </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>
+ </section>
+
+ <section id="conf.destination.topic.attributes.security">
+ <title>Destination Security Configuration</title>
+
+ <para>
+ <literal>SecurityConfig</literal> - allows you to determine which roles are allowed
+ to read, write and create on the destination. It has exactly the same syntax and
+ semantics as the security configuration in JBossMQ destinations.
+ </para>
+
+ <para>
+ The <literal>SecurityConfig</literal> element should contain one
+ <literal><security></literal> element. The <literal><security></literal>
+ element can contain multiple <literal><role></literal> elements.
+ Each <literal><role></literal> element defines the access for that
+ particular role.
+ </para>
+
+ <para>
+ If the <literal>read</literal> attribute is <literal>true</literal> then that role
+ will be able to read (create consumers, receive messaages or browse) this destination.
+ </para>
+
+ <para>
+ If the <literal>write</literal> attribute is <literal>true</literal> then that role
+ will be able to write (create producers or send messages) to this destination.
+ </para>
+
+ <para>
+ If the <literal>create</literal> attribute is <literal>true</literal> then that role
+ will be able to create durable subscriptions on this destination.
+ </para>
+
+ <para>
+ Note that the security configuration for a destination is optional. If a
+ <literal>SecurityConfig</literal> element is not specifed then the default
+ security configuration from the Server Peer will be used.
+ </para>
+ </section>
+
+ <section id="conf.destination.topic.attributes.paging">
+ <title>Destination paging parameters</title>
+
+ <para>
+ 'Pageable Channels' are a sophisticated new feature available in JBoss Messaging.
+ </para>
+
+ <para>
+ If your application needs to support very large queues or subscriptions containing
+ potentially millions of messages, then it's not possible to store them all in
+ memory at once.
+ </para>
+
+ <para>
+ JBoss Messaging solves this problem but letting you specify the
+ maximum number of messages that can be stored in memory at any one time,
+ on a queue-by-queue, or topic-by-topic basis. JBoss Messaging then pages messages
+ to and from storage transparently in blocks, allowing queues and subscriptions to
+ grow to very large sizes without any performance degradation as channel size increases.
+ </para>
+
+ <para>
+ This has been tested with in excess of 10 million 2K messages on very basic hardware
+ and has the potential to scale to much larger number of messages.
+ </para>
+
+ <para>
+ The individual parameters are:
+ </para>
+
+ <para>
+ <literal>FullSize</literal> - this is the maximum number of messages held by the
+ queue or topic subscriptions in memory at any one time. The actual queue or
+ subscription can hold many more messages than this but these are paged to and
+ from storage as necessary as messages are added or consumed.
+ </para>
+
+ <para>
+ <literal>PageSize</literal> - When loading messages from the queue or subscrition
+ this is the maximum number of messages to pre-load in one operation.
+ </para>
+
+ <para>
+ <literal>DownCacheSize</literal> - When paging messages to storage from the queue
+ they first go into a "Down Cache" before being written to storage. This enables the
+ write to occur as a single operation thus aiding performance. This setting determines
+ the max number of messages that the Down Cache will hold before they are flushed
+ to storage.
+ </para>
+
+ <para>
+ If no values for <literal>FullSize</literal>, <literal>PageSize</literal>,
+ or <literal>DownCacheSize</literal> are specified they will default to values
+ 75000, 2000, 2000 respectively.
+ </para>
+
+ <para>
+ If you want to specify the paging parameters used for temporary queues then you need to specify them
+ on the appropriate connection factory.
+ See connection factory configuration for details.
+ </para>
+ </section>
+
+ <section id="conf.destination.topic.attributes.createdprogrammatically">
+ <title>CreatedProgrammatically</title>
+
+ <para>
+ Returns <literal>true</literal> if the topic was created programmatically
+ </para>
+ </section>
+
+ <section id="conf.destination.topic.attributes.maxsize">
+ <title>MaxSize</title>
+
+ <para>
+ A maximum size (in 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 unbounded.
+ </para>
+ </section>
+
+ <section id="conf.destination.topic.attributes.clustered">
+ <title>Clustered</title>
+
+ <para>
+ Clustered destinations must have this set to <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>
+ </section>
+
+ <section id="conf.destination.topic.attributes.messagecounters">
+ <title>MessageCounters</title>
+
+ <para>
+ Return a list of the message counters for the subscriptions of this topic.
+ </para>
+ </section>
+
+ <section id="conf.destination.topic.attributes.allmessagecount">
+ <title>AllMessageCount</title>
+
+ <para>
+ Return the total number of messages in all subscriptions of this topic.
+ </para>
+ </section>
+
+ <section id="conf.destination.topic.attributes.durablemessagecount">
+ <title>DurableMessageCount</title>
+
+ <para>
+ Return the total number of durable messages in all subscriptions of this topic.
+ </para>
+
+ </section>
+
+ <section id="conf.destination.topic.attributes.nondurablemessagecount">
+ <title>NonDurableMessageCount</title>
+
+ <para>
+ Return the total number of non durable messages in all subscriptions of this topic.
+ </para>
+ </section>
+
+ <section id="conf.destination.topic.attributes.allsubscriptionscount">
+ <title>AllSubscriptionsCount</title>
+
+ <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>
+ </section>
+
+ <section id="conf.destination.topic.attributesnon.durablesubscriptionscount">
+ <title>NonDurableSubscriptionsCount</title>
+
+ <para>
+ The count of all non durable subscriptions on this topic
+ </para>
</section>
+
+
</section>
+
+ <section id="conf.destination.topic.operations">
+
+ <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.
+ <warning>Use this with caution. It will permanently delete all messages from the topic</warning>
+ </para>
+ </section>
+
+ <section id="conf.destination.topic.operations.listallsubscriptions">
+ <title>ListAllSubscriptions</title>
+
+ <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>
+ </section>
+
+ <section id="conf.destination.topic.operations.listnondurablesubscriptions">
+ <title>ListNonDurableSubscriptions</title>
+
+ <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>
+ </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>
+ </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>
+ </section>
+
+ <section id="conf.destination.topic.operations.listallmessages">
+ <title>ListAllMessages</title>
+
+ <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 you can limit the messages returned.
+ </para>
+ </section>
+
+ <section id="conf.destination.topic.operations.listnondurablemessages">
+ <title>ListNonDurableMessages</title>
+
+ <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 you can limit the messages returned.
+ </para>
+ </section>
+
+ <section id="conf.destination.topic.operations.listdurablemessages">
+ <title>ListDurableMessages</title>
+
+ <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 you can limit the messages returned.
+ </para>
+ </section>
+
+ </section>
+
+ </section>
+
+
+
<section id="conf.destination.new">
<title>Deploying a new destination</title>
@@ -541,27 +2026,27 @@
<programlisting>
<?xml version="1.0" encoding="UTF-8"?>
<server>
- <loader-repository>jboss.messaging:loader=ScopedLoaderRepository
- <loader-repository-config>java2ParentDelegation=false</loader-repository-config>
- </loader-repository>
- <mbean
- code="org.jboss.jms.server.destination.Queue"
- name="jboss.messaging.destination:service=Queue,name=testQueue"
- xmbean-dd="xmdesc/Queue-xmbean.xml">
- <depends optional-attribute-name="ServerPeer">
- jboss.messaging:service=ServerPeer
- </depends>
- <attribute name="SecurityConfig">
- <security>
- <role name="guest" read="true"write="true"/>
- <role name="publisher" read="true" write="true" create="false"/>
- <role name="noacc" read="false" write="false" create="false"/>
- </security>
- </attribute>
- <attribute name="fullSize">75000</attribute>
- <attribute name="pageSize">2000</attribute>
- <attribute name="downCacheSize">2000</attribute>
- </mbean>
+ <loader-repository>jboss.messaging:loader=ScopedLoaderRepository
+ <loader-repository-config>java2ParentDelegation=false</loader-repository-config>
+ </loader-repository>
+ <mbean
+ code="org.jboss.jms.server.destination.Queue"
+ name="jboss.messaging.destination:service=Queue,name=testQueue"
+ xmbean-dd="xmdesc/Queue-xmbean.xml">
+ <depends optional-attribute-name="ServerPeer">
+ jboss.messaging:service=ServerPeer
+ </depends>
+ <attribute name="SecurityConfig">
+ <security>
+ <role name="guest" read="true"write="true"/>
+ <role name="publisher" read="true" write="true" create="false"/>
+ <role name="noacc" read="false" write="false" create="false"/>
+ </security>
+ </attribute>
+ <attribute name="fullSize">75000</attribute>
+ <attribute name="pageSize">2000</attribute>
+ <attribute name="downCacheSize">2000</attribute>
+ </mbean>
</server>
</programlisting>
@@ -592,43 +2077,48 @@
</para>
<para>
+ Connection factories can either be clustered or non clustered.
+ Clustered connection factories create subsequent connections on different nodes of the cluster according to the load balancing policy.
+ The default load balancing policy is round robin.
+ </para>
+
+ <para>
An example connection factory configuration is presented below:
</para>
<programlisting>
- errrrrfff eeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeee fffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffff
-<?xml version="1.0" encoding="UTF-8"?>
+
<server>
- <loader-repository>
- jboss.messaging:loader=ScopedLoaderRepository
- <loader-repository-config>
- java2ParentDelegation=false
- </loader-repository-config>
- </loader-repository>
- <mbean
- code="org.jboss.jms.server.connectionfactory.ConnectionFactory"
- name="jboss.messaging.destination:service=ConnectionFactory"
- xmbean-dd="xmdesc/ConnectionFactory-xmbean.xml">
- <constructor>
- <arg type="java.lang.String" value="myClientID"/>
- </constructor>
- <depends optional-attribute-name="ServerPeer">
- jboss.messaging:service=ServerPeer
- </depends>
- <depends optional-attribute-name="Connector">
- jboss.messaging:service=Connector,transport=socket
- </depends>
- <attribute name="PrefetchSize">10</attribute>
- <attribute name="DefaultTempQueueFullSize">1000</attribute>
- <attribute name="DefaultTempQueuePageSize">50</attribute>
- <attribute name="DefaultTempQueueDownCacheSize">50</attribute>
- <attribute name="JNDIBindings">
- <bindings>
- <binding>/MyConnectionFactory1</binding>
- <binding>/factories/cf1</binding>>
- </bindings>
- </attribute>
- </mbean>
+ <loader-repository>
+ jboss.messaging:loader=ScopedLoaderRepository
+ <loader-repository-config>
+ java2ParentDelegation=false
+ </loader-repository-config>
+ </loader-repository>
+ <mbean
+ code="org.jboss.jms.server.connectionfactory.ConnectionFactory"
+ name="jboss.messaging.destination:service=ConnectionFactory"
+ xmbean-dd="xmdesc/ConnectionFactory-xmbean.xml">
+ <constructor>
+ <arg type="java.lang.String" value="myClientID"/>
+ </constructor>
+ <depends optional-attribute-name="ServerPeer">
+ jboss.messaging:service=ServerPeer
+ </depends>
+ <depends optional-attribute-name="Connector">
+ jboss.messaging:service=Connector,transport=socket
+ </depends>
+ <attribute name="PrefetchSize">10</attribute>
+ <attribute name="DefaultTempQueueFullSize">1000</attribute>
+ <attribute name="DefaultTempQueuePageSize">50</attribute>
+ <attribute name="DefaultTempQueueDownCacheSize">50</attribute>
+ <attribute name="JNDIBindings">
+ <bindings>
+ <binding>/MyConnectionFactory1</binding>
+ <binding>/factories/cf1</binding>>
+ </bindings>
+ </attribute>
+ </mbean>
</server>
</programlisting>
@@ -641,18 +2131,71 @@
remoting connector. To use a different remoting connector with the connection factory
change the <literal>Connector</literal> attribute to specify the service name of the connector you wish to use.
</para>
- <para>prefetchSize is an optional attribute that determines how many messages client side message consumers will buffer locally. Pre-fetching messages prevents
- the client having to go to the server each time a message is consumed to say it is ready to receive another message.
- This greatly increases throughput. The default value for prefetchSize is 150. You may want to change this to a smaller value if you are dealing with
- very large messages, so as not to use too much memory on the client.
- </para>
- <para>DefaultTempQueueFullSize, DefaultTempQueuePageSize, DefaultTempQueueDownCacheSize are optional attributes that determine the default paging parameters to be used for
- any temporary destinations scoped to connections created using this connection factory. See the section on paging channels for more information
- on what these values mean.
- They will default to values of 75000, 2000 and 2000 respectively if ommitted.
- </para>
- </section>
+ <section id="conf.connectionfactory.attributes">
+
+ <title>
+ We now discuss the MBean attributes of the ConnectionFactory MBean
+ </title>
+
+ <section id="conf.destination.connectionfactory.attributes.clientid">
+ <title>ClientID</title>
+
+ <para>
+ Connection factories can be pre-configured with a client id. Any connections created using this connection factory will obtain this client id
+ </para>
+ </section>
+
+ <section id="conf.destination.connectionfactory.attributes.jndibindings">
+ <title>JNDIBindings</title>
+
+ <para>
+ Returns a list of the JNDI bindings for this connection factory
+ </para>
+ </section>
+
+ <section id="conf.destination.connectionfactory.attributes.prefetchsize">
+ <title>PrefetchSize</title>
+
+ <para>
+ Each client side consumer maintains a local buffer of messages from which it consumes. The server typically sends messages as fast as it can
+ to the consumer, and when the consumer is full it sends the server a "stop" message to say it is full.
+ When it clears enough space it sends a "start" message to ask the server to continue sending messages.
+ The prefetchSize determines the size of this buffer. Larger values give better throughput.
+ </para>
+ </section>
+
+ <section id="conf.destination.connectionfactory.attributes.tempqueuepaging">
+ <title>Temporary queue paging parameters</title>
+
+ <para>DefaultTempQueueFullSize, DefaultTempQueuePageSize, DefaultTempQueueDownCacheSize are optional attributes that determine the default paging parameters to be used for
+ any temporary destinations scoped to connections created using this connection factory. See the section on paging channels for more information
+ on what these values mean.
+ They will default to values of 200000, 2000 and 2000 respectively if ommitted.
+ </para>
+ </section>
+
+ <section id="conf.destination.connectionfactory.attributes.dupsokbatchsize">
+ <title>DupsOKBatchSize</title>
+
+ <para>When using a session with acknowledge mode of DUPS_OK_ACKNOWLEDGE this setting determines how many acknowledgments it will buffer locally
+ before sending. The default value is <literal>2000</literal>
+ </para>
+ </section>
+
+ <section id="conf.destination.connectionfactory.attributes.connector">
+ <title>Connector</title>
+
+ <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>
+ </section>
+
+ </section>
+
+</section>
+
<section id="conf.connector">
<title>Configuring the remoting connector</title>
@@ -669,25 +2212,26 @@
</para>
<para>
- The default connector is configured to use the remoting socket transport.
+ 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 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 client.
</para>
<para>
- This transport opens TCP connections from client to server for client to server
- communications (e.g. sending messages) and TCP connections from server to client
- for server to client communications (e.g. receiving messages). The transport can be
- configured to use SSL where a higher level of security is required.
- </para>
+ The bisocket transport can be configured to use SSL where a higher level of security is required.
+ </para>
<para>
- Future releases JBoss Messaging will support a bidirectional socket transport
- (similar to UIL2 in JBoss MQ) and an HTTP transport, both of which are useful in
- network environments where TCP connections from server to client are not possible.
- This means, for example, that you could deploy one connection factory that uses
- the HTTP transport for all the connections created from it, and another connection
- factory that uses the socket transport for all connections created from it.
+ 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>
+ <para>No other remoting transports are currently supported by JBoss Messaging</para>
+
<para>
You can look at remoting configuration under:
</para>
@@ -695,7 +2239,7 @@
<para>
<JBoss>/server/<YourMessagingServer>/deploy/jboss-messaging.sar/remoting-service.xml
</para>
-
+
<para>
By default JBoss Messaging binds to ${jboss.bind.address} which can be defined by:
./run.sh -c <yourconfig> -b yourIP.
@@ -703,10 +2247,21 @@
<para>
You can change remoting-service.xml if you want for example use a
- different communication port, or change any other network behavior.
+ different communication port.
</para>
+
+ <warning>Please be wary of changing other settings as they can have an adverse effect on the system</warning>
+
</section>
+ <section id="conf.servicebindingmanager">
+ <title>ServiceBindingManager</title>
+
+ <para>If you are using the JBoss AS ServiceBindingManager to provide different servers with different port ranges, then you must make sure that the JBoss Messaging
+ remoting configuration specified in the JBoss Messaging section of the ServiceBindingManager xml file exactly matches that in remoting-service.xml
+ </para>
+ </section>
+
<section id="conf.callback">
<title>Configuring the callback</title>
@@ -715,15 +2270,15 @@
</para>
<para>
- By default JBoss Messaging will execute InetAddress.getLocalHost().getHostAddress() to access your local host IP, but in case you need to setup a different IP, you can define a system property in your java arguments:
+ By default JBoss Messaging will execute InetAddress.getLocalHost().getHostAddress() to access your local host IP, but in case you need to setup a different IP, you can define a system property in your java arguments:
</para>
<para>
- Use java -Djboss.messaging.callback.bind.address=YourHost - That will determine the callBack host in your client.
+ Use java -Djboss.messaging.callback.bind.address=YourHost - That will determine the callBack host in your client.
</para>
<para>
- The client port will be selected randomly for any non used port. But if you defined -Djboss.messaging.callback.bind.port=NumericPort in your System Properties that number is going to be used for the call back client port.
+ The client port will be selected randomly for any non used port. But if you defined -Djboss.messaging.callback.bind.port=NumericPort in your System Properties that number is going to be used for the call back client port.
</para>
</section>
Modified: trunk/docs/userguide-1.2/en/modules/UG12_gettingstarted.xml
===================================================================
--- trunk/docs/userguide-1.2/en/modules/UG12_gettingstarted.xml 2007-03-01 10:52:35 UTC (rev 2532)
+++ trunk/docs/userguide-1.2/en/modules/UG12_gettingstarted.xml 2007-03-01 17:38:57 UTC (rev 2533)
@@ -52,6 +52,9 @@
of log4j.jar precedes jboss-messaging-client.jar in that class path. This approach
may work, but is not guaranteed to work, because we did not run the full test suite
with any other log4j.jar version except the one we bundle with the release.
+
+ Soon we will providing an ant task that creates a slimmed down client jar without the extra
+ dependencies bundled.
</para>
<para>
Modified: trunk/docs/userguide-1.2/en/modules/UG12_introduction.xml
===================================================================
--- trunk/docs/userguide-1.2/en/modules/UG12_introduction.xml 2007-03-01 10:52:35 UTC (rev 2532)
+++ trunk/docs/userguide-1.2/en/modules/UG12_introduction.xml 2007-03-01 17:38:57 UTC (rev 2533)
@@ -15,7 +15,7 @@
intelligently balancing and utilizing each nodes CPU cycles, with no single point of failure,
providing a highly scalable and perform-ant clustering implementation. JBoss Messaging includes
a JMS front-end to deliver messaging in a standards-based format as well as being designed to be
- able to support other messaging protocols in the future.
+ able to support other messaging protocols in the future.
</para>
<para>
@@ -33,6 +33,13 @@
flexibility to any SOA initiative.
</para>
+ <section id="support">
+ <title>JBoss Messaging support cover from Red Hat</title>
+
+ <para>JBoss Messaging 1.2.GA support is available via the......</para>
+
+ </section>
+
<section id="features">
<title>JBoss Messaging 1.2.0.GA Features</title>
@@ -133,6 +140,26 @@
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>
+ </listitem>
+ <listitem>
+ <para>
+ Extensive JMX management interface
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ Support for most major databases including Oracle, Sybase, MS SQL Server, PostgreSQL and MySQL
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ HTTP transport
+ </para>
+ </listitem>
</itemizedlist>
<para>
@@ -163,34 +190,40 @@
</listitem>
<listitem>
<para>
- Pluggable routing implementation. The policy for routing messages to a queue is fully
- pluggable and easily replaceable. The default policy always chooses a queue at the local
- node if there is one, and if not, it round robins between queues on different nodes.
+ Pluggable routing implementation. The policy for routing messages to a queue is fully
+ pluggable and easily replaceable. The default policy always chooses a queue at the local
+ node if there is one, and if not, it round robins between queues on different nodes.
</para>
</listitem>
<listitem>
<para>
- Intelligent message redistribution policy. Messages are automatically distributed between
- nodes depending on how fast or slow consumers are on certain nodes. If there are no or slow
- consumers on a particular queue node, messages will be pulled from that queue to a queue with
- faster consumers on a different node. The policy is fully pluggable.
+ Intelligent message redistribution policy. Messages are automatically distributed between
+ nodes depending on how fast or slow consumers are on certain nodes. If there are no or slow
+ consumers on a particular queue node, messages will be pulled from that queue to a queue with
+ faster consumers on a different node. The policy is fully pluggable.
</para>
</listitem>
<listitem>
<para>
- Shared durable subscriptions. Consumers can connect to the same durable subscription while
- attached to different nodes. This allows processing load from durable subscriptions to be
- distributed across the cluster in a similar way to queues.
+ Shared durable subscriptions. Consumers can connect to the same durable subscription while
+ attached to different nodes. This allows processing load from durable subscriptions to be
+ distributed across the cluster in a similar way to queues.
</para>
</listitem>
<listitem>
<para>
- High availability and seamless fail-over. If the node you are connected to fails, you
- will automatically fail over to another node and will not lose any persistent messages.
- You can carry on with your session seamlessly where you left off. Once and only once
- delivery of persistent messages is respected at all times.
+ High availability and seamless fail-over. If the node you are connected to fails, you
+ will automatically fail over to another node and will not lose any persistent messages.
+ You can carry on with your session seamlessly where you left off. Once and only once
+ delivery of persistent messages is respected at all times.
</para>
</listitem>
+ <listitem>
+ <para>
+ Message bridge. JBoss Messaging 1.2 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. separated by a WAN)
+ </para>
+ </listitem>
</itemizedlist>
@@ -215,12 +248,12 @@
</important>
</section>
- <section id="missingfeatures">
- <title>
- Features not yet available in the 1.2.0.GA release, but coming soon
- </title>
-
- <para>
+ <section id="missingfeatures">
+ <title>
+ Features not yet available in the 1.2.0.GA release, but coming soon
+ </title>
+
+ <para>
All the final features are available apart from:
</para>
Modified: trunk/docs/userguide-1.2/en/modules/UG12_runningexamples.xml
===================================================================
--- trunk/docs/userguide-1.2/en/modules/UG12_runningexamples.xml 2007-03-01 10:52:35 UTC (rev 2532)
+++ trunk/docs/userguide-1.2/en/modules/UG12_runningexamples.xml 2007-03-01 17:38:57 UTC (rev 2533)
@@ -3,7 +3,7 @@
<title>Running the Examples</title>
<para>
- Since JBoss Messaging is a fully compliant JMS provider, it supports all JMS APIs. So, all
+ Since JBoss Messaging is a fully compliant JMS 1.1 provider, it supports the entire JMS 1.1 API. So, all
JMS applications should work without modification. Integrated inside a JBoss AS, we should
also be able access the JMS system from EJBs and write message-driven beans against JMS
destinations.
@@ -41,76 +41,72 @@
{
String destinationName = getDestinationJNDIName();
- InitialContext ic = null;
- ConnectionFactory cf = null;
- Connection connection = null;
- Connection connection2 = null;
+ InitialContext ic = null;
+ ConnectionFactory cf = null;
+ Connection connection = null;
- try {
+ try
+ {
+ ic = new InitialContext();
- ic = new InitialContext();
+ cf = (ConnectionFactory)ic.lookup("/ConnectionFactory");
+ Queue queue = (Queue)ic.lookup(destinationName);
+ log("Queue " + destinationName + " exists");
- cf = (ConnectionFactory)ic.lookup("/ConnectionFactory");
- Queue queue = (Queue)ic.lookup(destinationName);
- log("Queue " + destinationName + " exists");
+ connection = cf.createConnection();
+ Session session = connection.createSession(false, Session.AUTO_ACKNOWLEDGE);
+ MessageProducer sender = session.createProducer(queue);
- connection = cf.createConnection();
- Session session = connection.createSession(false, Session.AUTO_ACKNOWLEDGE);
- MessageProducer sender = session.createProducer(queue);
+ TextMessage message = session.createTextMessage("Hello!");
+ sender.send(message);
+ log("The message was successfully sent to the " + queue.getQueueName() + " queue");
- TextMessage message = session.createTextMessage("Hello!");
- sender.send(message);
- log("The message was successfully sent to the " + queue.getQueueName() + " queue");
+ MessageConsumer consumer = session.createConsumer(queue);
- connection2 = cf.createConnection();
- Session session2 = connection2.createSession(false, Session.AUTO_ACKNOWLEDGE);
- MessageConsumer consumer = session2.createConsumer(queue);
+ connection.start();
- connection2.start();
+ message = (TextMessage)consumer.receive(2000);
+ log("Received message: " + message.getText());
+ assertEquals("Hello!", message.getText());
- message = (TextMessage)consumer.receive(2000);
- log("Received message: " + message.getText());
- assertEquals("Hello!", message.getText());
+ displayProviderInfo(connection.getMetaData());
- displayProviderInfo(connection2.getMetaData());
+ }
+ finally
+ {
+ if(ic != null)
+ {
+ try
+ {
+ ic.close();
+ }
+ catch(Exception e)
+ {
+ throw e;
+ }
+ }
- }catch(NamingException ne){
- ne.printStackTrace();
-
- }catch(JMSException jmse){
- jmse.printStackTrace();
-
- }catch(Exception e){
- e.printStackTrace();
-
- }finally{
-
- if(ic != null) {
- try {
- ic.close();
- }catch(Exception ignore){ }
- }
-
- closeConnection(connection);
-
- closeConnection(connection2);
- }
-
+ // ALWAYS close your connection in a finally block to avoid leaks.
+ // Closing connection also takes care of closing its related objects e.g. sessions.
+ closeConnection(connection);
+ }
}
- private void closeConnection(Connection con){
-
- try {
- if (con != null) {
- con.close();
- }
-
- }catch(JMSException jmse) {
- log("Could not close connection " + con +" exception was " +jmse);
- }
+ private void closeConnection(Connection con)
+ {
+ try
+ {
+ if (con != null)
+ {
+ con.close();
+ }
+ }
+ catch(JMSException jmse)
+ {
+ log("Could not close connection " + con +" exception was " + jmse);
+ }
}
-
protected boolean isQueueExample()
{
return true;
@@ -144,68 +140,75 @@
{
String destinationName = getDestinationJNDIName();
- InitialContext ic = null;
- Connection connection = null;
+ InitialContext ic = null;
+ Connection connection = null;
- try {
+ try
+ {
+ ic = new InitialContext();
- ic = new InitialContext();
+ ConnectionFactory cf = (ConnectionFactory)ic.lookup("/ConnectionFactory");
+ Topic topic = (Topic)ic.lookup(destinationName);
+ log("Topic " + destinationName + " exists");
- ConnectionFactory cf = (ConnectionFactory)ic.lookup("/ConnectionFactory");
- Topic topic = (Topic)ic.lookup(destinationName);
- log("Topic " + destinationName + " exists");
+ connection = cf.createConnection();
+ Session session = connection.createSession(false, Session.AUTO_ACKNOWLEDGE);
+ MessageProducer publisher = session.createProducer(topic);
+ MessageConsumer subscriber = session.createConsumer(topic);
- connection = cf.createConnection();
- Session session = connection.createSession(false, Session.AUTO_ACKNOWLEDGE);
- MessageProducer publisher = session.createProducer(topic);
- MessageConsumer subscriber = session.createConsumer(topic);
+ ExampleListener messageListener = new ExampleListener();
+ subscriber.setMessageListener(messageListener);
+ connection.start();
- ExampleListener messageListener = new ExampleListener();
- subscriber.setMessageListener(messageListener);
- connection.start();
+ TextMessage message = session.createTextMessage("Hello!");
+ publisher.send(message);
+ log("The message was successfully published on the topic");
- TextMessage message = session.createTextMessage("Hello!");
- publisher.send(message);
- log("The message was successfully published on the topic");
+ messageListener.waitForMessage();
- messageListener.waitForMessage();
+ message = (TextMessage)messageListener.getMessage();
+ log("Received message: " + message.getText());
+ assertEquals("Hello!", message.getText());
- message = (TextMessage)messageListener.getMessage();
- log("Received message: " + message.getText());
- assertEquals("Hello!", message.getText());
+ displayProviderInfo(connection.getMetaData());
- displayProviderInfo(connection.getMetaData());
+ }
+ finally
+ {
+ if (ic != null)
+ {
+ try
+ {
+ ic.close();
+ }
+ catch(Exception e)
+ {
+ throw e;
+ }
+ }
- }finally{
-
- if(ic != null) {
- try {
- ic.close();
- }catch(Exception e){
- throw e;
- }
- }
-
- //ALWAYS close your connection in a finally block to avoid leaks
- //Closing connection also takes care of closing its related objects e.g. sessions
- closeConnection(connection);
- }
+ // ALWAYS close your connection in a finally block to avoid leaks.
+ // Closing connection also takes care of closing its related objects e.g. sessions.
+ closeConnection(connection);
+ }
}
- private void closeConnection(Connection con) throws JMSException {
+ private void closeConnection(Connection con) throws JMSException
+ {
- try {
- if (con != null) {
- con.close();
- }
-
- }catch(JMSException jmse) {
- log("Could not close connection " + con +" exception was " +jmse);
- throw jmse;
- }
+ try
+ {
+ if (con != null)
+ {
+ con.close();
+ }
+ }
+ catch(JMSException jmse)
+ {
+ log("Could not close connection " + con +" exception was " + jmse);
+ }
}
-
protected boolean isQueueExample()
{
return false;
@@ -226,14 +229,19 @@
<para>This example deploys a simple Stateless Session Bean that is used as a proxy to send and receive JMS messages in a managed environment.
</para>
+ <warning>
+ Receiving a JMS message from inside an EJB (or MBean or servlet) method is considered an anti-pattern since it will require the creation
+ of a new JMS consumer on every send - even when using the JCA adaptor. This is likely to make it very slow. (Users of the Spring JMSTemplate be warned that this is what it uses
+ to implement it's receive.)
+ If you want to receive messages as part of a global transaction then use an MDB instead.
+ </warning>
+
<programlisting>
public class StatelessSessionExampleBean implements SessionBean
{
- private SessionContext ctx;
+ private ConnectionFactory cf = null;
- private ConnectionFactory cf = null;
-
public void drain(String queueName) throws Exception
{
InitialContext ic = new InitialContext();
@@ -257,22 +265,28 @@
}
finally
{
- closeConnection(conn);
+ if (conn != null)
+ {
+ closeConnection(conn);
+ }
}
}
public void send(String txt, String queueName) throws Exception
{
InitialContext ic = new InitialContext();
+
Queue queue = (Queue)ic.lookup(queueName);
+
ic.close();
Session session = null;
Connection conn = null;
- try
+ try
{
conn = getConnection();
+
session = conn.createSession(false, Session.AUTO_ACKNOWLEDGE);
MessageProducer producer = session.createProducer(queue);
@@ -280,16 +294,19 @@
TextMessage tm = session.createTextMessage(txt);
producer.send(tm);
+
System.out.println("message " + txt + " sent to " + queueName);
-
}
finally
{
- closeConnection(conn);
+ if (conn != null)
+ {
+ closeConnection(conn);
+ }
}
}
- public List browse(String queueName) throws Exception
+ public int browse(String queueName) throws Exception
{
InitialContext ic = new InitialContext();
Queue queue = (Queue)ic.lookup(queueName);
@@ -310,11 +327,14 @@
list.add(e.nextElement());
}
- return list;
+ return list.size();
}
finally
{
- closeConnection(conn);
+ if (conn != null)
+ {
+ closeConnection(conn);
+ }
}
}
@@ -327,6 +347,8 @@
Session session = null;
Connection conn = null;
+ // WARN! this is an anti-pattern - please see above warning
+
try
{
conn = getConnection();
@@ -345,47 +367,98 @@
System.out.println("Message " + tm.getText() + " received");
return tm.getText();
-
}
finally
{
- closeConnection(conn);
+ if (conn != null)
+ {
+ closeConnection(conn);
+ }
}
}
- public Connection getConnection() throws Exception {
+ public Connection getConnection() throws Exception
+ {
- Connection connection = null;
+ Connection connection = null;
- try {
- connection = cf.createConnection();
- connection.start();
+ try
+ {
+ connection = cf.createConnection();
- }catch(Exception e ){
- if(connection != null)
- closeConnection(connection);
- System.out.println("Failed to get connection...exception is " +e);
- throw e;
- }
+ connection.start();
+ }
+ catch(Exception e )
+ {
+ if(connection != null)
+ {
+ closeConnection(connection);
+ }
+ System.out.println("Failed to get connection...exception is " + e);
+ throw e;
+ }
- return connection;
- }
+ return connection;
+ }
- public void closeConnection(Connection con) throws Exception {
+ public void closeConnection(Connection con) throws Exception
+ {
+ try
+ {
+ con.close();
+ }
+ catch(JMSException jmse)
+ {
+ System.out.println("Could not close connection " + con +" exception was " + jmse);
+ throw jmse;
+ }
+ }
- try {
- if (con != null) {
- con.close();
- }
+ public void setSessionContext(SessionContext ctx) throws EJBException, RemoteException
+ {
+ }
- }catch(JMSException jmse) {
- System.out.println("Could not close connection " + con +" exception was " +jmse);
- throw jmse;
+ public void ejbCreate()
+ {
+ try
+ {
+ InitialContext ic = new InitialContext();
- }
- }
+ cf = (ConnectionFactory)ic.lookup("java:/JmsXA");
- .......
+ ic.close();
+ }
+ catch(Exception e)
+ {
+ e.printStackTrace();
+ throw new EJBException("Initalization failure: " + e.getMessage());
+ }
+ }
+
+ public void ejbRemove() throws EJBException
+ {
+ try
+ {
+ if(cf != null)
+ {
+ cf = null;
+ }
+ }
+ catch(Exception e)
+ {
+ throw new EJBException("ejbRemove ", e);
+ }
+ }
+
+ public void ejbActivate() throws EJBException, RemoteException
+ {
+ }
+
+ public void ejbPassivate() throws EJBException, RemoteException
+ {
+ }
+
+}
</programlisting>
</section>
@@ -423,7 +496,6 @@
<programlisting>
public class MDBExample implements MessageDrivenBean, MessageListener
{
-
private MessageDrivenContext ctx;
private ConnectionFactory cf = null;
@@ -463,60 +535,105 @@
{
if (conn != null)
{
- try {
- closeConnection(conn);
- }catch(Exception e){
- System.out.println("Could not close the connection!" +e);
+ try
+ {
+ closeConnection(conn);
}
+ catch(Exception e)
+ {
+ System.out.println("Could not close the connection!" +e);
+ }
}
}
}
- private String process(String text)
+ private String process(String s)
{
// flip the string
- String result = ";
+ String result = "";
- for(int i = 0; i < text.length(); i++)
+ for (int i = 0; i < text.length(); i++)
{
result = text.charAt(i) + result;
}
return result;
}
- public Connection getConnection() throws Exception {
+ public Connection getConnection() throws Exception
+ {
+ Connection connection = null;
- Connection connection = null;
+ try
+ {
+ connection = cf.createConnection();
+ connection.start();
+ }
+ catch(Exception e )
+ {
+ if(connection != null)
+ {
+ closeConnection(connection);
+ }
+ System.out.println("Failed to get connection...exception is " + e);
+ throw e;
+ }
- try {
- connection = cf.createConnection();
- connection.start();
+ return connection;
+ }
- }catch(Exception e ){
- if(connection != null)
- closeConnection(connection);
- System.out.println("Failed to get connection...exception is " +e);
- throw e;
- }
+ public void closeConnection(Connection con) throws Exception
+ {
+ try
+ {
+ con.close();
+ }
+ catch(JMSException e)
+ {
+ System.out.println("Could not close connection " + con + " exception was " + e);
+ }
+ }
- return connection;
- }
+ public void ejbCreate()
+ {
+ try
+ {
+ InitialContext ic = new InitialContext();
- public void closeConnection(Connection con) throws Exception {
+ cf = (ConnectionFactory)ic.lookup("java:/JmsXA");
- try {
- if (con = null) {
- con.close();
- }
+ ic.close();
+ }
+ catch(Exception e)
+ {
+ e.printStackTrace();
+ throw new EJBException("Failure to get connection factory: " + e.getMessage());
+ }
+ }
- }catch(JMSException jmse) {
- System.out.println("Could not close connection " + con +" exception was " +jmse);
- throw jmse;
- }
- }
+ public void ejbRemove() throws EJBException
+ {
+ try
+ {
+ if(cf != null)
+ {
+ cf = null;
+ }
+ }
+ catch(Exception e)
+ {
+ throw new EJBException("ejbRemove", e);
+ }
+ }
- ......
+ public void setMessageDrivenContext(MessageDrivenContext ctx)
+ {
+ this.ctx = ctx;
+ }
+
+
+}
+
</programlisting>
@@ -577,12 +694,11 @@
The EJB3 Message Driven Bean source code:
</para>
<programlisting>
- at MessageDriven(activateConfig =
+ at MessageDriven(activationConfig =
{
- @ActivationConfigProperty(propertyName="destinationType",
- propertyValue="javax.jms.Queue"),
- @ActivationConfigProperty(propertyName="destination",
- propertyValue="queue/testQueue")
+ @ActivationConfigProperty(propertyName="destinationType", propertyValue="javax.jms.Queue"),
+ @ActivationConfigProperty(propertyName="destination", propertyValue="queue/testQueue"),
+ @ActivationConfigProperty(propertyName="DLQMaxResent", propertyValue="10")
})
public class EJB3MDBExample implements MessageListener
{
@@ -591,7 +707,6 @@
businessLogic(m);
}
-
private void businessLogic(Message m)
{
Connection conn = null;
More information about the jboss-cvs-commits
mailing list