[jboss-cvs] JBossAS SVN: r94324 - in projects/docs/enterprise/5.0/JBoss_Messaging_2.0.0/JBoss_Messaging_User_Guide: en-US and 1 other directories.
jboss-cvs-commits at lists.jboss.org
jboss-cvs-commits at lists.jboss.org
Sun Oct 4 21:37:17 EDT 2009
Author: laubai
Date: 2009-10-04 21:37:17 -0400 (Sun, 04 Oct 2009)
New Revision: 94324
Added:
projects/docs/enterprise/5.0/JBoss_Messaging_2.0.0/JBoss_Messaging_User_Guide/Makefile
projects/docs/enterprise/5.0/JBoss_Messaging_2.0.0/JBoss_Messaging_User_Guide/en-US/
projects/docs/enterprise/5.0/JBoss_Messaging_2.0.0/JBoss_Messaging_User_Guide/en-US/Author_Group.xml
projects/docs/enterprise/5.0/JBoss_Messaging_2.0.0/JBoss_Messaging_User_Guide/en-US/Book_Info.xml
projects/docs/enterprise/5.0/JBoss_Messaging_2.0.0/JBoss_Messaging_User_Guide/en-US/Clusters.xml
projects/docs/enterprise/5.0/JBoss_Messaging_2.0.0/JBoss_Messaging_User_Guide/en-US/Command_Buffering.xml
projects/docs/enterprise/5.0/JBoss_Messaging_2.0.0/JBoss_Messaging_User_Guide/en-US/Configuration_Reference.xml
projects/docs/enterprise/5.0/JBoss_Messaging_2.0.0/JBoss_Messaging_User_Guide/en-US/Configuring_the_Transports.xml
projects/docs/enterprise/5.0/JBoss_Messaging_2.0.0/JBoss_Messaging_User_Guide/en-US/Connection_TTL.xml
projects/docs/enterprise/5.0/JBoss_Messaging_2.0.0/JBoss_Messaging_User_Guide/en-US/Duplicate_Detection.xml
projects/docs/enterprise/5.0/JBoss_Messaging_2.0.0/JBoss_Messaging_User_Guide/en-US/Embedding_JBM.xml
projects/docs/enterprise/5.0/JBoss_Messaging_2.0.0/JBoss_Messaging_User_Guide/en-US/Examples.xml
projects/docs/enterprise/5.0/JBoss_Messaging_2.0.0/JBoss_Messaging_User_Guide/en-US/Filter_Expressions.xml
projects/docs/enterprise/5.0/JBoss_Messaging_2.0.0/JBoss_Messaging_User_Guide/en-US/HA_and_Failover.xml
projects/docs/enterprise/5.0/JBoss_Messaging_2.0.0/JBoss_Messaging_User_Guide/en-US/JBoss_Messaging_User_Guide.xml
projects/docs/enterprise/5.0/JBoss_Messaging_2.0.0/JBoss_Messaging_User_Guide/en-US/JMS_Wildcard_Syntax.xml
projects/docs/enterprise/5.0/JBoss_Messaging_2.0.0/JBoss_Messaging_User_Guide/en-US/Message_Flow_Diverts.xml
projects/docs/enterprise/5.0/JBoss_Messaging_2.0.0/JBoss_Messaging_User_Guide/en-US/Messaging_Concepts.xml
projects/docs/enterprise/5.0/JBoss_Messaging_2.0.0/JBoss_Messaging_User_Guide/en-US/Paging.xml
projects/docs/enterprise/5.0/JBoss_Messaging_2.0.0/JBoss_Messaging_User_Guide/en-US/Performance_Tuning.xml
projects/docs/enterprise/5.0/JBoss_Messaging_2.0.0/JBoss_Messaging_User_Guide/en-US/Persistence.xml
projects/docs/enterprise/5.0/JBoss_Messaging_2.0.0/JBoss_Messaging_User_Guide/en-US/Pre-acknowledge_Mode.xml
projects/docs/enterprise/5.0/JBoss_Messaging_2.0.0/JBoss_Messaging_User_Guide/en-US/Queue_Attributes.xml
projects/docs/enterprise/5.0/JBoss_Messaging_2.0.0/JBoss_Messaging_User_Guide/en-US/Security.xml
projects/docs/enterprise/5.0/JBoss_Messaging_2.0.0/JBoss_Messaging_User_Guide/en-US/Send_Guarantees.xml
projects/docs/enterprise/5.0/JBoss_Messaging_2.0.0/JBoss_Messaging_User_Guide/en-US/Thread_Management.xml
projects/docs/enterprise/5.0/JBoss_Messaging_2.0.0/JBoss_Messaging_User_Guide/en-US/Using_Core.xml
projects/docs/enterprise/5.0/JBoss_Messaging_2.0.0/JBoss_Messaging_User_Guide/en-US/Using_the_Server.xml
projects/docs/enterprise/5.0/JBoss_Messaging_2.0.0/JBoss_Messaging_User_Guide/en-US/images/
projects/docs/enterprise/5.0/JBoss_Messaging_2.0.0/JBoss_Messaging_User_Guide/en-US/images/architecture1.jpg
projects/docs/enterprise/5.0/JBoss_Messaging_2.0.0/JBoss_Messaging_User_Guide/en-US/images/architecture2.jpg
projects/docs/enterprise/5.0/JBoss_Messaging_2.0.0/JBoss_Messaging_User_Guide/en-US/images/architecture3.jpg
projects/docs/enterprise/5.0/JBoss_Messaging_2.0.0/JBoss_Messaging_User_Guide/en-US/interoperability.xml
Log:
Adding JBoss Messaging 2.0.0 docs for editing. NOT YET READY TO SHIP.
Added: projects/docs/enterprise/5.0/JBoss_Messaging_2.0.0/JBoss_Messaging_User_Guide/Makefile
===================================================================
--- projects/docs/enterprise/5.0/JBoss_Messaging_2.0.0/JBoss_Messaging_User_Guide/Makefile (rev 0)
+++ projects/docs/enterprise/5.0/JBoss_Messaging_2.0.0/JBoss_Messaging_User_Guide/Makefile 2009-10-05 01:37:17 UTC (rev 94324)
@@ -0,0 +1,13 @@
+#Makefile for JBoss_Messaging_User_Guide
+
+XML_LANG = en-US
+BRAND = JBoss
+
+#OTHER_LANGS = as-IN bn-IN de-DE es-ES fr-FR gu-IN hi-IN it-IT ja-JP kn-IN ko-KR ml-IN mr-IN or-IN pa-IN pt-BR ru-RU si-LK ta-IN te-IN zh-CN zh-TW
+
+# Extra Parameters start here
+
+# Extra Parameters stop here
+COMMON_CONFIG = /usr/share/publican
+include $(COMMON_CONFIG)/make/Makefile.common
+
Added: projects/docs/enterprise/5.0/JBoss_Messaging_2.0.0/JBoss_Messaging_User_Guide/en-US/Author_Group.xml
===================================================================
--- projects/docs/enterprise/5.0/JBoss_Messaging_2.0.0/JBoss_Messaging_User_Guide/en-US/Author_Group.xml (rev 0)
+++ projects/docs/enterprise/5.0/JBoss_Messaging_2.0.0/JBoss_Messaging_User_Guide/en-US/Author_Group.xml 2009-10-05 01:37:17 UTC (rev 94324)
@@ -0,0 +1,11 @@
+<?xml version='1.0'?>
+<!DOCTYPE authorgroup PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [
+]>
+
+<authorgroup>
+<author>
+ <firstname>Red Hat Documentation Group</firstname>
+ <surname></surname>
+ </author>
+</authorgroup>
+
Added: projects/docs/enterprise/5.0/JBoss_Messaging_2.0.0/JBoss_Messaging_User_Guide/en-US/Book_Info.xml
===================================================================
--- projects/docs/enterprise/5.0/JBoss_Messaging_2.0.0/JBoss_Messaging_User_Guide/en-US/Book_Info.xml (rev 0)
+++ projects/docs/enterprise/5.0/JBoss_Messaging_2.0.0/JBoss_Messaging_User_Guide/en-US/Book_Info.xml 2009-10-05 01:37:17 UTC (rev 94324)
@@ -0,0 +1,35 @@
+<?xml version='1.0'?>
+<!DOCTYPE bookinfo PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [
+]>
+
+<bookinfo>
+ <title>JBoss Messaging 2.0.0 User Guide</title>
+ <subtitle>for Use with JBoss Enterprise Application Platform 5.0</subtitle>
+ <edition>1</edition>
+ <pubsnumber>0</pubsnumber>
+ <productname>JBoss Enterprise Application Platform</productname>
+ <productnumber>5.0</productnumber>
+ <pubdate>September, 2009</pubdate>
+ <abstract>
+ <para>
+ The JBoss Enterprise Application Platform Edition of the JBoss Messaging version 2.0.0 User Guide.
+ </para>
+ </abstract>
+ <corpauthor>
+ <inlinemediaobject>
+ <imageobject>
+ <imagedata format='SVG' fileref="Common_Content/images/title_logo.svg" />
+ </imageobject>
+ <textobject><phrase>Logo</phrase></textobject>
+ </inlinemediaobject>
+ </corpauthor>
+ <copyright>
+ <year>&YEAR;</year>
+ <holder>&HOLDER;</holder>
+ </copyright>
+ <xi:include href="Common_Content/Legal_Notice.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
+ <xi:include href="Author_Group.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
+</bookinfo>
+
+
+
Added: projects/docs/enterprise/5.0/JBoss_Messaging_2.0.0/JBoss_Messaging_User_Guide/en-US/Clusters.xml
===================================================================
--- projects/docs/enterprise/5.0/JBoss_Messaging_2.0.0/JBoss_Messaging_User_Guide/en-US/Clusters.xml (rev 0)
+++ projects/docs/enterprise/5.0/JBoss_Messaging_2.0.0/JBoss_Messaging_User_Guide/en-US/Clusters.xml 2009-10-05 01:37:17 UTC (rev 94324)
@@ -0,0 +1,690 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<chapter id="clusters">
+ <title>Clusters</title>
+ <section>
+ <title>Clusters Overview</title>
+ <para>JBoss Messaging clusters allow groups of JBoss Messaging servers to be grouped
+ together in order to share message processing load. Each active node in the cluster is
+ an active JBoss Messaging server which manages its own messages and handles its own
+ connections. A server must be configured to be clustered, you will need to set the
+ <literal>clustered</literal> element in the <literal>jbm-configuration.xml</literal>
+ configuration file to <literal>true</literal>, this is <literal>false</literal> by
+ default.</para>
+ <para>The cluster is formed by each node declaring <emphasis>cluster connections</emphasis>
+ to other nodes in the core configuration file <literal>jbm-configuration.xml</literal>.
+ When a node forms a cluster connection to another node, internally it creates a <emphasis>core
+ bridge</emphasis> (as described in <xref
+ linkend="core-bridges" />) connection between it and the other node,
+ this is done transparently behind the scenes - you don't have to declare an explicit
+ bridge for each node. These cluster connections allow messages to flow between the nodes
+ of the cluster to balance load.</para>
+ <para>Nodes can be connected together to form a cluster in many different topologies, we
+ will discuss a couple of the more common topologies later in this chapter.</para>
+ <para>We'll also discuss client side load balancing, where we can balance client connections
+ across the nodes of the cluster, and we'll consider message redistribution where JBoss
+ Messaging will redistribute messages between nodes to avoid starvation.</para>
+ <para>Another important part of clustering is <emphasis>server discovery</emphasis> where
+ servers can broadcast their connection details so clients or other servers can connect
+ to them with the minimum of configuration.</para>
+ </section>
+ <section id="clusters.server-discovery">
+ <title>Server discovery</title>
+ <para>Server discovery is a mechanism by which servers can broadcast their connection
+ settings across the network. This is useful for two purposes:</para>
+ <itemizedlist>
+ <listitem>
+ <para>Discovery by messaging clients. A messaging client wants to be able to connect
+ to the servers of the cluster without having specific knowledge of which servers
+ in the cluster are up at any one time. Messaging clients
+ <emphasis>can</emphasis> be initialised with an explicit list of the servers
+ in a cluster, but this is not flexible or maintainable as servers are added or
+ removed from the cluster.</para>
+ </listitem>
+ <listitem>
+ <para>Discovery by other servers. Servers in a cluster want to be able to create
+ cluster connections to each other without having prior knowledge of all the
+ other servers in the cluster. </para>
+ </listitem>
+ </itemizedlist>
+ <para>Server discovery uses <ulink url="http://en.wikipedia.org/wiki/User_Datagram_Protocol"
+ >UDP</ulink> multicast to broadcast server connection settings. If UDP is disabled
+ on your network you won't be able to use this, and will have to specify servers
+ explicitly when setting up a cluster or using a messaging client.</para>
+ <section id="clusters.broadcast-groups">
+ <title>Broadcast Groups</title>
+ <para>A broadcast group is the means by which a server broadcasts connectors over the
+ network. A connector defines a way in which a client (or other server) can make
+ connections to the server. For more information on what a connector is, please see
+ <xref linkend="configuring-transports" />.</para>
+ <para>The broadcast group takes a set of connector pairs, each connector pair contains
+ connection settings for a live and (optional) backup server and broadcasts them on
+ the network. It also defines the UDP address and port settings. </para>
+ <para>Broadcast groups are defined in the server configuration file <literal
+ >jbm-configuration.xml</literal>. There can be many broadcast groups per JBoss
+ Messaging server. All broadcast groups must be defined in a <literal
+ >broadcast-groups</literal> element.</para>
+ <para>Let's take a look at an example broadcast group from <literal
+ >jbm-configuration.xml</literal>:</para>
+ <programlisting><broadcast-groups>
+ <broadcast-group name="my-broadcast-group">
+ <local-bind-port>54321</local-bind-port>
+ <group-address>231.7.7.7</group-address>
+ <group-port>9876</group-port>
+ <broadcast-period>1000</broadcast-period>
+ <connector-ref connector-name="netty-connector"
+ backup-connector-name="backup-connector"/>
+ </broadcast-group>
+</broadcast-groups></programlisting>
+ <para>Some of the broadcast group parameters are optional and you'll normally use the
+ defaults, but we specify them all in the above example for clarity. Let's discuss
+ each one in turn:</para>
+ <itemizedlist>
+ <listitem>
+ <para><literal>name</literal> attribute. Each broadcast group in the server must
+ have a unique name. </para>
+ </listitem>
+ <listitem>
+ <para><literal>local-bind-address</literal>. This is the local bind
+ address that the datagram socket is bound to. If you have multiple network
+ interfaces on your server, you would specify which one you wish to use for
+ broadcasts by setting this property. If this property is not specified then
+ the socket will be bound to the wildcard address, an IP address chosen by
+ the kernel.</para>
+ </listitem>
+ <listitem>
+ <para><literal>local-bind-port</literal>. If you want to specify a local port to
+ which the datagram socket is bound you can specify it here. Normally you
+ would just use the default value of <literal>-1</literal> which signifies
+ that an anonymous port should be used.</para>
+ </listitem>
+ <listitem>
+ <para><literal>group-address</literal>. This is the multicast address to which
+ the data will be broadcast. It is a class D IP address in the range <literal
+ >224.0.0.0</literal> to <literal>239.255.255.255</literal>, inclusive.
+ The address <literal>224.0.0.0</literal> is reserved and is not available
+ for use. This parameter is mandatory.</para>
+ </listitem>
+ <listitem>
+ <para><literal>group-port</literal>. This is the UDP port number used for
+ broadcasting. This parameter is mandatory.</para>
+ </listitem>
+ <listitem>
+ <para><literal>broadcast-period</literal>. This is the period in milliseconds
+ between consecutive broadcasts. This parameter is optional, the default
+ value is <literal>1000</literal> milliseconds.</para>
+ </listitem>
+ <listitem>
+ <para><literal>connector-ref</literal>. This specifies the connector and
+ optional backup connector that will be broadcasted (see <xref
+ linkend="configuring-transports" /> for more information on
+ connectors). The connector to be broadcasted is specified by the <literal
+ >connector-name</literal> attribute, and the backup connector to be
+ broadcasted is specified by the <literal>backup-connector</literal> attribute.
+ The <literal>backup-connector</literal> attribute is optional.</para>
+ </listitem>
+ </itemizedlist>
+ </section>
+ <section id="clusters.discovery-groups">
+ <title>Discovery Groups</title>
+ <para>While the broadcast group defines who connector information is broadcast from a
+ server, a discovery group defines how connector information is received from a
+ multicast address.</para>
+ <para>A discovery group maintains a list of connector pairs - one for each broadcast by
+ a different server. As it receives broadcasts on the multicast group address from a
+ particular server it updates its entry in the list for that server.</para>
+ <para>If it has not received a broadcast from a particular server for a length of time
+ it will remove that server's entry from its list.</para>
+ <para>Discovery groups are used in two places in JBoss Messaging:</para>
+ <itemizedlist>
+ <listitem>
+ <para>By cluster connections so they know what other servers in the cluster they
+ should make connections to.</para>
+ </listitem>
+ <listitem>
+ <para>By messaging clients so they can discovery what servers in the cluster
+ that they can connect to.</para>
+ </listitem>
+ </itemizedlist>
+ </section>
+ <section>
+ <title>Defining Discovery Groups on the Server</title>
+ <para>For cluster connections, discovery groups are defined in the server side
+ configuration file <literal>jbm-configuration.xml</literal>. All discovery groups
+ must be defined inside a <literal>discovery-groups</literal> element. There can be
+ many discovery groups defined by JBoss Messaging server. Let's look at an
+ example:</para>
+ <programlisting><discovery-groups>
+ <discovery-group name="my-discovery-group">
+ <group-address>231.7.7.7</group-address>
+ <group-port>9876</group-port>
+ <refresh-timeout>10000</refresh-timeout>
+ </discovery-group>
+</discovery-groups></programlisting>
+ <para>We'll consider each parameter of the discovery group:</para>
+ <itemizedlist>
+ <listitem>
+ <para><literal>name</literal> attribute. Each discovery group must have a unique
+ name per server.</para>
+ </listitem>
+ <listitem>
+ <para><literal>group-address</literal>. This is the multicast ip address of the
+ group to listen on. It should match the <literal>group-address</literal> in
+ the broadcast group that you wish to listen from. This parameter is
+ mandatory.</para>
+ </listitem>
+ <listitem>
+ <para><literal>group-port</literal>. This is the UDP port of the multicast
+ group. It should match the <literal>group-port</literal> in the broadcast
+ group that you wish to listen from. This parameter is mandatory.</para>
+ </listitem>
+ <listitem>
+ <para><literal>refresh-timeout</literal>. This is the period the discovery group
+ waits after receiving the last broadcast from a particular server before
+ removing that servers connector pair entry from its list. You would normally
+ set this to a value significantly higher than the <literal
+ >broadcast-period</literal> on the broadcast group otherwise servers
+ might intermittently disappear from the list even though they are still
+ broadcasting due to slight differences in timing. This parameter is
+ optional, the default value is <literal>10000</literal> milliseconds (10
+ seconds).</para>
+ </listitem>
+ </itemizedlist>
+ </section>
+ <section id="clusters-discovery.groups.clientside">
+ <title>Discovery Groups on the Client Side</title>
+ <para>Let's discuss how to configure a JBoss Messaging client to use discovery to
+ discover a list of servers to which it can connect. The way to do this differs
+ depending on whether you're using JMS or the core API.</para>
+ <section>
+ <title>Configuring client discovery using JMS</title>
+ <para>If you're using JMS and you're also using the JMS Service on the server to
+ load your JMS connection factory instances into JNDI, then you can specify which
+ discovery group to use for your JMS connection factory in the server side xml
+ configuration <literal>jbm-jms.xml</literal>. Let's take a look at an
+ example:</para>
+ <programlisting><connection-factory name="ConnectionFactory">
+ <discovery-group-ref discovery-group-name="my-discovery-group"/>
+ <entries>
+ <entry name="ConnectionFactory"/>
+ </entries>
+</connection-factory></programlisting>
+ <para>The element <literal>discovery-group-ref</literal> specifies the name of a
+ discovery group defined in <literal>jbm-configuration.xml</literal>.</para>
+ <para>When this connection factory is downloaded from JNDI by a client application
+ and JMS connections are created from it, those connections will be load-balanced
+ across the list of servers that the discovery group maintains by listening on
+ the multicast address specified in the discovery group configuration.</para>
+ <para>If you're using JMS, but you're not using JNDI to lookup a connection factory
+ - you're instantiating the JMS connection factory directly then you can specify
+ the discovery group parameters directly when creating the JMS connection
+ factory. Here's an
+ example:<programlisting>final String groupAddress = "231.7.7.7";
+
+final int groupPort = 9876;
+
+ConnectionFactory jmsConnectionFactory =
+ new JBossConnectionFactory(groupAddress, groupPort);
+
+Connection jmsConnection1 = jmsConnectionFactory.createConnection();
+
+Connection jmsConnection2 = jmsConnectionFactory.createConnection();</programlisting></para>
+ <para>The <literal>refresh-timeout</literal> can be set directly on the connection
+ factory by using the setter method <literal>setDiscoveryRefreshTimeout() if you
+ want to change the default value.</literal></para>
+ <para>There is also a further parameter settable on the connection factory using the
+ setter method <literal>setInitialWaitTimeout()</literal>. If the connection
+ factory is used immediately after creation then it may not have had enough time
+ to received broadcasts from all the nodes in the cluster. On first usage, the
+ connection factory will make sure it waits this long since creation before
+ creating the first connection. The default value for this parameter is <literal
+ >2000</literal> milliseconds.</para>
+ </section>
+ <section>
+ <title>Configuring client discovery using Core</title>
+ <para>If you're using the core API to directly instantiate <literal
+ >ClientSessionFactory</literal> instances, then you can specify the
+ discovery group parameters directly when creating the session factory. Here's an
+ example:final String groupAddress = "231.7.7.7"; final int groupPort = 9876;
+ SessionFactory factory = new ClientSessionFactoryImpl(groupAddress, groupPort);
+ ClientSession session1 = factory.createClientSession(...); ClientSession
+ session2 = factory.createClientSession(...); </para>
+ <para>The <literal>refresh-timeout</literal> can be set directly on the session
+ factory by using the setter method <literal>setDiscoveryRefreshTimeout() if you
+ want to change the default value.</literal></para>
+ <para>There is also a further parameter settable on the session factory using the
+ setter method <literal>setInitialWaitTimeout()</literal>. If the session factory
+ is used immediately after creation then it may not have had enough time to
+ received broadcasts from all the nodes in the cluster. On first usage, the
+ session factory will make sure it waits this long since creation before creating
+ the first session. The default value for this parameter is <literal
+ >2000</literal> milliseconds.</para>
+ </section>
+ </section>
+ </section>
+ <section>
+ <title>Server-Side Message Load Balancing</title>
+ <para>If cluster connections are defined between nodes of a cluster, then JBoss Messaging
+ will load balance messages arriving from at a particular node from a client.</para>
+ <para>Let's take a simple example of a cluster of four nodes A, B, C, and D arranged in a
+ <emphasis>symmetric cluster</emphasis> (described in <xref linkend="symmetric-cluster" />).
+ We have a queue called
+ <literal>OrderQueue</literal> deployed on each node of the cluster.</para>
+ <para>We have client Ca connected to node A, sending orders to the server. We have also have
+ order processor clients Pa, Pb, Pc, and Pd connected to each of the nodes A, B, C, D. If
+ no cluster connection was defined on node A, then as order messages arrive on node A
+ they will all end up in the <literal>OrderQueue</literal> on node A, so will only get
+ consumed by the order processor client attached to node A, Pa.</para>
+ <para>If we define a cluster connection on node A, then as ordered messages arrive on node A
+ instead of all of them going into the local <literal>OrderQueue</literal> instance, they
+ are distributed in a round-robin fashion between all the nodes of the cluster. The
+ messages are forwarded from the receiving node to other nodes of the cluster. This is
+ all done on the server side, the client maintains a single connection to node A.</para>
+ <para>For example, messages arriving on node A might be distributed in the following order
+ between the nodes: B, D, C, A, B, D, C, A, B, D. The exact order depends on the order
+ the nodes started up, but the algorithm used is round robin.</para>
+ <para>JBoss Messaging cluster connections can be configured to always blindly load balance
+ messages in a round robin fashion irrespective of whether there are any matching
+ consumers on other nodes, but they can be a bit cleverer than that and also be
+ configured to only distribute to other nodes if they have matching consumers. We'll look
+ at both these cases in turn with some examples, but first we'll discuss configuring
+ cluster connections in general.</para>
+ <section id="clusters.cluster-connections">
+ <title>Configuring Cluster Connections</title>
+ <para>Cluster connections group servers into clusters so that messages can be load
+ balanced between the nodes of the cluster. Let's take a look at a typical cluster
+ connection. Cluster connections are always defined in <literal
+ >jbm-configuration.xml</literal> inside a <literal>cluster-connection</literal>
+ element. There can be zero or more cluster connections defined per JBoss Messaging
+ server.</para>
+ <programlisting>
+<cluster-connections>
+ <cluster-connection name="my-cluster">
+ <address>jms</address>
+ <retry-interval>500</retry-interval>
+ <use-duplicate-detection>true</use-duplicate-detection>
+ <forward-when-no-consumers>false</forward-when-no-consumers>
+ <max-hops>1</max-hops>
+ <discovery-group-ref discovery-group-name="my-discovery-group"/>
+ </cluster-connection>
+</cluster-connections>
+ </programlisting>
+ <para>In the above cluster connection all parameters have been explicitly specified. In
+ practice you might use the defaults for some.</para>
+ <itemizedlist>
+ <listitem>
+ <para><literal>address</literal>. Each cluster connection only applies to
+ messages sent to an address that starts with this value.</para>
+ <para>In this case, this cluster connection will load balance messages sent to
+ address that start with <literal>jms</literal>. This cluster connection,
+ will, in effect apply to all JMS queue and topic subscriptions since they
+ map to core queues that start with the substring "jms".</para>
+ <para>The address can be any value and you can have many cluster connections
+ with different values of <literal>address</literal>, simultaneously
+ balancing messages for those addresses, potentially to different clusters of
+ servers. By having multiple cluster connections on different addresses a
+ single JBoss Messaging Server can effectively take part in multiple clusters
+ simultaneously.</para>
+ <para>By careful not to have multiple cluster connections with overlapping
+ values of <literal>address</literal>, e.g. "europe" and "europe.news" since
+ this could result in the same messages being distributed between more than
+ one cluster connection, possibly resulting in duplicate deliveries. </para>
+ <para>This parameter is mandatory.</para>
+ </listitem>
+ <listitem>
+ <para><literal>retry-interval</literal>. We mentioned before that, internally,
+ cluster connections cause bridges to be created between the nodes of the
+ cluster. If the cluster connection is created and the target node has not
+ been started, or say, is being rebooted, then the cluster connections from
+ other nodes will retry connecting to the target until it comes back up, in
+ the same way as a bridge does.</para>
+ <para>This parameter determines the interval in milliseconds between retry
+ attempts. It has the same meaning as the <literal>retry-interval</literal>
+ on a bridge (as described in <xref linkend="core-bridges" />).</para>
+ <para>This parameter is optional and its default value is <literal>500</literal>
+ milliseconds.</para>
+ </listitem>
+ <listitem>
+ <para><literal>use-duplicate-detection</literal>. Internally cluster connections
+ use bridges to link the nodes, and bridges can be configured to add a
+ duplicate id property in each message that is forwarded. If the target node
+ of the bridge crashes and then recovers, messages might be resent from the
+ source node. By enabling duplicate detection any duplicate messages will be
+ filtered out and ignored on receipt at the target node.</para>
+ <para>This parameter has the same meaning as <literal
+ >use-duplicate-detection</literal> on a bridge. For more information on
+ duplicate detection, please see <xref linkend="duplicate-detection"
+ />.</para>
+ <para>This parameter is optional and has a default value of <literal
+ >true</literal>.</para>
+ </listitem>
+ <listitem>
+ <para><literal>forward-when-no-consumers</literal>. This parameter determines
+ whether messages will be distributed round robin between other nodes of the
+ cluster <emphasis>irrespective</emphasis> of whether there are matching or
+ indeed any consumers on other nodes. </para>
+ <para>If this is set to <literal>true</literal> then each incoming message will
+ be round robin'd even though the same queues on the other nodes of the
+ cluster may have no consumers at all, or they may have consumers that have
+ non matching message filters (selectors). Note that JBoss Messaging will
+ <emphasis>not</emphasis> forward messages to other nodes if there are no
+ <emphasis>queues</emphasis> of the same name on the other nodes, even if
+ this parameter is set to <literal>true</literal>.</para>
+ <para>If this is set to <literal>false</literal> then JBoss Messaging will only
+ forward messages to other nodes of the cluster if the address to which they
+ are being forwarded has queues which have consumers, and if those consumers
+ have message filters (selectors) at least one of those selectors must match
+ the message.</para>
+ <para>This parameter is optional, the default value is <literal
+ >false</literal>.</para>
+ </listitem>
+ <listitem>
+ <para><literal>max-hops</literal>. When a cluster connection decides the set of
+ nodes to which it might load balance a message, those nodes do not have to
+ be directly connected to it via a cluster connection. JBoss Messaging can be
+ configured to also load balance messages to nodes which might be connected
+ to it only indirectly with other JBoss Messaging servers as intermediates in
+ a chain.</para>
+ <para>This allows JBoss Messaging to be configured in more complex topologies
+ and still provide message load balancing. We'll discuss this more later in
+ this chapter.</para>
+ <para>The default value for this parameter is <literal>1</literal>, which means
+ messages are only load balanced to other JBoss Messaging serves which are
+ directly connected to this server. This parameter is optional.</para>
+ </listitem>
+ <listitem>
+ <para><literal>discovery-group-ref</literal>. This parameter determines which
+ discovery group is used to obtain the list of other servers in the cluster
+ that this cluster connection will make connections to.</para>
+ </listitem>
+ </itemizedlist>
+ </section>
+ </section>
+ <section id="clusters.client.loadbalancing">
+ <title>Client-Side Load balancing</title>
+ <para>With JBoss Messaging client-side connection load balancing, subsequent client
+ connections created using a single factory can be made to different nodes of the
+ cluster. This allows connections to spread smoothly across the nodes of a cluster and
+ not be "clumped" on any particular node.</para>
+ <para>The load balancing policy to be used by the client factory is configurable. JBoss
+ Messaging provides two out-of-the-box load balancing policies and you can also implement
+ your own and use that.</para>
+ <para>The out-of-the-box policies are</para>
+ <itemizedlist>
+ <listitem>
+ <para>Round Robin. With this policy the first node is chosen randomly then each
+ subsequent node is chosen sequentially in the same order.</para>
+ <para>For example nodes might be chosen in the order B, C, D, A, B, C, D, A, B or D,
+ A, B, C, A, B, C, D, A or C, D, A, B, C, D, A, B, C, D, A.</para>
+ </listitem>
+ <listitem>
+ <para>Random. With this policy each node is chosen randomly.</para>
+ </listitem>
+ </itemizedlist>
+ <para>You can also implement your own policy by implementing the interface <literal
+ >org.jboss.messaging.core.client.ConnectionLoadBalancingPolicy</literal></para>
+ <para>Specifying which load balancing policy to use differs whether you are using JMS or the
+ core API. If you don't specify a policy then the default will be used which is <literal
+ >org.jboss.messaging.core.client.impl.RoundRobinConnectionLoadBalancingPolicy</literal>.</para>
+ <para>If you're using JMS, and you're using JNDI on the server to put your JMS connection
+ factories into JNDI, then you can specify the load balancing policy directly in the
+ <literal>jbm-jms.xml</literal> configuration file on the server as follows:
+ <programlisting>
+<connection-factory name="ConnectionFactory">
+ <discovery-group-ref discovery-group-name="my-discovery-group"/>
+ <entries>
+ <entry name="ConnectionFactory"/>
+ </entries>
+ <connection-load-balancing-policy-class-name>
+ org.jboss.messaging.core.client.impl.RandomConnectionLoadBalancingPolicy
+ </connection-load-balancing-policy-class-name>
+</connection-factory>
+ </programlisting>The
+ above example would deploy a JMS connection factory that uses the random connection load
+ balancing policy. </para>
+ <para>If you're using JMS but you're instantiating your connection factory directly on the
+ client side then you can set the load balancing policy using the setter on the <literal
+ >JBossConnectionFactory</literal> before using it:
+ <programlisting>
+ConnectionFactory jmsConnectionFactory = new JBossConnectionFactory(...);
+jmsConnectionFactory.setLoadBalancingPolicyClassName("com.acme.MyLoadBalancingPolicy");
+ </programlisting></para>
+ <para>If you're using the core API, you can set the load balancing policy directly on the
+ <literal>ClientSessionFactory</literal> instance you are using:
+ <programlisting>
+ClientSessionFactory factory = new ClientSessionFactoryImpl(...);
+factory.setLoadBalancingPolicyClassName("com.acme.MyLoadBalancingPolicy");
+ </programlisting></para>
+ <para>The set of servers over which the factory load balances can be determined in one of
+ two ways:</para>
+ <itemizedlist>
+ <listitem>
+ <para>Specifying servers explicitly</para>
+ </listitem>
+ <listitem>
+ <para>Using discovery.</para>
+ </listitem>
+ </itemizedlist>
+ </section>
+ <section>
+ <title>Specifying Members of a Cluster Explicitly</title>
+ <para>Sometimes UDP is not enabled on a network so it's not possible to use UDP server
+ discovery for clients to discover the list of servers in the cluster, or for servers to
+ discover what other servers are in the cluster.</para>
+ <para>In this case, the list of servers in the cluster can be specified explicitly on each
+ node and on the client side. Let's look at how we do this:</para>
+ <section>
+ <title>Specify List of Servers on the Client Side</title>
+ <para>This differs depending on whether you're using JMS or the Core API</para>
+ <section>
+ <title>Specifying List of Servers using JMS</title>
+ <para>If you're using JMS, and you're using the JMS Service to load your JMS
+ connection factory instances directly into JNDI on the server, then you can
+ specify the list of servers in the server side configuration file <literal
+ >jbm-jms.xml</literal>. Let's take a look at an example:</para>
+ <programlisting><connection-factory name="ConnectionFactory">
+ <connector-ref connector-name="my-connector1"
+ backup-connector-name="my-backup-connector1"/>
+ <connector-ref connector-name="my-connector2"
+ backup-connector-name="my-backup-connector2"/>
+ <connector-ref connector-name="my-connector3"
+ backup-connector-name="my-backup-connector3"/>
+ <entries>
+ <entry name="ConnectionFactory"/>
+ </entries>
+</connection-factory></programlisting>
+ <para>The <literal>connection-factory</literal> element can contain zero or more
+ <literal>connector-ref</literal> elements, each one of which specifies a
+ <literal>connector-name</literal> attribute and an optional <literal
+ >backup-connector-name</literal> attribute. The <literal
+ >connector-name</literal> attribute references a connector defined in
+ <literal>jbm-configuration.xml</literal> which will be used as a live
+ connector. The <literal>backup-connector-name</literal> is optional, and if
+ specified it also references a connector defined in <literal
+ >jbm-configuration.xml</literal>. For more information on connectors please
+ see <xref linkend="configuring-transports" />.</para>
+ <para>The connection factory thus maintains a list of [connector, backup connector]
+ pairs, these pairs are then used by the client connection load balancing policy
+ on the client side when creating connections to the cluster.</para>
+ <para>If you're using JMS but you're not using JNDI then you can also specify the
+ list of [connector, backup connector] pairs directly when instantiating the
+ <literal>JBossConnectionFactory</literal>, here's an
+ example:<programlisting>List<Pair<TransportConfiguration, TransportConfiguration>> serverList =
+ new ArrayList<Pair<TransportConfiguration, TransportConfiguration>>();
+
+serverList.add(new Pair<TransportConfiguration,
+ TransportConfiguration>(liveTC0, backupTC0));
+serverList.add(new Pair<TransportConfiguration,
+ TransportConfiguration>(liveTC1, backupTC1));
+serverList.add(new Pair<TransportConfiguration,
+ TransportConfiguration>(liveTC2, backupTC2));
+
+ConnectionFactory jmsConnectionFactory = new JBossConnectionFactory(serverList);
+
+Connection jmsConnection1 = jmsConnectionFactory.createConnection();
+
+Connection jmsConnection2 = jmsConnectionFactory.createConnection();</programlisting></para>
+ <para>In the above snippet we create a list of pairs of <literal
+ >TransportConfiguration</literal> objects. Each <literal
+ >TransportConfiguration</literal> object contains knowledge of how to make a
+ connection to a specific server.</para>
+ <para>A <literal>JBossConnectionFactory</literal> instance is then created passing
+ the list of servers in the constructor. Any connections subsequently created by
+ this factory will create connections according to the client connection load
+ balancing policy applied to that list of servers.</para>
+ </section>
+ <section>
+ <title>Specifying List of Servers using the Core API</title>
+ <para>If you're using the core API you can also specify the list of servers directly
+ when creating the <literal>ClientSessionFactory</literal> instance. Here's an
+ example:</para>
+ <programlisting>List<Pair<TransportConfiguration, TransportConfiguration>> serverList =
+ new ArrayList<Pair<TransportConfiguration, TransportConfiguration>>();
+
+serverList.add(new Pair<TransportConfiguration,
+ TransportConfiguration>(liveTC0, backupTC0));
+serverList.add(new Pair<TransportConfiguration,
+ TransportConfiguration>(liveTC1, backupTC1));
+serverList.add(new Pair<TransportConfiguration,
+ TransportConfiguration>(liveTC2, backupTC2));
+
+ClientSessionFactory factory = new ClientSessionFactoryImpl(serverList);
+
+ClientSession sesison1 = factory.createClientSession(...);
+
+ClientSession session2 = factory.createClientSession(...);</programlisting>
+ <para>In the above snippet we create a list of pairs of <literal
+ >TransportConfiguration</literal> objects. Each <literal
+ >TransportConfiguration</literal> object contains knowledge of how to make a
+ connection to a specific server. For more information on this, please see
+ <xref linkend="configuring-transports" />.</para>
+ <para>A <literal>ClientSessionFactoryImpl</literal> instance is then created passing
+ the list of servers in the constructor. Any sessions subsequently created by
+ this factory will create sessions according to the client connection load
+ balancing policy applied to that list of servers.</para>
+ </section>
+ </section>
+ <section>
+ <title>Specifying List of Servers to form a Cluster</title>
+ <para>Let's take a look at an example where each cluster connection is defined for a
+ symmetric cluster, but we're not using discovery for each node to discover its
+ neighbours, instead we'll configure each cluster connection to have explicit
+ knowledge of all the other nodes in the cluster.</para>
+ <para>Here's an example cluster connection definition showing that:</para>
+ <programlisting><cluster-connections>
+ <cluster-connection name="my-explicit-cluster">
+ <address>jms</address>
+ <connector-ref connector-name="my-connector1"
+ backup-connector-name="my-backup-connector1"/>
+ <connector-ref connector-name="my-connector2"
+ backup-connector-name="my-backup-connector2"/>
+ <connector-ref connector-name="my-connector3"
+ backup-connector-name="my-backup-connector3"/>
+ </cluster-connection>
+</cluster-connections></programlisting>
+ <para>The <literal>cluster-connection</literal> element can contain zero or more
+ <literal>connector-ref</literal> elements, each one of which specifies a
+ <literal>connector-name</literal> attribute and an optional <literal
+ >backup-connector-name</literal> attribute. The <literal
+ >connector-name</literal> attribute references a connector defined in <literal
+ >jbm-configuration.xml</literal> which will be used as a live connector. The
+ <literal>backup-connector-name</literal> is optional, and if specified it also
+ references a connector defined in <literal>jbm-configuration.xml</literal>. For more
+ information on connectors please see <xref linkend="configuring-transports" />.</para>
+ </section>
+ </section>
+ <section id="clusters.message-redistribution">
+ <title>Message Redistribution</title>
+ <para>Another important part of clustering is message redistribution. Earlier we learned how
+ server side message load balancing round robins messages across the cluster. If <literal
+ >forward-when-no-consumers</literal> is false, then messages won't be forwarded to
+ nodes which don't have matching consumers, this is great and ensures that messages don't
+ arrive on a queue which has no consumers to consume them, however there is a situation
+ it doesn't solve: What happens if the consumers on a queue close after the messages have
+ been sent to the node? If there are no consumers on the queue the message won't get
+ consumed and we have a <emphasis>starvation</emphasis> situation.</para>
+ <para>This is where message redistribution comes in. With message redistribution JBoss
+ Messaging can be configured to automatically <emphasis>redistribute</emphasis> messages
+ from queues which have no consumers back to other nodes in the cluster which do have
+ matching consumers.</para>
+ <para>Message redistribution can be configured to kick in immediately after the last
+ consumer on a queue is closed, or to wait a configurable delay after the last consumer
+ on a queue is closed before redistributing. By default message redistribution is
+ disabled.</para>
+ <para>Message redistribution can be configured on a per address basis, by specifying the
+ redistribution delay in the address settings, for more information on configuring
+ address settings, please see <xref linkend="queue-attributes" />.</para>
+ <para>Here's an address settings snippet from <literal>jbm-configuration.xml</literal>
+ showing how message redistribution is enabled for a set of queues:</para>
+ <programlisting><address-settings>
+ <address-setting match="jms.#">
+ <redistribution-delay>0</redistribution-delay>
+ </address-setting>
+ </address-settings></programlisting>
+ <para>The above <literal>address-settings</literal> block would set a <literal
+ >redistribution-delay</literal> of <literal>0</literal> for any queue which is bound
+ to an address that starts with "jms.". All JMS queues and topic subscriptions are bound
+ to addresses that start with "jms.", so the above would enable instant (no delay)
+ redistribution for all JMS queues and topic subscriptions.</para>
+ <para>The attribute <literal>match</literal> can be an exact match or it can be a string
+ that conforms to the JBoss Messaging wildcard syntax (described in <xref linkend="wildcard-syntax"
+ />).</para>
+ <para>The element <literal>redistribution-delay</literal> defines the delay in milliseconds
+ after the last consumer is closed on a queue before redistributing messages from that
+ queue to other nodes of the cluster which do have matching consumers. A delay of zero
+ means the messages will be immediately redistributed. A value of <literal>-1</literal>
+ signifies that messages will never be redistributed. The default value is <literal
+ >-1</literal>.</para>
+ <para>It often makes sense to introduce a delay before redistributing as it's a common case
+ that a consumer closes but another one quickly is created on the same queue, in such a
+ case you probably don't want to redistribute immediately since the new consumer will
+ arrive shortly.</para>
+ </section>
+ <section>
+ <title>Cluster topologies</title>
+ <para>JBoss Messaging clusters can be connected together in many different topologies, let's
+ consider the two most common ones here</para>
+ <section id="symmetric-cluster">
+ <title>Symmetric cluster</title>
+ <para>A symmetric cluster is probably the most common cluster topology, and you'll be
+ familiar with if you've had experience of JBoss Application Server
+ clustering.</para>
+ <para>With a symmetric cluster every node in the cluster is connected to every other
+ node in the cluster. In other words every node in the cluster is no more than one
+ hop away from every other node.</para>
+ <para>To form a symmetric cluster every node in the cluster defines a cluster connection
+ with the attribute <literal>max-hops</literal> set to <literal>1</literal>.
+ Typically the cluster connection will use server discovery in order to know what
+ other servers in the cluster it should connect to, although it is possible to
+ explicitly define each target server too in the cluster connection if, for example,
+ UDP is not available on your network.</para>
+ <para>With a symmetric cluster each node knows about all the queues that exist on all
+ the other nodes and what consumers they have. With this knowledge it can determine
+ how to load balance and redistribute messages around the nodes.</para>
+ </section>
+ <section>
+ <title>Chain cluster</title>
+ <para>With a chain cluster, each node in the cluster is not connected to every node in
+ the cluster directly, instead the nodes form a chain with a node on each end of the
+ chain and all other nodes just connecting to the previous and next nodes in the
+ chain.</para>
+ <para>An example of this would be a three node chain consisting of nodes A, B and C.
+ Node A is hosted in one network and has many producer clients connected to it
+ sending order messages. Due to corporate policy, the order consumer clients need to
+ be hosted in a different network, and that network is only accessible via a third
+ network. In this setup node B acts as a mediator with no producers or consumers on
+ it. Any messages arriving on node A will be forwarded to node B, which will in turn
+ forward them to node C where they can get consumed. Node A does not need to directly
+ connect to C, but all the nodes can still act as a part of the cluster.</para>
+ <para>To set up a cluster in this way, node A would define a cluster connection that
+ connects to node B, and node B would define a cluster connection that connects to
+ node C. In this case we only want cluster connections in one direction since we're
+ only moving messages from node A->B->C and never from C->B->A.</para>
+ <para>For this topology we would set <literal>max-hops</literal> to <literal
+ >2</literal>. With a value of <literal>2</literal> the knowledge of what queues and
+ consumers that exist on node C would be propagated from node C to node B to node A.
+ Node A would then know to distribute messages to node B when they arrive, even
+ though node B has no consumers itself, it would know that a further hop away is node
+ C which does have consumers.</para>
+ </section>
+ </section>
+</chapter>
Added: projects/docs/enterprise/5.0/JBoss_Messaging_2.0.0/JBoss_Messaging_User_Guide/en-US/Command_Buffering.xml
===================================================================
--- projects/docs/enterprise/5.0/JBoss_Messaging_2.0.0/JBoss_Messaging_User_Guide/en-US/Command_Buffering.xml (rev 0)
+++ projects/docs/enterprise/5.0/JBoss_Messaging_2.0.0/JBoss_Messaging_User_Guide/en-US/Command_Buffering.xml 2009-10-05 01:37:17 UTC (rev 94324)
@@ -0,0 +1,32 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<chapter id="command-buffering">
+ <title>Command Buffering</title>
+ <para>As JBoss Messaging clients send commands to their servers they store each sent command in
+ an in-memory buffer. In the case that connection failure occurs and the client subsequently
+ reconnects to the same server or fails over onto a replica server, as part of the
+ reconnection protocol the server informs the client during reconnection with the id of the
+ last command it successfully received from that client.</para>
+ <para>If the client has sent more commands than were received before failover it can replay any
+ sent commands from its buffer so that the client and server can reconcile their
+ states.</para>
+ <para>The size of this buffer is configured by the <literal>ProducerWindowSize</literal>
+ parameter, when the server has received <literal>ProducerWindowSize</literal> bytes of
+ commands and processed them it will send back a command confirmation to the client, and the
+ client can then free up space in the buffer.</para>
+ <para>If you are using JMS and you're using the JMS service on the server to load your JMS
+ connection factory instances into JNDI then this parameter can be configured in <literal
+ >jbm-jms.xml</literal> using the element <literal>producer-window-size</literal> a. If
+ you're using JMS but not using JNDI then you can set these values directly on the <literal
+ >JBossConnectionFactory</literal> instance using the appropriate setter method.</para>
+ <para>If you're using core you can set these values directly on the <literal
+ >ClientSessionFactory</literal> instance using the appropriate setter method.</para>
+ <para>The send window is specified in bytes, and has a default value of <literal
+ >1MiB</literal>.</para>
+ <para>When the send buffer becomes full, any attempts to send more commands from the client will
+ block until the client receives a confirmation from the server and clears out the buffer.
+ Because of the blocking, the command buffer performs a type of <literal>flow
+ control</literal>, preventing the client from overwhelming the server with
+ commands.</para>
+ <para>Setting this parameter to <literal>-1</literal> disables any flow control on
+ sending.</para>
+</chapter>
Added: projects/docs/enterprise/5.0/JBoss_Messaging_2.0.0/JBoss_Messaging_User_Guide/en-US/Configuration_Reference.xml
===================================================================
--- projects/docs/enterprise/5.0/JBoss_Messaging_2.0.0/JBoss_Messaging_User_Guide/en-US/Configuration_Reference.xml (rev 0)
+++ projects/docs/enterprise/5.0/JBoss_Messaging_2.0.0/JBoss_Messaging_User_Guide/en-US/Configuration_Reference.xml 2009-10-05 01:37:17 UTC (rev 94324)
@@ -0,0 +1,1062 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<chapter id="configuration-index">
+ <title>Configuration Reference</title>
+ <para>This section is a quick index for looking up configuration. Click on the element name to
+ go to the specific chapter.</para>
+ <section id="server.configuration">
+ <title>Server Configuration</title>
+ <section>
+ <title>jbm-configuration.xml</title>
+ <para>This is the main core server configuration file.</para>
+ <table frame="topbot" border="2">
+ <title>Server Configuration</title>
+ <tgroup cols="4">
+ <colspec colname="c1" colnum="1"/>
+ <colspec colname="c2" colnum="2"/>
+ <colspec colname="c3" colnum="3"/>
+ <colspec colname="c4" colnum="4"/>
+ <thead>
+ <row>
+ <entry>Element Name</entry>
+ <entry>Element Type</entry>
+ <entry>Description</entry>
+ <entry>Default</entry>
+ </row>
+ </thead>
+ <tbody>
+ <row>
+ <entry><link linkend="configuring.live.backup">backup</link></entry>
+ <entry>Boolean</entry>
+ <entry>true means that this server is a backup to another node in the
+ cluster</entry>
+ <entry>false</entry>
+ </row>
+ <row>
+ <entry><link linkend="configuring.live.backup"
+ >backup-connector-ref</link></entry>
+ <entry>String</entry>
+ <entry>the name of the remoting connector to connect to the backup
+ node</entry>
+ <entry/>
+ </row>
+ <row>
+ <entry><link linkend="configuring.bindings.journal"
+ >bindings-directory</link></entry>
+ <entry>String</entry>
+ <entry>the directory to store the persisted bindings to</entry>
+ <entry>data/bindings</entry>
+ </row>
+ <row>
+ <entry><link linkend="clusters">clustered</link></entry>
+ <entry>Boolean</entry>
+ <entry>true means that the server is clustered</entry>
+ <entry>false</entry>
+ </row>
+ <row>
+ <entry><link linkend="connection-ttl"
+ >connection-ttl-override</link></entry>
+ <entry>Long</entry>
+ <entry>if set, this will override how long (in ms) to keep a connection
+ alive without receiving a ping. </entry>
+ <entry>-1</entry>
+ </row>
+ <row>
+ <entry><link linkend="configuring.bindings.journal"
+ >create-bindings-dir</link></entry>
+ <entry>Boolean</entry>
+ <entry>true means that the server will create the bindings directory on
+ start up</entry>
+ <entry>true</entry>
+ </row>
+ <row>
+ <entry><link linkend="configuring.message.journal.create-journal-dir"
+ >create-journal-dir</link></entry>
+ <entry>Boolean</entry>
+ <entry>true means that the journal directory will be created</entry>
+ <entry>true</entry>
+ </row>
+ <row>
+ <entry><link linkend="using-server.configuration"
+ >file-deployment-enabled</link></entry>
+ <entry>Boolean</entry>
+ <entry>true means that the server will load configuration from the
+ configuration files</entry>
+ <entry>true</entry>
+ </row>
+ <row>
+ <entry><link linkend="duplicate.id.cache">id-cache-size</link></entry>
+ <entry>Integer</entry>
+ <entry>the size of the cache for pre creating message id's</entry>
+ <entry>2000</entry>
+ </row>
+ <row>
+ <entry><link
+ linkend="configuring.message.journal.journal-aio-buffer-size"
+ >journal-aio-buffer-size</link></entry>
+ <entry>Long</entry>
+ <entry>The size of the internal buffer on AIO.</entry>
+ <entry>128 KiB</entry>
+ </row>
+ <row>
+ <entry><link
+ linkend="configuring.message.journal.journal-aio-buffer-timeout"
+ >journal-aio-buffer-timeout</link></entry>
+ <entry>Long</entry>
+ <entry>The timeout (in nanoseconds) used to flush internal
+ buffers.</entry>
+ <entry>20000</entry>
+ </row>
+ <row>
+ <entry><link
+ linkend="configuring.message.journal.journal-aio-flush-on-sync"
+ >journal-aio-flush-on-sync</link></entry>
+ <entry>Boolean</entry>
+ <entry>If true, transactions will ignore timeouts and be persisted
+ immediately</entry>
+ <entry>False</entry>
+ </row>
+ <row>
+ <entry><link
+ linkend="configuring.message.journal.journal-compact-min-files"
+ >journal-compact-min-files</link></entry>
+ <entry>Integer</entry>
+ <entry>The minimal number of data files before we can start
+ compacting</entry>
+ <entry>10</entry>
+ </row>
+ <row>
+ <entry><link
+ linkend="configuring.message.journal.journal-compact-percentage"
+ >journal-compact-percentage</link></entry>
+ <entry>Integer</entry>
+ <entry>The percentage of live data on which we consider compacting the
+ journal</entry>
+ <entry>30</entry>
+ </row>
+ <row>
+ <entry><link linkend="configuring.message.journal.journal-directory"
+ >journal-directory</link></entry>
+ <entry>String</entry>
+ <entry>the directory to store the journal files in</entry>
+ <entry>data/journal</entry>
+ </row>
+ <row>
+ <entry><link linkend="configuring.message.journal.journal-file-size"
+ >journal-file-size</link></entry>
+ <entry>Long</entry>
+ <entry>the size (in bytes) of each journal file</entry>
+ <entry>128 * 1024</entry>
+ </row>
+ <row>
+ <entry><link linkend="configuring.message.journal.journal-max-aio"
+ >journal-max-aio</link></entry>
+ <entry>Integer</entry>
+ <entry>the maximum number of write requests that can be in the AIO queue
+ at any one time</entry>
+ <entry>500</entry>
+ </row>
+ <row>
+ <entry><link linkend="configuring.message.journal.journal-min-files"
+ >journal-min-files</link></entry>
+ <entry>Integer</entry>
+ <entry>how many journal files to pre-create</entry>
+ <entry>2</entry>
+ </row>
+ <row>
+ <entry><link
+ linkend="configuring.message.journal.journal-sync-transactional"
+ >journal-sync-transactional</link></entry>
+ <entry>Boolean</entry>
+ <entry>if true wait for transaction data to be synchronized to the
+ journal before returning response to client</entry>
+ <entry>true</entry>
+ </row>
+ <row>
+ <entry><link
+ linkend="configuring.message.journal.journal-sync-non-transactional"
+ >journal-sync-non-transactional</link></entry>
+ <entry>Boolean</entry>
+ <entry>if true wait for non transaction data to be synced to the journal
+ before returning response to client.</entry>
+ <entry>false</entry>
+ </row>
+ <row>
+ <entry><link linkend="configuring.message.journal.journal-type"
+ >journal-type</link></entry>
+ <entry>ASYNCIO|NIO</entry>
+ <entry>the type of journal to use</entry>
+ <entry>ASYNCIO</entry>
+ </row>
+ <row>
+ <entry><link linkend="management.jmx.configuration"
+ >jmx-management-enabled</link></entry>
+ <entry>Boolean</entry>
+ <entry>true means that the management API is available via JMX</entry>
+ <entry>true</entry>
+ </row>
+ <row>
+ <entry><link linkend="large.message.configuring"
+ >large-messages-directory</link></entry>
+ <entry>String</entry>
+ <entry>the directory to store large messages</entry>
+ <entry>data/largemessages</entry>
+ </row>
+ <row>
+ <entry><link linkend="management.core.configuration"
+ >management-address</link></entry>
+ <entry>String</entry>
+ <entry>the name of the management address to send management messages
+ to</entry>
+ <entry>jbm.management</entry>
+ </row>
+ <row>
+ <entry><link linkend="management.replication"
+ >management-cluster-user</link></entry>
+ <entry>String</entry>
+ <entry>the user used to for replicating management operations between
+ clustered nodes</entry>
+ <entry>JBM.MANAGEMENT.ADMIN.USER</entry>
+ </row>
+ <row>
+ <entry><link linkend="management.replication"
+ >management-cluster-password</link></entry>
+ <entry>String</entry>
+ <entry>the password used to for replicating management operations
+ between clustered nodes</entry>
+ <entry>CHANGE ME!!</entry>
+ </row>
+ <row>
+ <entry><link linkend="management.notifications.core.configuration"
+ >management-notification-address</link></entry>
+ <entry>String</entry>
+ <entry>the name of the address that consumers bind to receive management
+ notifications</entry>
+ <entry>jbm.notifications</entry>
+ </row>
+ <row>
+ <entry><link linkend="management.replication"
+ >management-request-timeout</link></entry>
+ <entry>Long</entry>
+ <entry>how long (in ms) to wait for a reply to a management
+ request</entry>
+ <entry>5000</entry>
+ </row>
+ <row>
+ <entry><link linkend="configuring.message.counters"
+ >message-counter-enabled</link></entry>
+ <entry>Boolean</entry>
+ <entry>true means that message counters are enabled</entry>
+ <entry>false</entry>
+ </row>
+ <row>
+ <entry><link linkend="configuring.message.counters"
+ >message-counter-max-day-history</link></entry>
+ <entry>Integer</entry>
+ <entry>how many days to keep message counter history</entry>
+ <entry>10</entry>
+ </row>
+ <row>
+ <entry><link linkend="configuring.message.counters"
+ >message-counter-sample-period</link></entry>
+ <entry>Long</entry>
+ <entry>the sample period (in ms) to use for message counters</entry>
+ <entry>10000</entry>
+ </row>
+ <row>
+ <entry><link linkend="configuring.expiry.reaper"
+ >message-expiry-scan-period</link></entry>
+ <entry>Long</entry>
+ <entry>how often (in ms) to scan for expired messages</entry>
+ <entry>30000</entry>
+ </row>
+ <row>
+ <entry><link linkend="configuring.expiry.reaper"
+ >message-expiry-thread-priority</link></entry>
+ <entry>Integer</entry>
+ <entry>the priority of the thread expiring messages</entry>
+ <entry>3</entry>
+ </row>
+ <row>
+ <entry><link linkend="paging.main.config"
+ >paging-directory</link></entry>
+ <entry>String</entry>
+ <entry>the directory to store paged messages in</entry>
+ <entry>data/paging</entry>
+ </row>
+ <row>
+ <entry><link linkend="configuring.delivery.count.persistence">
+ persist-delivery-count-before-delivery</link></entry>
+ <entry>Boolean</entry>
+ <entry>true means that the delivery count is persisted before delivery.
+ False means that this only happens after a message has been
+ cancelled.</entry>
+ <entry>false</entry>
+ </row>
+ <row>
+ <entry><link linkend="persistence.enabled"
+ >persistence-enabled</link></entry>
+ <entry>Boolean</entry>
+ <entry>true means that the server will use the file based journal for
+ persistence.</entry>
+ <entry>true</entry>
+ </row>
+ <row>
+ <entry><link linkend="duplicate.id.cache"
+ >persist-id-cache</link></entry>
+ <entry>Boolean</entry>
+ <entry>true means that id's are persisted to the journal</entry>
+ <entry>true</entry>
+ </row>
+ <row>
+ <entry><link linkend="queue.activation.timeout"
+ >queue-activation-timeout</link></entry>
+ <entry>Long</entry>
+ <entry>after failover occurs, this timeout specifies how long (in ms) to
+ wait for consumers to re-attach before starting delivery</entry>
+ <entry>30000</entry>
+ </row>
+ <row>
+ <entry><link linkend="server.scheduled.thread.pool"
+ >scheduled-thread-pool-max-size</link></entry>
+ <entry>Integer</entry>
+ <entry>the number of threads that the main scheduled thread pool
+ has.</entry>
+ <entry>5</entry>
+ </row>
+ <row>
+ <entry><link linkend="security">security-enabled</link></entry>
+ <entry>Boolean</entry>
+ <entry>true means that security is enabled</entry>
+ <entry>true</entry>
+ </row>
+ <row>
+ <entry><link linkend="security"
+ >security-invalidation-interval</link></entry>
+ <entry>Long</entry>
+ <entry>how long (in ms) to wait before invalidating the security
+ cache</entry>
+ <entry>10000</entry>
+ </row>
+ <row>
+ <entry><link linkend="server.scheduled.thread.pool"
+ >thread-pool-max-size</link></entry>
+ <entry>Integer</entry>
+ <entry>the number of threads that the main thread pool has. -1 means no
+ limit</entry>
+ <entry>-1</entry>
+ </row>
+ <row>
+ <entry><link linkend="connection-ttl.async-connection-execution"
+ >async-connection-execution-enabled</link></entry>
+ <entry>Boolean</entry>
+ <entry>Should incoming packets on the server be handed off to a thread
+ from the thread pool for processing or should they be handled on the
+ remoting thread?</entry>
+ <entry>true</entry>
+ </row>
+ <row>
+ <entry><link linkend="transaction-config"
+ >transaction-timeout</link></entry>
+ <entry>Long</entry>
+ <entry>how long (in ms) before a transaction can be removed from the
+ resource manager after create time</entry>
+ <entry>60000</entry>
+ </row>
+ <row>
+ <entry><link linkend="transaction-config"
+ >transaction-timeout-scan-period</link></entry>
+ <entry>Long</entry>
+ <entry>how often (in ms) to scan for timeout transactions</entry>
+ <entry>1000</entry>
+ </row>
+ <row>
+ <entry><link linkend="wildcard-routing"
+ >wild-card-routing-enabled</link></entry>
+ <entry>Boolean</entry>
+ <entry>true means that the server supports wild card routing</entry>
+ <entry>true</entry>
+ </row>
+ <row>
+ <entry><link linkend="configuring-transports.acceptors"
+ >acceptors</link></entry>
+ <entry>Acceptor</entry>
+ <entry>a list of remoting acceptors to create</entry>
+ <entry/>
+ </row>
+ <row>
+ <entry><link linkend="clusters.broadcast-groups"
+ >broadcast-groups</link></entry>
+ <entry>BroadcastGroup</entry>
+ <entry>a list of broadcast groups to create</entry>
+ <entry/>
+ </row>
+ <row>
+ <entry><link linkend="understanding.connectors"
+ >connectors</link></entry>
+ <entry>Connector</entry>
+ <entry>a list of remoting connectors configurations to create</entry>
+ <entry/>
+ </row>
+ <row>
+ <entry><link linkend="clusters.discovery-groups"
+ >discovery-groups</link></entry>
+ <entry>DiscoveryGroup</entry>
+ <entry>a list of discovery groups to create</entry>
+ <entry/>
+ </row>
+ <row>
+ <entry><link linkend="diverts">diverts</link></entry>
+ <entry>Divert</entry>
+ <entry>a list of diverts to use</entry>
+ <entry/>
+ </row>
+ <row>
+ <entry><link linkend="diverts">divert.name (attribute)</link></entry>
+ <entry>String</entry>
+ <entry>a unique name for the divert - mandatory</entry>
+ <entry/>
+ </row>
+ <row>
+ <entry><link linkend="diverts">divert.routing-name</link></entry>
+ <entry>String</entry>
+ <entry>the routing name for the divert - mandatory</entry>
+ <entry/>
+ </row>
+ <row>
+ <entry><link linkend="diverts">divert.address</link></entry>
+ <entry>String</entry>
+ <entry>the address this divert will divert from - mandatory</entry>
+ <entry/>
+ </row>
+ <row>
+ <entry><link linkend="diverts">divert.forwarding-address</link></entry>
+ <entry>String</entry>
+ <entry>the forwarding address for the divert - mandatory</entry>
+ <entry/>
+ </row>
+ <row>
+ <entry><link linkend="diverts">divert.exclusive</link></entry>
+ <entry>Boolean</entry>
+ <entry>is this divert exclusive?</entry>
+ <entry>false</entry>
+ </row>
+ <row>
+ <entry><link linkend="diverts">divert.filter</link></entry>
+ <entry>String</entry>
+ <entry>an optional core filter expression</entry>
+ <entry>null</entry>
+ </row>
+ <row>
+ <entry><link linkend="diverts"
+ >divert.transformer-class-name</link></entry>
+ <entry>String</entry>
+ <entry>an optional class name of a transformer</entry>
+ <entry/>
+ </row>
+ <row>
+ <entry><link linkend="predefined.queues">queues</link></entry>
+ <entry>Queue</entry>
+ <entry>a list of pre configured queues to create</entry>
+ <entry/>
+ </row>
+ <row>
+ <entry><link linkend="predefined.queues">queues.name
+ (attribute)</link></entry>
+ <entry>String</entry>
+ <entry>unique name of this queue</entry>
+ <entry/>
+ </row>
+ <row>
+ <entry><link linkend="predefined.queues">queues.address</link></entry>
+ <entry>String</entry>
+ <entry>address for this queue - mandatory</entry>
+ <entry/>
+ </row>
+ <row>
+ <entry><link linkend="predefined.queues">queues.filter</link></entry>
+ <entry>String</entry>
+ <entry>optional core filter expression for this queue</entry>
+ <entry>null</entry>
+ </row>
+ <row>
+ <entry><link linkend="predefined.queues">queues.durable</link></entry>
+ <entry>Boolean</entry>
+ <entry>is this queue durable?</entry>
+ <entry>true</entry>
+ </row>
+ <row>
+ <entry><link linkend="core-bridges">bridges</link></entry>
+ <entry>Bridge</entry>
+ <entry>a list of bridges to create</entry>
+ <entry/>
+ </row>
+ <row>
+ <entry><link linkend="core-bridges">bridges.name
+ (attribute)</link></entry>
+ <entry>String</entry>
+ <entry>unique name for this bridge</entry>
+ <entry/>
+ </row>
+ <row>
+ <entry><link linkend="core-bridges">bridges.queue-name</link></entry>
+ <entry>String</entry>
+ <entry>name of queue that this bridge consumes from - mandatory</entry>
+ <entry/>
+ </row>
+ <row>
+ <entry><link linkend="core-bridges"
+ >bridges.forwarding-address</link></entry>
+ <entry>String</entry>
+ <entry>address to forward to. If omitted original destination is
+ used</entry>
+ <entry>null</entry>
+ </row>
+ <row>
+ <entry><link linkend="core-bridges">bridges.filter</link></entry>
+ <entry>String</entry>
+ <entry>optional core filter expression</entry>
+ <entry>null</entry>
+ </row>
+ <row>
+ <entry><link linkend="core-bridges"
+ >bridges.transformer-class-name</link></entry>
+ <entry>String</entry>
+ <entry>optional name of transformer class</entry>
+ <entry>null</entry>
+ </row>
+ <row>
+ <entry><link linkend="core-bridges"
+ >bridges.retry-interval</link></entry>
+ <entry>Long</entry>
+ <entry>period (in ms) between successive retries</entry>
+ <entry>2000 ms</entry>
+ </row>
+ <row>
+ <entry><link linkend="core-bridges"
+ >bridges.retry-interval-multiplier</link></entry>
+ <entry>Double</entry>
+ <entry>multiplier to apply to successive retry intervals</entry>
+ <entry>1.0</entry>
+ </row>
+ <row>
+ <entry><link linkend="core-bridges"
+ >bridges.reconnect-attempts</link></entry>
+ <entry>Integer</entry>
+ <entry>maximum number of retry attempts, -1 signifies infinite</entry>
+ <entry>-1</entry>
+ </row>
+ <row>
+ <entry><link linkend="core-bridges"
+ >bridges.failover-on-server-shutdown</link></entry>
+ <entry>Boolean</entry>
+ <entry>should failover be prompted if target server is cleanly
+ shutdown?</entry>
+ <entry>false</entry>
+ </row>
+ <row>
+ <entry><link linkend="core-bridges"
+ >bridges.use-duplicate-detection</link></entry>
+ <entry>Boolean</entry>
+ <entry>should duplicate detection headers be inserted in forwarded
+ messages?</entry>
+ <entry>true</entry>
+ </row>
+ <row>
+ <entry><link linkend="core-bridges"
+ >bridges.discovery-group-ref</link></entry>
+ <entry>String</entry>
+ <entry>name of discovery group used by this bridge</entry>
+ <entry>null</entry>
+ </row>
+ <row>
+ <entry><link linkend="core-bridges">bridges.connector-ref.connector-name
+ (attribute)</link></entry>
+ <entry>String</entry>
+ <entry>name of connector to use for live connection</entry>
+ <entry/>
+ </row>
+ <row>
+ <entry><link linkend="core-bridges"
+ >bridges.connector-ref.backup-connector-name
+ (attribute)</link></entry>
+ <entry>String</entry>
+ <entry>optional name of connector to use for backup connection</entry>
+ <entry>null</entry>
+ </row>
+ <row>
+ <entry><link linkend="clusters.cluster-connections"
+ >cluster-connections</link></entry>
+ <entry>ClusterConnection</entry>
+ <entry>a list of cluster connections</entry>
+ <entry/>
+ </row>
+ <row>
+ <entry><link linkend="clusters.cluster-connections"
+ >cluster-connections.name (attribute)</link></entry>
+ <entry>String</entry>
+ <entry>unique name for this cluster connection</entry>
+ <entry/>
+ </row>
+ <row>
+ <entry><link linkend="clusters.cluster-connections"
+ >cluster-connections.address</link></entry>
+ <entry>String</entry>
+ <entry>name of address this cluster connection applies to</entry>
+ <entry/>
+ </row>
+ <row>
+ <entry><link linkend="clusters.cluster-connections"
+ >cluster-connections.forward-when-no-consumers</link></entry>
+ <entry>Boolean</entry>
+ <entry>should messages be load balanced if there are no matching
+ consumers on target?</entry>
+ <entry>false</entry>
+ </row>
+ <row>
+ <entry><link linkend="clusters.cluster-connections"
+ >cluster-connections.max-hops</link></entry>
+ <entry>Integer</entry>
+ <entry>maximum number of hops cluster topology is propagated</entry>
+ <entry>1</entry>
+ </row>
+ <row>
+ <entry><link linkend="clusters.cluster-connections"
+ >cluster-connections.retry-interval</link></entry>
+ <entry>Long</entry>
+ <entry>period (in ms) between successive retries</entry>
+ <entry>2000</entry>
+ </row>
+ <row>
+ <entry><link linkend="clusters.cluster-connections"
+ >cluster-connections.use-duplicate-detection</link></entry>
+ <entry>Boolean</entry>
+ <entry>should duplicate detection headers be inserted in forwarded
+ messages?</entry>
+ <entry>true</entry>
+ </row>
+ <row>
+ <entry><link linkend="clusters.cluster-connections"
+ >cluster-connections.discovery-group-ref</link></entry>
+ <entry>String</entry>
+ <entry>name of discovery group used by this bridge</entry>
+ <entry>null</entry>
+ </row>
+ <row>
+ <entry><link linkend="clusters.cluster-connections"
+ >cluster-connections.connector-ref.connector-name
+ (attribute)</link></entry>
+ <entry>String</entry>
+ <entry>name of connector to use for live connection</entry>
+ <entry/>
+ </row>
+ <row>
+ <entry><link linkend="clusters.cluster-connections"
+ >cluster-connections.connector-ref.backup-connector-name
+ (attribute)</link></entry>
+ <entry>String</entry>
+ <entry>optional name of connector to use for backup connection</entry>
+ <entry>null</entry>
+ </row>
+ <row>
+ <entry><link linkend="security.settings.roles"
+ >security-settings</link></entry>
+ <entry>SecuritySetting</entry>
+ <entry>a list of security settings</entry>
+ <entry/>
+ </row>
+ <row>
+ <entry><link linkend="security.settings.roles">security-settings.match
+ (attribute)</link></entry>
+ <entry>String</entry>
+ <entry>the string to use for matching security against an
+ address</entry>
+ <entry/>
+ </row>
+ <row>
+ <entry><link linkend="security.settings.roles"
+ >security-settings.permission</link></entry>
+ <entry>Security Permission</entry>
+ <entry>a permision to add to the address</entry>
+ <entry/>
+ </row>
+ <row>
+ <entry><link linkend="security.settings.roles"
+ >security-settings.permission.type (attribute)</link></entry>
+ <entry>Permission Type</entry>
+ <entry>the type of permission</entry>
+ <entry/>
+ </row>
+ <row>
+ <entry><link linkend="security.settings.roles"
+ >security-settings.permission.roles (attribute)</link></entry>
+ <entry>Roles</entry>
+ <entry>a comma-separated list of roles to apply the permission
+ to</entry>
+ <entry/>
+ </row>
+ <row>
+ <entry><link linkend="queue-attributes.address-settings"
+ >address-settings</link></entry>
+ <entry>AddressSetting</entry>
+ <entry>a list of address settings</entry>
+ <entry/>
+ </row>
+ <row>
+ <entry><link linkend="undelivered-messages.configuring"
+ >address-settings.dead-letter-address</link></entry>
+ <entry>String</entry>
+ <entry>the address to send dead messages too</entry>
+ <entry/>
+ </row>
+ <row>
+ <entry><link linkend="undelivered-messages.configuring"
+ >address-settings.max-delivery-attempts</link></entry>
+ <entry>Integer</entry>
+ <entry>how many times to attempt to deliver a message before sending to
+ dead letter address</entry>
+ <entry>10</entry>
+ </row>
+ <row>
+ <entry><link linkend="message-expiry.configuring"
+ >address-settings.expiry-address</link></entry>
+ <entry>String</entry>
+ <entry>the address to send expired messages too</entry>
+ <entry/>
+ </row>
+ <row>
+ <entry><link linkend="undelivered-messages.delay"
+ >address-settings.redelivery-delay</link></entry>
+ <entry>Long</entry>
+ <entry>the time (in ms) to wait before redelivering a cancelled
+ message.</entry>
+ <entry>0</entry>
+ </row>
+ <row>
+ <entry><link linkend="last-value-queues"
+ >address-settings.last-value-queue</link></entry>
+ <entry>boolean</entry>
+ <entry>whether to treat the queue as a last value queue</entry>
+ <entry>false</entry>
+ </row>
+ <row>
+ <entry><link linkend="queue-attributes.address-settings"
+ >address-settings.distribution-policy-class</link></entry>
+ <entry>String</entry>
+ <entry>the class to use for distributing messages to a consumer</entry>
+ <entry>RoundRobinDistributor</entry>
+ </row>
+ <row>
+ <entry><link linkend="paging"
+ >address-settings.page-size-bytes</link></entry>
+ <entry>Long</entry>
+ <entry>the page size (in bytes) to use for an address</entry>
+ <entry>10 * 1024 * 1024</entry>
+ </row>
+ <row>
+ <entry><link linkend="paging"
+ >address-settings.max-size-bytes</link></entry>
+ <entry>Long</entry>
+ <entry>the maximum size (in bytes) to use in paging for an
+ address</entry>
+ <entry>-1</entry>
+ </row>
+ <row>
+ <entry><link linkend="clusters.message-redistribution"
+ >address-settings.redistribution-delay</link></entry>
+ <entry>Long</entry>
+ <entry>how long (in ms) to wait after the last consumer is closed on a
+ queue before redistributing messages.</entry>
+ <entry>-1</entry>
+ </row>
+ </tbody>
+ </tgroup>
+ </table>
+ </section>
+ <section>
+ <title>jbm-jms.xml</title>
+ <para>This is the configuration file used by the server side JMS service to load JMS
+ Queues, Topics and Connection Factories.</para>
+ <table frame="topbot" border="2">
+ <title>JMS Server Configuration</title>
+ <tgroup cols="4">
+ <colspec colname="c1" colnum="1"/>
+ <colspec colname="c2" colnum="2"/>
+ <colspec colname="c3" colnum="3"/>
+ <colspec colname="c4" colnum="4"/>
+ <thead>
+ <row>
+ <entry>Element Name</entry>
+ <entry>Element Type</entry>
+ <entry>Description</entry>
+ <entry>Default</entry>
+ </row>
+ </thead>
+ <tbody>
+ <row>
+ <entry><link linkend="using-jms.server.configuration"
+ >connection-factory</link></entry>
+ <entry>ConnectionFactory</entry>
+ <entry>a list of connection factories to create and add to JNDI</entry>
+ <entry/>
+ </row>
+ <row>
+ <entry><link linkend="message-grouping.jmsconfigure"
+ >connection-factory.auto-group</link></entry>
+ <entry>Boolean</entry>
+ <entry>whether or not message grouping is automatically used</entry>
+ <entry>false</entry>
+ </row>
+ <row>
+ <entry><link linkend="send-guarantees.nontrans.acks"
+ >connection-factory.block-on-acknowledge</link></entry>
+ <entry>Boolean</entry>
+ <entry>whether or not messages are acknowledged synchronously</entry>
+ <entry>false</entry>
+ </row>
+ <row>
+ <entry><link linkend="non-transactional-sends"
+ >connection-factory.block-on-non-persistent-send</link></entry>
+ <entry>Boolean</entry>
+ <entry>whether or not non persistent messages are sent
+ synchronously</entry>
+ <entry>false</entry>
+ </row>
+ <row>
+ <entry><link linkend="non-transactional-sends"
+ >connection-factory.block-on-persistent-send</link></entry>
+ <entry>Boolean</entry>
+ <entry>whether or not persistent messages are sent synchronously</entry>
+ <entry>false</entry>
+ </row>
+ <row>
+ <entry>connection-factory.call-timeout</entry>
+ <entry>Long</entry>
+ <entry>the timeout (in ms) for remote calls</entry>
+ <entry>30000</entry>
+ </row>
+ <row>
+ <entry><link linkend="dead.connections"
+ >connection-factory.client-failure-check-period</link></entry>
+ <entry>Long</entry>
+ <entry>the period (in ms) after which the client will consider the
+ connection failed after not receiving packets from the
+ server</entry>
+ <entry>5000</entry>
+ </row>
+ <row>
+ <entry><link linkend="using-jms.clientid"
+ >connection-factory.client-id</link></entry>
+ <entry>String</entry>
+ <entry>the pre-configured client ID for the connection factory</entry>
+ <entry>null</entry>
+ </row>
+ <row>
+ <entry><link linkend="clusters.client.loadbalancing"
+ >connection-factory.connection-load-balancing-policy-class-name</link></entry>
+ <entry>String</entry>
+ <entry>the name of the load balancing class</entry>
+ <entry>org.jboss.messaging.core.client.impl.RoundRobinConnectionLoadBalancingPolicy</entry>
+ </row>
+ <row>
+ <entry><link linkend="dead.connections"
+ >connection-factory.connection-ttl</link></entry>
+ <entry>Long</entry>
+ <entry>the time to live (in ms) for connections</entry>
+ <entry>5 * 60000</entry>
+ </row>
+ <row>
+ <entry><link linkend="flow-control.rate.core.api"
+ >connection-factory.consumer-max-rate</link></entry>
+ <entry>Integer</entry>
+ <entry>the fastest rate a consumer may consume messages per
+ second</entry>
+ <entry>-1</entry>
+ </row>
+ <row>
+ <entry><link linkend="flow-control.core.api"
+ >connection-factory.consumer-window-size</link></entry>
+ <entry>Integer</entry>
+ <entry>the window size (in bytes) for consumer flow control</entry>
+ <entry>1024 * 1024</entry>
+ </row>
+ <row>
+ <entry><link linkend="clusters-discovery.groups.clientside"
+ >connection-factory.discovery-initial-wait-timeout</link></entry>
+ <entry>Long</entry>
+ <entry>the initial time to wait (in ms) for discovery groups to wait for
+ broadcasts</entry>
+ <entry>2000</entry>
+ </row>
+ <row>
+ <entry><link linkend="using-jms.dupsokbatchsize"
+ >connection-factory.dups-ok-batch-size</link></entry>
+ <entry>Integer</entry>
+ <entry>the batch size (in bytes) between acknowledgements when using
+ DUPS_OK_ACKNOWLEDGE mode</entry>
+ <entry>1024 * 1024</entry>
+ </row>
+ <row>
+ <entry><link linkend="ha.client.automatic"
+ >connection-factory.failover-on-server-shutdown</link></entry>
+ <entry>Boolean</entry>
+ <entry>whether or not to failover on server shutdown</entry>
+ <entry>false</entry>
+ </row>
+ <row>
+ <entry><link linkend="connection-ttl.session.multiplexing"
+ >connection-factory.max-connections</link></entry>
+ <entry>Integer</entry>
+ <entry>the maximum number of connections per factory</entry>
+ <entry>8</entry>
+ </row>
+ <row>
+ <entry><link linkend="large-messages.core.config"
+ >connection-factory.min-large-message-size</link></entry>
+ <entry>Integer</entry>
+ <entry>the size (in bytes) before a message is treated as large </entry>
+ <entry>100 * 1024</entry>
+ </row>
+ <row>
+ <entry><link linkend="large-messages.cache.client"
+ >connection-factory.cache-large-message-client</link></entry>
+ <entry>Boolean</entry>
+ <entry>If true clients using this connection factory will hold the large
+ message body on temporary files.</entry>
+ <entry>false</entry>
+ </row>
+ <row>
+ <entry><link linkend="pre-acknowledge.configure"
+ >connection-factory.pre-acknowledge</link></entry>
+ <entry>Boolean</entry>
+ <entry>whether messages are pre acknowledged by the server before
+ sending</entry>
+ <entry>false</entry>
+ </row>
+ <row>
+ <entry><link linkend="flow-control.producer.rate.core.api"
+ >connection-factory.producer-max-rate</link></entry>
+ <entry>Integer</entry>
+ <entry>the maximum rate of messages per second that can be sent</entry>
+ <entry>-1</entry>
+ </row>
+ <row>
+ <entry><link linkend="command-buffering"
+ >connection-factory.producer-window-size</link></entry>
+ <entry>Integer</entry>
+ <entry>the window size (in bytes) for sending messages</entry>
+ <entry>1024 * 1024</entry>
+ </row>
+ <row>
+ <entry><link linkend="client-reconnection"
+ >connection-factory.reconnect-attempts</link></entry>
+ <entry>Integer</entry>
+ <entry>maximum number of retry attempts, -1 signifies infinite</entry>
+ <entry>0</entry>
+ </row>
+ <row>
+ <entry><link linkend="client-reconnection"
+ >connection-factory.retry-interval</link></entry>
+ <entry>Long</entry>
+ <entry>the time (in ms) to retry a connection after failing</entry>
+ <entry>2000</entry>
+ </row>
+ <row>
+ <entry><link linkend="client-reconnection"
+ >connection-factory.retry-interval-multiplier</link></entry>
+ <entry>Double</entry>
+ <entry>multiplier to apply to successive retry intervals</entry>
+ <entry>1d</entry>
+ </row>
+ <row>
+ <entry><link linkend="thread-pooling.client.side"
+ >connection-factory.scheduled-thread-pool-max-size</link></entry>
+ <entry>Integer</entry>
+ <entry>the size of the scheduled thread pool</entry>
+ <entry>2</entry>
+ </row>
+ <row>
+ <entry><link linkend="thread-pooling.client.side"
+ >connection-factory.thread-pool-max-size</link></entry>
+ <entry>Integer</entry>
+ <entry>the size of the thread pool</entry>
+ <entry>-1</entry>
+ </row>
+ <row>
+ <entry><link linkend="using-jms.txbatchsize"
+ >connection-factory.transaction-batch-size</link></entry>
+ <entry>Integer</entry>
+ <entry>the batch size (in bytes) between acknowledgements when using a
+ transactional session</entry>
+ <entry>1024 * 1024</entry>
+ </row>
+ <row>
+ <entry><link linkend="thread-pooling.client.side"
+ >connection-factory.use-global-pools</link></entry>
+ <entry>Boolean</entry>
+ <entry>whether or not to use a global thread pool for threads</entry>
+ <entry>true</entry>
+ </row>
+ <row>
+ <entry><link linkend="using-jms.server.configuration"
+ >queue</link></entry>
+ <entry>Queue</entry>
+ <entry>a queue to create and add to JNDI</entry>
+ <entry/>
+ </row>
+ <row>
+ <entry><link linkend="using-jms.server.configuration">queue.name
+ (attribute)</link></entry>
+ <entry>String</entry>
+ <entry>unique name of the queue</entry>
+ <entry/>
+ </row>
+ <row>
+ <entry><link linkend="using-jms.server.configuration"
+ >queue.entry</link></entry>
+ <entry>String</entry>
+ <entry>context where the queue will be bound in JNDI (there can be
+ many)</entry>
+ <entry/>
+ </row>
+ <row>
+ <entry><link linkend="using-jms.server.configuration"
+ >queue.durable</link></entry>
+ <entry>Boolean</entry>
+ <entry>is the queue durable?</entry>
+ <entry>true</entry>
+ </row>
+ <row>
+ <entry><link linkend="using-jms.server.configuration"
+ >queue.filter</link></entry>
+ <entry>String</entry>
+ <entry>optional filter expression for the queue</entry>
+ <entry/>
+ </row>
+ <row>
+ <entry><link linkend="using-jms.server.configuration"
+ >topic</link></entry>
+ <entry>Topic</entry>
+ <entry>a topic to create and add to JNDI</entry>
+ <entry/>
+ </row>
+ <row>
+ <entry><link linkend="using-jms.server.configuration">topic.name
+ (attribute)</link></entry>
+ <entry>String</entry>
+ <entry>unique name of the topic</entry>
+ <entry/>
+ </row>
+ <row>
+ <entry><link linkend="using-jms.server.configuration"
+ >topic.entry</link></entry>
+ <entry>String</entry>
+ <entry>context where the topic will be bound in JNDI (there can be
+ many)</entry>
+ <entry/>
+ </row>
+ </tbody>
+ </tgroup>
+ </table>
+ </section>
+ </section>
+</chapter>
Added: projects/docs/enterprise/5.0/JBoss_Messaging_2.0.0/JBoss_Messaging_User_Guide/en-US/Configuring_the_Transports.xml
===================================================================
--- projects/docs/enterprise/5.0/JBoss_Messaging_2.0.0/JBoss_Messaging_User_Guide/en-US/Configuring_the_Transports.xml (rev 0)
+++ projects/docs/enterprise/5.0/JBoss_Messaging_2.0.0/JBoss_Messaging_User_Guide/en-US/Configuring_the_Transports.xml 2009-10-05 01:37:17 UTC (rev 94324)
@@ -0,0 +1,418 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<chapter id="configuring-transports">
+ <title>Configuring the Transport</title>
+ <para>JBoss Messaging has a fully pluggable and highly flexible transport layer and defines its
+ own Service Provider Interface (SPI) to make plugging in a new transport provider relatively
+ straightforward.</para>
+ <para>In this chapter we'll describe the concepts required for understanding JBoss Messaging
+ transports and where and how they're configured.</para>
+ <section id="configuring-transports.acceptors">
+ <title>Understanding Acceptors</title>
+ <para>One of the most important concepts in JBoss Messaging transports is the
+ <emphasis>acceptor</emphasis>. Let's dive straight in and take a look at an acceptor
+ defined in xml in the configuration file <literal
+ >jbm-configuration.xml</literal>.</para>
+ <programlisting>
+<acceptors>
+ <acceptor name="netty">
+ <factory-class>
+org.jboss.messaging.integration.transports.netty.NettyAcceptorFactory
+ </factory-class>
+ <param key="jbm.remoting.netty.port" value="5446" type="Integer"/>
+ </acceptor>
+</acceptors>
+ </programlisting>
+ <para>Acceptors are always defined inside an <literal>acceptors</literal> element. There can
+ be one or more acceptors defined in the <literal>acceptors</literal> element. There's no
+ upper limit to the number of acceptors per server.</para>
+ <para>Each acceptor defines a way in which connections can be made to the JBoss Messaging
+ server.</para>
+ <para>In the above example we're defining an acceptor that uses Netty to listen for
+ connections at port <literal>5446</literal>. </para>
+ <para>The <literal>acceptor</literal> element contains a sub-element <literal
+ >factory-class</literal>, this element defines the factory used to create acceptor
+ instances. In this case we're using Netty to listen for connections so we use the Netty
+ implementation of an <literal>AcceptorFactory</literal> to do this. Basically, the
+ <literal>factory-class</literal> element determines which pluggable transport we're
+ going to use to do the actual listening.</para>
+ <para>The <literal>acceptor</literal> element can also be configured with zero or more
+ <literal>param</literal> sub-elements. Each <literal>param</literal> element defines
+ a key-value pair. These key-value pairs are used to configure the specific transport,
+ the set of valid key-value pairs depends on the specific transport be used and are
+ passed straight through to the underlying transport.</para>
+ <para>Examples of key-value pairs for a particular transport would be, say, to configure the
+ IP address to bind to, or the port to listen at.</para>
+ <para>Keys are always strings and values can be of type Long, Integer, String or
+ Boolean.</para>
+ </section>
+ <section id="understanding.connectors">
+ <title>Understanding Connectors</title>
+ <para>Whereas acceptors are used on the server to define how we accept connections,
+ connectors are used by a client to define how it connects to a server.</para>
+ <para>Let's look at a connector defined in our <literal>jbm-configuration.xml</literal>
+ file:</para>
+ <programlisting>
+<connectors>
+ <connector name="netty">
+ <factory-class>
+ org.jboss.messaging.integration.transports.netty.NettyConnectorFactory
+ </factory-class>
+ <param key="jbm.remoting.netty.port" value="5446" type="Integer"/>
+ </connector>
+</connectors>
+ </programlisting>
+ <para>Connectors can be defined inside an <literal>connectors</literal> element. There can
+ be one or more connectors defined in the <literal>connectors</literal> element. There's
+ no upper limit to the number of connectors per server.</para>
+ <para>You make ask yourself, if connectors are used by the <emphasis>client</emphasis> to
+ make connections then why are they defined on the <emphasis>server</emphasis>? There are
+ a couple of reasons for this:</para>
+ <itemizedlist>
+ <listitem>
+ <para>Sometimes the server acts as a client itself when it connects to another
+ server, for example when one server is bridged to another, or when a server
+ takes part in a cluster. In this cases the server needs to know how to connect
+ to other servers. That's defined by <emphasis>connectors</emphasis>.</para>
+ </listitem>
+ <listitem>
+ <para>If you're using JMS and the server side JMS service to instantiate JMS
+ ConnectionFactory instances and bind them in JNDI, then when creating the
+ <literal>JBossConnectionFactory</literal> it needs to know what server that
+ connection factory will create connections to.</para>
+ <para>That's defined by the <literal>connector-ref</literal> element in the <literal
+ >jbm-jms.xml</literal>file on the server side. Let's take a look at a
+ snipped from a <literal>jbm-jms.xml</literal> file that shows a JMS connection
+ factory that references our netty connector defined in our <literal
+ >jbm-configuration.xml</literal> file:</para>
+ <programlisting>
+<connection-factory name="ConnectionFactory">
+ <connector-ref connector-name="netty"/>
+ <entries>
+ <entry name="ConnectionFactory"/>
+ <entry name="XAConnectionFactory"/>
+ </entries>
+</connection-factory>
+ </programlisting>
+ </listitem>
+ </itemizedlist>
+ </section>
+ <section id="configuring-transports.client.side">
+ <title>Configuring the transport directly from the client side.</title>
+ <para>How do we configure a core <literal>ClientSessionFactory</literal> with the
+ information that it needs to connect with a server?</para>
+ <para>Connectors are also used indirectly when directly configuring a core <literal
+ >ClientSessionFactory</literal> to directly talk to a server. Although in this case
+ there's no need to define such a connector in the server side configuration, instead we
+ just create the parameters and tell the <literal>ClientSessionFactory</literal> which
+ connector factory to use.</para>
+ <para>Here's an example of creating a <literal>ClientSessionFactory</literal> which will
+ connect directly to the acceptor we defined earlier in this chapter, it uses the
+ standard Netty TCP transport and will try and connect on port 5446 to localhost
+ (default):</para>
+ <programlisting>
+Map<String, Object> connectionParams = new HashMap<String, Object>();
+
+ connectionParams.put(org.jboss.messaging.integration.transports.netty.TransportConstants.PORT_PROP_NAME,
+ 5446);
+
+TransportConfiguration transportConfiguration =
+ new TransportConfiguration(
+ "org.jboss.messaging.integration.transports.netty.NettyConnectorFactory",
+ connectionParams);
+
+ClientSessionFactory sessionFactory = new ClientSessionFactoryImpl(transportConfiguration);
+
+ClientSession session = sessionFactory.createSession(...);
+
+etc
+ </programlisting>
+ <para>Similarly, if you're using JMS, you can configure the JMS connection factory directly
+ on the client side without having to define a connector on the server side or define a
+ connection factory in <literal>jbm-jms.xml</literal>:</para>
+ <programlisting>
+Map<String, Object> connectionParams = new HashMap<String, Object>();
+
+connectionParams.put(org.jboss.messaging.integration.transports.netty.TransportConstants.PORT_PROP_NAME, 5446);
+
+TransportConfiguration transportConfiguration =
+ new TransportConfiguration(
+ "org.jboss.messaging.integration.transports.netty.NettyConnectorFactory",
+ connectionParams);
+
+ConnectionFactory connectionFactory = new JBossConnectionFactory(transportConfiguration);
+
+Connection jmsConnection = connectionFactory.createConnection();
+
+etc
+ </programlisting>
+ </section>
+ <section>
+ <title>Configuring the Netty transport</title>
+ <para>Out of the box, JBoss Messaging currently uses <ulink
+ url="http://www.jboss.org/netty/">Netty</ulink>, a high performance low level
+ network library.</para>
+ <para>Our Netty transport can be configured in several different ways; to use old (blocking)
+ Java IO, or NIO (non-blocking), also to use straightforward TCP sockets, SSL, or to
+ tunnel over HTTP or HTTPS, on top of that we also provide a servlet transport.</para>
+ <para>We believe this caters for the vast majority of transport requirements.</para>
+ <section>
+ <title>Configuring Netty TCP</title>
+ <para> Netty TCP is a simple unencrypted TCP sockets based transport. Netty TCP can be
+ configured to use old blocking Java IO or non blocking Java NIO. We recommend you
+ use the default Java NIO for better scalability. </para>
+ <para>If you're running connections across an untrusted network please bear in mind this
+ transport is unencrypted. You may want to look at the SSL or HTTPS
+ configurations.</para>
+ <para>With the Netty TCP transport all connections are initiated from the client side.
+ I.e. the server does not initiate any connections to the client. This works well
+ with firewall policies that typically only allow connections to be initiated in one
+ direction.</para>
+ <para>All the valid Netty transport keys are defined in the class <literal
+ >org.jboss.messaging.integration.transports.netty.TransportConstants</literal>.
+ The parameters can be used either with acceptors or connectors. The following
+ parameters can be used to configure Netty for simple TCP:</para>
+ <itemizedlist>
+ <listitem>
+ <para><literal>jbm.remoting.netty.usenio</literal>. If this is <literal
+ >true</literal> then Java non blocking NIO will be used. If set to
+ <literal>false</literal> than old blocking Java IO will be used.</para>
+ <para>We highly recommend that you use non blocking Java NIO. Java NIO does not
+ maintain a thread per connection so can scale to many more concurrent
+ connections than with old blocking IO. We recommend the usage of Java 6 for
+ NIO and the best scalability. The default value for this property is
+ <literal>true</literal>.</para>
+ </listitem>
+ <listitem>
+ <para><literal>jbm.remoting.netty.host</literal>. This specified the host name
+ or ip address to connect to (when configuring a connector) or to listen on
+ (when configuring an acceptor). The default value for this property is
+ <literal>localhost</literal>. Note that if you want your servers
+ accessible from other nodes, don't bind to localhost!</para>
+ </listitem>
+ <listitem>
+ <para><literal>jbm.remoting.netty.port</literal>. This specified the port to
+ connect to (when configuring a connector) or to listen on (when configuring
+ an acceptor). The default value for this property is <literal
+ >5445</literal>.</para>
+ </listitem>
+ <listitem>
+ <para><literal>jbm.remoting.netty.tcpnodelay</literal>. If this is <literal
+ >true</literal> then <ulink
+ url="http://en.wikipedia.org/wiki/Nagle's_algorithm">Nagle's
+ algorithm</ulink> will be enabled. The default value for this property
+ is <literal>true</literal>.</para>
+ </listitem>
+ <listitem>
+ <para><literal>jbm.remoting.netty.tcpsendbuffersize</literal>. This parameter
+ determines the size of the TCP send buffer in bytes. The default value for
+ this property is <literal>32768</literal> bytes (32KiB).</para>
+ <para>TCP buffer sizes should be tuned according to the bandwidth and latency of
+ your network. Here's a good link that explains the theory behind <ulink
+ url="http://www-didc.lbl.gov/TCP-tuning/">this</ulink>.</para>
+ <para>In summary TCP send/receive buffer sizes should be calculated as:</para>
+ <programlisting>
+ buffer_size = bandwidth * RTT.
+ </programlisting>
+ <para>Where bandwidth is in <emphasis>bytes per second</emphasis> and network
+ round trip time (RTT) is in seconds. RTT can be easily measured using the
+ <literal>ping</literal> utility.</para>
+ <para>For fast networks you may want to increase the buffer sizes from the
+ defaults.</para>
+ </listitem>
+ <listitem>
+ <para><literal>jbm.remoting.netty.tcpreceivebuffersize</literal>. This parameter
+ determines the size of the TCP receive buffer in bytes. The default value
+ for this property is <literal>32768</literal> bytes (32KiB).</para>
+ </listitem>
+ </itemizedlist>
+ </section>
+ <section>
+ <title>Configuring Netty SSL</title>
+ <para>Netty SSL is similar to the Netty TCP transport but it provides additional
+ security by encrypting TCP connections using the Secure Sockets Layer SSL</para>
+ <para>Please see the examples for a full working example of using Netty SSL.</para>
+ <para>Netty SSL uses all the same properties as Netty TCP but adds the following
+ additional properties:</para>
+ <itemizedlist>
+ <listitem>
+ <para><literal>jbm.remoting.netty.sslenabled</literal>. Must be <literal
+ >true</literal> to enable SSL.</para>
+ </listitem>
+ <listitem>
+ <para><literal>jbm.remoting.netty.keystorepath</literal>. This is the path to
+ the SSL key store on the client which holds the client certificates.</para>
+ </listitem>
+ <listitem>
+ <para><literal>jbm.remoting.netty.keystorepassword</literal>. This is the
+ password for the client certificate key store on the client.</para>
+ </listitem>
+ <listitem>
+ <para><literal>jbm.remoting.netty.truststorepath</literal>. This is the path to
+ the trusted client certificate store on the server.</para>
+ </listitem>
+ <listitem>
+ <para><literal>jbm.remoting.netty.truststorepassword</literal>. This is the
+ password to the trusted client certificate store on the server.</para>
+ </listitem>
+ </itemizedlist>
+ </section>
+ <section>
+ <title>Configuring Netty HTTP</title>
+ <para>Netty HTTP tunnels packets over the HTTP protocol. It can be useful in scenarios
+ where firewalls only allow HTTP traffice to pass.</para>
+ <para>Please see the examples for a full working example of using Netty HTTP.</para>
+ <para>Netty HTTP uses the same properties as Netty TCP but adds the following additional
+ properties:</para>
+ <itemizedlist>
+ <listitem>
+ <para><literal>jbm.remoting.netty.httpenabled</literal>. Must be <literal
+ >true</literal> to enable HTTP.</para>
+ </listitem>
+ <listitem>
+ <para><literal>jbm.remoting.netty.httpclientidletime</literal>. How long a
+ client can be idle before sending an empty http request to keep the
+ connection alive</para>
+ </listitem>
+ <listitem>
+ <para><literal>jbm.remoting.netty.httpclientidlescanperiod</literal>. How often,
+ in milliseconds, to scan for idle clients</para>
+ </listitem>
+ <listitem>
+ <para><literal>jbm.remoting.netty.httpresponsetime</literal>. How long the
+ server can wait before sending an empty http response to keep the connection
+ alive</para>
+ </listitem>
+ <listitem>
+ <para><literal>jbm.remoting.netty.httpserverscanperiod</literal>. How often, in
+ milliseconds, to scan for clients needing responses</para>
+ </listitem>
+ <listitem>
+ <para><literal>jbm.remoting.netty.httprequiressessionid</literal>. If true the
+ client will wait after the first call to receive a session id. Used the http
+ connector is connecting to servlet acceptor (not recommended) </para>
+ </listitem>
+ </itemizedlist>
+ </section>
+ <section>
+ <title>Configuring Netty Servlet</title>
+ <para>We also provide a Netty servlet transport for use with JBoss Messaging. The
+ servlet transport allows JBoss Messaging traffic to be tunneled over HTTP to a
+ servlet running in a servlet engine which then redirects it to an in-VM JBoss
+ Messaging server.</para>
+ <para>The servlet transport differs from the Netty HTTP transport in that, with the HTTP
+ transport JBoss Messaging effectively acts a web server listening for HTTP traffic
+ on, e.g. port 80 or 8080, whereas with the servlet transport JBM traffic is proxied
+ through a servlet engine which may already be serving web site or other
+ applications. This allows JBoss Messaging to be used where corporate policies may
+ only allow a single web server listening on an HTTP port, and this needs to serve
+ all applications including messaging.</para>
+ <para>Please see the examples for a full working example of the servlet transport being
+ used.</para>
+ <para>To configure a servlet engine to work the Netty Servlet transport we need to do
+ the following things:</para>
+ <itemizedlist>
+ <listitem>
+ <para>Deploy the servlet. Here's an example web.xml describing a web application
+ that uses the servlet:</para>
+ <programlisting><?xml version="1.0" encoding="UTF-8"?>
+<web-app xmlns="http://java.sun.com/xml/ns/j2ee" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+ xsi:schemaLocation="http://java.sun.com/xml/ns/j2ee http://java.sun.com/xml/ns/j2ee/web-app_2_4.xsd"
+ version="2.4">
+ <servlet>
+ <servlet-name>NettyServlet</servlet-name>
+ <servlet-class>org.jboss.netty.channel.socket.http.HttpTunnelingServlet</servlet-class>
+ <init-param>
+ <param-name>endpoint</param-name>
+ <param-value>local:org.jboss.jbm</param-value>
+ </init-param>
+ <load-on-startup>1</load-on-startup>
+ </servlet>
+
+ <servlet-mapping>
+ <servlet-name>NettyServlet</servlet-name>
+ <url-pattern>/JBMServlet</url-pattern>
+ </servlet-mapping>
+</web-app>
+
+</programlisting>
+ </listitem>
+ <listitem>
+ <para>We also need to add a special Netty invm acceptor on the server side
+ configuration.</para>
+ <para>Here's a snippet from the <literal>jbm-configuration.xml</literal> file
+ showing that acceptor being defined:</para>
+ <programlisting>
+<acceptors>
+
+ <acceptor name="netty-invm">
+ <factory-class>
+ org.jboss.messaging.integration.transports.netty.NettyAcceptorFactory
+ </factory-class>
+ <param key="jbm.remoting.netty.useinvm" value="true" type="Boolean"/>
+ <param key="jbm.remoting.netty.host" value="org.jboss.jbm" type="String"/>
+ </acceptor>
+
+</acceptors>
+ </programlisting>
+ </listitem>
+ <listitem>
+ <para>Lastly we need a connector for the client, this again will be configured
+ in the <literal>jbm-configuration.xml</literal> file as such:</para>
+ <programlisting><connectors>
+
+ <connector name="netty-servlet">
+ <factory-class>
+ org.jboss.messaging.integration.transports.netty.NettyConnectorFactory
+ </factory-class>
+ <param key="jbm.remoting.netty.host" value="localhost" type="String"/>
+ <param key="jbm.remoting.netty.port" value="8080" type="Integer"/>
+ <param key="jbm.remoting.netty.useservlet" value="true" type="Boolean"/>
+ <param key="jbm.remoting.netty.servletpath"
+ value="/messaging/JBMServlet" type="String"/>
+ </connector>
+
+ </connectors></programlisting>
+ </listitem>
+ </itemizedlist>
+ <para>Heres a list of the init params and what they are used for</para>
+ <itemizedlist>
+ <listitem>
+ <para>endpoint - This is the name of the netty acceptor that the servlet will
+ forward its packets too. You can see it matches the name of the <literal
+ >jbm.remoting.netty.host</literal> param.</para>
+ </listitem>
+ </itemizedlist>
+ <para>The servlet pattern configured in the <literal>web.xml</literal> is the path of
+ the URL that is used. The connector param <literal
+ >jbm.remoting.netty.servletpath</literal> on the connector config must match
+ this using the application context of the web app if there is one.</para>
+ <para>Its also possible to use the servlet transport over SSL. simply add the following
+ configuration to the
+ connector:<programlisting> <connector name="netty-servlet">
+ <factory-class>org.jboss.messaging.integration.transports.netty.NettyConnectorFactory</factory-class>
+ <param key="jbm.remoting.netty.host" value="localhost" type="String"/>
+ <param key="jbm.remoting.netty.port" value="8443" type="Integer"/>
+ <param key="jbm.remoting.netty.useservlet" value="true" type="Boolean"/>
+ <param key="jbm.remoting.netty.servletpath" value="/messaging/JBMServlet" type="String"/>
+ <param key="jbm.remoting.netty.sslenabled" value="true" type="Boolean"/>
+ <param key="jbm.remoting.netty.keystorepath" value="path to a keystoree" type="String"/>
+ <param key="jbm.remoting.netty.keystorepassword" value="keysore password" type="String"/>
+ </connector>
+</programlisting></para>
+ <para>You will also have to configure the Application server to use a KeyStore. Edit the
+ <literal>server.xml</literal> file that can be found under <literal
+ >server/default/deploy/jbossweb.sar</literal> of the Application Server
+ installation and edit the SSL/TLS connector configuration to look like the
+ following:<programlisting><Connector protocol="HTTP/1.1" SSLEnabled="true"
+ port="8443" address="${jboss.bind.address}"
+ scheme="https" secure="true" clientAuth="false"
+ keystoreFile="path to a keystore"
+ keystorePass="keystore password" sslProtocol = "TLS" />
+
+</programlisting>In
+ both cases you will need to provide a keystore and password. Take a look at the
+ servlet ssl example shipped with JBoss Messaging for more detail.</para>
+ </section>
+ </section>
+
+</chapter>
Added: projects/docs/enterprise/5.0/JBoss_Messaging_2.0.0/JBoss_Messaging_User_Guide/en-US/Connection_TTL.xml
===================================================================
--- projects/docs/enterprise/5.0/JBoss_Messaging_2.0.0/JBoss_Messaging_User_Guide/en-US/Connection_TTL.xml (rev 0)
+++ projects/docs/enterprise/5.0/JBoss_Messaging_2.0.0/JBoss_Messaging_User_Guide/en-US/Connection_TTL.xml 2009-10-05 01:37:17 UTC (rev 94324)
@@ -0,0 +1,188 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<chapter id="connection-ttl">
+ <title>Dead Connections and Session Multiplexing</title>
+ <para>In this section we will discuss connection time-to-live (TTL) and explain how JBoss
+ Messaging deals with crashed clients and clients which have exited without cleanly closing
+ their resources. We'll also discuss how JBoss Messaging multiplexes several sessions on a
+ single connection.</para>
+ <section id="dead.connections">
+ <title>Cleaning up Dead Connection Resources on the Server</title>
+ <para>Before a JBoss Messaging client application exits it is considered good practice that
+ it should close its resources in a controlled manner, using a <literal>finally</literal>
+ block.</para>
+ <para>Here's an example of a well behaved core client application closing its session and
+ session factory in a finally block:</para>
+ <programlisting>
+ClientSessionFactory sf = null;
+ClientSession session = null;
+
+try
+{
+ sf = new ClientSessionFactoryImpl(...);
+
+ session = sf.createSession(...);
+
+ ... do some stuff with the session...
+}
+finally
+{
+ if (session != null)
+ {
+ session.close();
+ }
+
+ if (sf != null)
+ {
+ sf.close();
+ }
+}
+ </programlisting>
+ <para>And here's an example of a well behaved JMS client application:</para>
+ <programlisting>
+Connection jmsConnection = null;
+
+try
+{
+ ConnectionFactory jmsConnectionFactory = new JBossConnectionFactory(...);
+
+ jmsConnection = jmsConnectionFactory.createConnection();
+
+ ... do some stuff with the connection...
+}
+finally
+{
+ if (connection != null)
+ {
+ connection.close();
+ }
+}
+ </programlisting>
+ <para>Unfortunately users don't always write well behaved applications, and sometimes
+ clients just crash so they don't have a chance to clean up their resources!</para>
+ <para>If this occurs then it can leave server side resources, like sessions, hanging on the
+ server. If these were not removed they would cause a resource leak on the server and
+ over time this result in the server running out of memory or other resources.</para>
+ <para>We have to balance the requirement for cleaning up dead client resources with the fact
+ that sometimes the network between the client and the server can fail and then come
+ back, allowing the client to reconnect. JBoss Messaging supports client reconnection, so
+ we don't want to clean up "dead" server side resources too soon or this will prevent any
+ client from reconnecting, as it won't be able to find its old sessions on the
+ server.</para>
+ <para>JBoss Messaging makes all of this configurable. For each <literal
+ >ClientSessionFactory</literal> we define a <emphasis>connection TTL</emphasis>.
+ Basically, the TTL determines how long the server will keep a connection alive in the
+ absence of any data arriving from the client. The client will automatically send "ping"
+ packets periodically to prevent the server from closing it down. If the server doesn't
+ receive any packets on a connection for the connection TTL time, then it will
+ automatically close all the sessions on the server that relate to that
+ connection.</para>
+ <para>If you're using JMS, the connection TTL is defined by the <literal
+ >ConnectionTTL</literal> attribute on a <literal>JBossConnectionFactory</literal>
+ instance, or if you're deploying JMS connection factory instances direct into JNDI on
+ the server side, you can specify it in the xml config, using the parameter <literal
+ >connection-ttl</literal>.</para>
+ <para>The default value for connection ttl is <literal>300000</literal>ms, i.e. 5 minutes. A
+ value of <literal>-1</literal> for <literal>ConnectionTTL</literal> means the server
+ will never time out the connection on the server side.</para>
+ <para>If you do not wish clients to be able to specify their own connection TTL, you can
+ override all values used by a global value set on the server side. This can be done by
+ specifying the <literal>connection-ttl-override</literal> attribute in the server side
+ configuration. The default value for <literal>connection-ttl-override</literal> is
+ <literal>-1</literal> which means "do not override" (i.e. let clients use their own
+ values).</para>
+ <section>
+ <title>Closing core sessions or JMS connections that you have failed to close</title>
+ <para>As previously discussed, it's important that all core client sessions and JMS
+ connections are always closed explicitly in a <literal>finally</literal> block when
+ you are finished using them. </para>
+ <para>If you fail to do so, JBoss Messaging will detect this at garbage collection time,
+ and log a warning similar to the following in the logs (If you are using JMS the
+ warning will involve a JMS connection not a client session):</para>
+ <programlisting>
+
+[Finalizer] 20:14:43,244 WARNING [org.jboss.messaging.core.client.impl.DelegatingSession] I'm closin
+g a ClientSession you left open. Please make sure you close all ClientSessions explicitly before let
+ting them go out of scope!
+[Finalizer] 20:14:43,244 WARNING [org.jboss.messaging.core.client.impl.DelegatingSession] The sessi
+on you didn't close was created here:
+java.lang.Exception
+at org.jboss.messaging.core.client.impl.DelegatingSession.<init>(DelegatingSession.java:83)
+at org.acme.yourproject.YourClass (YourClass.java:666)
+
+ </programlisting>
+ <para>JBoss Messaging will then close the connection / client session for you.</para>
+ <para>Note that the log will also tell you the exact line of your user code where you
+ created the JMS connection / client session that you later did not close. This will
+ enable you to pinpoint the error in your code and correct it appropriately.</para>
+ </section>
+ </section>
+ <section>
+ <title>Detecting failure from the client side.</title>
+ <para>In the previous section we discussed how the client sends pings to the server and how
+ "dead" connection resources are cleaned up by the server. There's also another reason
+ for pinging, and that's for the <emphasis>client</emphasis> to be able to detect that
+ the server or network has failed.</para>
+ <para>As long as the client is receiving data from the server it will consider the
+ connection to be still alive. If the connection is idle the server will periodically
+ send packets to the client to prevent the client from thinking the connection is
+ dead.</para>
+ <para>If the client does not receive any packets for <literal
+ >client-failure-check-period</literal> milliseconds then it will consider the
+ connection failed and will either initiate failover, or call any <literal
+ >FailureListener</literal> instances (or <literal>ExceptionListener</literal>
+ instances if you are using JMS) depending on how it has been configured.</para>
+ <para>If you're using JMS it's defined by the <literal>ClientFailureCheckPeriod</literal>
+ attribute on a <literal>JBossConnectionFactory</literal> instance, or if you're
+ deploying JMS connection factory instances direct into JNDI on the server side, you can
+ specify it in the <literal>jbm-jms.xml </literal> configuration file, using the
+ parameter <literal>client-failure-check-period</literal>.</para>
+ <para>The default value for client failure check period is <literal>5000</literal>ms, i.e. 5
+ seconds. A value of <literal>-1</literal> means the client will never fail the
+ connection on the client side if no data is received from the server. Typically this is
+ much lower than connection TTL to allow clients to reconnect in case of transitory
+ failure.</para>
+ </section>
+ <section id="connection-ttl.async-connection-execution">
+ <title>Configuring Asynchronous Connection Execution</title>
+ <para>By default, as packets are received by on the server side, they are handed off to a
+ thread from the internal thread pool for processing, rather than processing them on the
+ remoting thread.</para>
+ <para>This prevents remoting threads being tied up for too long, especially if the operation
+ takes a significant time to complete. It's dangerous for remoting threads to be tied up
+ for too long, since then they might not be able to handle pings from the client,
+ resulting in reply pings being sent back to the client late and the client erroneously
+ thinking a problem has happened on the connection.</para>
+ <para>Processing operations asynchronously on another thread does however add a little more
+ latency, so we allow this to be configured using the parameter <literal
+ >async-connection-execution-enabled</literal> in <literal
+ >jbm-configuration.xml</literal>. The default value for this parameter is <literal
+ >true</literal>.</para>
+ <para>If you do set this parameter to <literal>false</literal> please do so with
+ caution.</para>
+ </section>
+ <section id="connection-ttl.session.multiplexing">
+ <title>Session Multiplexing</title>
+ <para>Each <literal>ClientSessionFactory</literal> creates connections on demand to the same
+ server as you create sessions. Each instance will create up to a maximum of <literal
+ >maxConnections</literal> connections to the same server. Subsequent sessions will
+ use one of the already created connections in a round-robin fashion.</para>
+ <para>To illustrate this, let's say <literal>maxConnections</literal> is set to <literal
+ >8</literal>. The first eight sessions that you create will have a new underlying
+ connection created for them, the next eight you create will use one of the previously
+ created connections.</para>
+ <para>The default value for <literal>maxConnections</literal> is <literal>8</literal>, if
+ you prefer you can set it to a lower value so each factory maintains only one underlying
+ connection. We choose a default value of <literal>8</literal> because on the server side
+ each packet read from a particular connection is read serially by the same thread, so,
+ if all traffic from the clients sessions is multiplexed on the same connection it will
+ all be processed by the same thread on the server, which might not be a good use of
+ cores on the server. By choosing <literal>8</literal> then different sessions traffic
+ from the same client can be processed by different cores. If you have many different
+ clients then this may not be relevant anyway.</para>
+ <para>To change the value of <literal>maxConnections</literal> simply use the setter method
+ on the <literal>ClientSessionFactory</literal> immediately after constructing it, or if
+ you are using JMS use the setter on the <literal>JBossConnectionFactory</literal> or
+ specify the <literal>max-connections</literal> parameter in the connection factory xml
+ configuration in <literal>jbm-jms.xml</literal>.</para>
+ </section>
+</chapter>
Added: projects/docs/enterprise/5.0/JBoss_Messaging_2.0.0/JBoss_Messaging_User_Guide/en-US/Duplicate_Detection.xml
===================================================================
--- projects/docs/enterprise/5.0/JBoss_Messaging_2.0.0/JBoss_Messaging_User_Guide/en-US/Duplicate_Detection.xml (rev 0)
+++ projects/docs/enterprise/5.0/JBoss_Messaging_2.0.0/JBoss_Messaging_User_Guide/en-US/Duplicate_Detection.xml 2009-10-05 01:37:17 UTC (rev 94324)
@@ -0,0 +1,135 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<chapter id="duplicate-detection">
+ <title>Duplicate Message Detection</title>
+ <para>JBoss Messaging includes powerful automatic duplicate message detection, filtering out
+ duplicate messages without you having to code your own fiddly duplicate detection logic at
+ the application level. This chapter will explain what duplicate detection is, how JBoss
+ Messaging uses it and how and where to configure it.</para>
+ <para>When sending messages from a client to a server, or indeed from a server to another
+ server, if the target server or connection fails sometime after sending the message, but
+ before the sender receives a response that the send (or commit) was processed successfully
+ then the sender cannot know for sure if the message was sent successfully to the
+ address.</para>
+ <para>If the target server or connection failed after the send was received and processed but
+ before the response was sent back then the message will have been sent to the address
+ successfully, but if the target server or connection failed before the send was received and
+ finished processing then it will not have been sent to the address successfully. From the
+ senders point of view it's not possible to distinguish these two cases.</para>
+ <para>When the server recovers this leaves the client in a difficult situation. It knows the
+ target server failed, but it does not know if the last message reached its destination ok.
+ If it decides to resend the last message, then that could result in a duplicate message
+ being sent to the address. If each message was an order or a trade then this could result in
+ the order being fulfilled twice or the trade being double booked. This is clearly not a
+ desirable situation.</para>
+ <para>Sending the message(s) in a transaction does not help out either. If the server or
+ connection fails while the transaction commit is being processed it is also indeterminate
+ whether the transaction was successfully committed or not!</para>
+ <para>To solve these issues JBoss Messaging provides automatic duplicate messages detection for
+ messages sent to addresses.</para>
+ <section>
+ <title>Using Duplicate Detection for Message Sending</title>
+ <para>Enabling duplicate message detection for sent messages is simple: you just need to set
+ a special property on the message to a unique value. You can create the value however
+ you like, as long as it is unique. When the target server receives the message it will
+ check if that property is set, if it is, then it will check in its in memory cache if it
+ has already received a message with that value of the header. If it has received a
+ message with the same value before then it will ignore the message.</para>
+ <note>
+ <para>Using duplicate detection to move messages between nodes can give you the same
+ <emphasis>once and only once</emphasis> delivery guarantees as if you were using
+ an XA transaction to consume messages from source and send them to the target, but
+ with less overhead and much easier configuration than using XA.</para>
+ </note>
+ <para>If you're sending messages in a transaction then you don't have to set the property
+ for <emphasis>every</emphasis> message you send in that transaction, you only need to
+ set it once in the transaction. If the server detects a duplicate message for any
+ message in the transaction, then it will ignore the entire transaction.</para>
+ <para>The name of the property that you set is given by the value of <literal
+ >org.jboss.messaging.core.message.impl.HDR_DUPLICATE_DETECTION_ID</literal>, which
+ is <literal>_JBM_DUPL_ID</literal></para>
+ <para>The value of the property can be of type <literal>byte[]</literal> or <literal
+ >SimpleString</literal> if you're using the core API. If you're using JMS it must be
+ a <literal>String</literal>, and it's valid should be unique. An easy way of generating
+ a unique id is by generating a UUID.</para>
+ <para>Here's an example of setting the property using the core API:</para>
+ <programlisting>
+...
+
+ClientMessage message = session.createClientMessage(true);
+
+SimpleString myUniqueID = "This is my unique id"; // Could use a UUID for this
+
+message.setStringProperty(HDR_DUPLICATE_DETECTION_ID, myUniqueID);
+
+...
+ </programlisting>
+ <para>And here's an example using the JMS API:</para>
+ <programlisting>
+...
+
+Message jmsMessage = session.createMessage();
+
+String myUniqueID = "This is my unique id"; // Could use a UUID for this
+
+message.setStringProperty(HDR_DUPLICATE_DETECTION_ID.toString(), myUniqueID);
+
+...
+ </programlisting>
+ </section>
+ <section id="duplicate.id.cache">
+ <title>Configuring the Duplicate ID Cache</title>
+ <para>The server maintains caches of received values of the <literal
+ >org.jboss.messaging.core.message.impl.HDR_DUPLICATE_DETECTION_ID</literal> property
+ sent to each address. Each address has its own distinct cache.</para>
+ <para>The cache is a circular fixed size cache. If the cache has a maximum size of <literal
+ >n</literal> elements, then the <literal>n + 1</literal>th id stored will overwrite
+ the <literal>0</literal>th element in the cache.</para>
+ <para>The maximum size of the cache is configured by the parameter <literal
+ >id-cache-size</literal> in <literal>jbm-configuration.xml</literal>, the default
+ value is <literal>2000</literal> elements.</para>
+ <para>The caches can also be configured to persist to disk or not. This is configured by the
+ parameter <literal>persist-id-cache</literal>, also in <literal
+ >jbm-configuration.xml</literal>. If this is set to <literal>true</literal> then
+ each id will be persisted to permanent storage as they are received. The default value
+ for this parameter is <literal>true</literal>.</para>
+ <note>
+ <para>When choosing a size of the duplicate id cache be sure to set it to a larger
+ enough size so if you resend messages all the previously sent ones are in the cache
+ not having been overwritten.</para>
+ </note>
+ </section>
+ <section>
+ <title>Duplicate Detection and Bridges</title>
+ <para>Core bridges can configured to automatically add a unique duplicate id value (if there
+ isn't already one in the message) before forwarding the message to it's target. This
+ ensures that if the target server crashes or the connection is interrupted and the
+ bridge resends the message, then if it has already been received by the target server,
+ it will be ignored.</para>
+ <para>To configure a core bridge to add the duplicate id header, simply set the <parameter
+ >use-duplicate-detection</parameter> to <literal>true</literal> when configuring a
+ bridge in <literal>jbm-configuration.xml</literal>.</para>
+ <para>The default value for this parameter is <literal>true</literal>.</para>
+ <para>For more information on core bridges and how to configure them, please see
+ <xref linkend="core-bridges" />.</para>
+ </section>
+ <section>
+ <title>Duplicate Detection and Cluster Connections</title>
+ <para>Cluster connections internally use core bridges to move messages reliable between
+ nodes of the cluster. Consequently they can also be configured to insert the duplicate
+ id header for each message they move using their internal bridges.</para>
+ <para>To configure a cluster connection to add the duplicate id header, simply set the
+ <parameter>use-duplicate-detection</parameter> to <literal>true</literal> when
+ configuring a cluster connection in <literal>jbm-configuration.xml</literal>.</para>
+ <para>The default value for this parameter is <literal>true</literal>.</para>
+ <para>For more information on cluster connections and how to configure them, please see <xref
+ linkend="clusters"/>.</para>
+ </section>
+ <section>
+ <title>Duplicate Detection and Paging</title>
+ <para>JBoss Messaging also uses duplicate detection when paging messages to storage. This is
+ so when a message is depaged from storage and server failure occurs, we do not end up
+ depaging the message more than once which could result in duplicate delivery.</para>
+ <para>For more information on paging and how to configure it, please see <xref
+ linkend="paging" />.</para>
+ </section>
+</chapter>
Added: projects/docs/enterprise/5.0/JBoss_Messaging_2.0.0/JBoss_Messaging_User_Guide/en-US/Embedding_JBM.xml
===================================================================
--- projects/docs/enterprise/5.0/JBoss_Messaging_2.0.0/JBoss_Messaging_User_Guide/en-US/Embedding_JBM.xml (rev 0)
+++ projects/docs/enterprise/5.0/JBoss_Messaging_2.0.0/JBoss_Messaging_User_Guide/en-US/Embedding_JBM.xml 2009-10-05 01:37:17 UTC (rev 94324)
@@ -0,0 +1,176 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<chapter id="embedding-jbm">
+ <title>Embedding JBoss Messaging</title>
+ <para>JBoss Messaging is designed as set of simple Plain Old Java Objects (POJOs). This means
+ JBoss Messaging can be instantiated and run in any dependency injection framework such as
+ JBoss Microcontainer, Spring or Google Guice. It also means that if you have an application
+ that could use messaging functionality internally, then it can <emphasis>directly
+ instantiate</emphasis> JBoss Messaging clients and servers in its own application code
+ to perform that functionality. We call this <emphasis>embedding</emphasis> JBoss
+ Messaging.</para>
+ <para>Examples of applications that might want to do this include any application that needs
+ very high performance, transactional, persistent messaging but doesn't want the hassle of
+ writing it all from scratch.</para>
+ <para>Embedding JBM can be done in very few easy steps. Instantiate the configuration object,
+ instantiate the server, start it, and you have a JBoss Messaging running in your virtual
+ machine. It's as simple and easy as that.</para>
+ <section>
+ <title>POJO instantiation</title>
+ <para>You can follow this step-by-step guide:</para>
+ <para>Create the configuration object - this contains configuration information for a JBoss
+ Messaging server. If you want to configure it from a file on the classpath, use <literal
+ >FileConfigurationImpl</literal></para>
+ <programlisting>import org.jboss.messaging.core.config.Configuration;
+import org.jboss.messaging.core.config.impl.FileConfiguration;
+
+...
+
+
+Configuration config = new FileConfiguration();
+config.setConfigurationUrl(urlToYourconfigfile);
+config.start();</programlisting>
+ <para>If you don't need to support a configuration file, just use <literal
+ >ConfigurationImpl</literal> and change the config parameters accordingly, such as
+ adding acceptors. </para>
+ <para>The acceptors are configured through <literal>ConfigurationImpl</literal>. Just add
+ the <literal>NettyAcceptorFactory</literal> on the transports the same way you would
+ through the main configuration file.</para>
+ <programlisting>import org.jboss.messaging.core.config.Configuration;
+import org.jboss.messaging.core.config.impl.ConfigurationImpl;
+
+...
+
+Configuration config = new ConfigurationImpl();
+HashSet<TransportConfiguration> transports = new HashSet<TransportConfiguration>();
+
+transports.add(new TransportConfiguration(NettyAcceptorFactory.class.getName()));
+transports.add(new TransportConfiguration(InVMAcceptorFactory.class.getName()));
+
+config.setAcceptorConfigurations(transports);</programlisting>
+ <para>You need to instantiate and start JBoss Messaging server. The class <literal
+ >org.jboss.messaging.core.serverMessaging</literal> has a few static methods for
+ creating servers with common configurations.</para>
+ <programlisting>import org.jboss.messaging.core.server.Messaging;
+import org.jboss.messaging.core.server.MessagingServer;
+
+...
+
+MessagingServer server = Messaging.newMessagingServer(config);
+
+server.start();</programlisting>
+ <para>You also have the option of instantiating <literal>MessagingServerImpl</literal>
+ directly:</para>
+ <programlisting>MessagingServer server =
+ new MessagingServerImpl(config);
+server.start();</programlisting>
+ </section>
+ <section>
+ <title>Dependency Frameworks</title>
+ <para>You may also choose to use a dependency injection framework such as <trademark>JBoss
+ Micro Container</trademark> or <trademark>Spring Framework</trademark>.</para>
+ <para>JBoss Messaging standalone uses JBoss Micro Container as the injection framework.
+ <literal>JBMBootstrapServer</literal> and <literal>jbm-jboss-beans.xml</literal>
+ which are part of the JBoss Messaging distribution provide a very complete
+ implementation of what's needed to bootstrap the server using JBoss Micro Container. </para>
+ <para>When using JBoss Micro Container, you need to provide a XML declaring the <literal
+ >MessagingServer</literal> and <literal>Configuration</literal> object, you can also
+ inject a security manager and a MBean server if you want, but those are optional.</para>
+ <para>A very basic XML Bean declaration for the JBoss Micro Container would be:</para>
+ <programlisting><?xml version="1.0" encoding="UTF-8"?>
+
+<deployment xmlns="urn:jboss:bean-deployer:2.0">
+
+ <!-- The core configuration -->
+ <bean name="Configuration"
+ class="org.jboss.messaging.core.config.impl.FileConfiguration">
+ </bean>
+
+ <!-- The core server -->
+ <bean name="MessagingServer"
+ class="org.jboss.messaging.core.server.impl.MessagingServerImpl">
+ <constructor>
+ <parameter>
+ <inject bean="Configuration"/>
+ </parameter>
+ </constructor>
+ </bean>
+ </deployment></programlisting>
+ <para><literal>JBMBootstrapServer</literal> provides an easy encapsulation of JBoss Micro
+ Container.</para>
+ <programlisting>JBMBootstrapServer bootStrap =
+ new JBMBootstrapServer(new String[] {"jbm-jboss-beans.xml"});
+ bootStrap.run();</programlisting>
+ </section>
+ <section>
+ <title>Connecting to the Embedded JBoss Messaging</title>
+ <para>To connect clients to JBoss Messaging you just create the factories as normal:</para>
+ <section>
+ <title>Core API</title>
+ <para>If using the core API, just create the <literal>ClientSessionFactory</literal> and
+ use the regular core API.</para>
+ <programlisting>ClientSessionFactory nettyFactory = new ClientSessionFactoryImpl(
+ new TransportConfiguration(
+ InVMConnectorFactory.class.getName()));
+
+ClientSession session = factory.createSession();
+
+session.createQueue("example", "example", true);
+
+ClientProducer producer = session.createProducer("example");
+
+ClientMessage message = session.createClientMessage(true);
+
+message.getBody().writeString("Hello");
+
+producer.send(message);
+
+session.start();
+
+ClientConsumer consumer = session.createConsumer("example");
+
+ClientMessage msgReceived = consumer.receive();
+
+System.out.println("message = " + msgReceived.getBody().readString());
+
+session.close();</programlisting>
+ </section>
+ <section>
+ <title>JMS API</title>
+ <para>Connection on an Embedded JBoss Messaging through JMS is also simple. Just
+ instantiate <literal>JBossConnectionFactory</literal> directly. The following
+ example illustrates that.</para>
+ <programlisting>JBossConnectionFactory cf =
+ new JBossConnectionFactory(
+ new TransportConfiguration(InVMConnectorFactory.class.getName()));
+
+Connection conn = cf.createConnection();
+
+conn.start();
+
+Session sess = conn.createSession(true, Session.SESSION_TRANSACTED);
+
+MessageProducer prod = sess.createProducer(queue);
+
+TextMessage msg = sess.createTextMessage("Hello!");
+
+prod.send(msg);
+
+sess.commit();
+
+MessageConsumer consumer = sess.createConsumer(queue);
+
+TextMessage txtmsg = (TextMessage)consumer.receive();
+
+System.out.println("Msg = " + txtmsg.getText());
+
+sess.commit();
+
+conn.close();</programlisting>
+ </section>
+ </section>
+ <section>
+ <title>JMS Embedding Example</title>
+ <para>Please see <xref linkend="examples.embedded" /> for an example which shows how
+ to setup and run JBoss Messaging embedded with JMS.</para>
+ </section>
+</chapter>
Added: projects/docs/enterprise/5.0/JBoss_Messaging_2.0.0/JBoss_Messaging_User_Guide/en-US/Examples.xml
===================================================================
--- projects/docs/enterprise/5.0/JBoss_Messaging_2.0.0/JBoss_Messaging_User_Guide/en-US/Examples.xml (rev 0)
+++ projects/docs/enterprise/5.0/JBoss_Messaging_2.0.0/JBoss_Messaging_User_Guide/en-US/Examples.xml 2009-10-05 01:37:17 UTC (rev 94324)
@@ -0,0 +1,514 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<chapter id="examples">
+ <title>Examples</title>
+ <para>The JBoss Messaging distribution comes with a wide variety of run out-of-the-box examples
+ demonstrating many of the features.</para>
+ <para>The examples are available in the distribution, in the <literal>examples</literal>
+ directory. Examples are split into JMS and core examples. JMS examples show how a particular
+ feature can be used by a normal JMS client. Core examples show how the equivalent feature
+ can be used by a core messaging client.</para>
+ <para>A set of Java EE examples are also provided which need the JBoss Application Server
+ installed to be able to run.</para>
+ <section>
+ <title>JMS Examples</title>
+ <para>To run a JMS example, simply <literal>cd</literal> into the appropriate example
+ directory and type <literal>ant</literal>.</para>
+ <para>You will need to have Apache 1.7.0 or later ant installed on your system with the ant
+ <literal>bin</literal> directory on your path.</para>
+ <para>Here's a listing of the examples with a brief description.</para>
+ <section id="application-level-failover">
+ <title>Application-Layer Failover</title>
+ <para>JBoss Messaging implements fully transparent automatic failover of connections
+ from a live to backup node, this requires no special coding for failover, and is
+ described in a different example. Automatic failover requires server
+ replication.</para>
+ <para>However, JBoss Messaging also supports Application-Layer failover, useful in the
+ case that replication is not enabled on the server side.</para>
+ <para>With Application-Layer failover, it's up to the application to register a JMS
+ <literal>ExceptionListener</literal> with JBoss Messaging which will be called
+ by JBoss Messaging in the event that connection failure is detected.</para>
+ <para>The code in the <literal>ExceptionListener</literal> then recreates the JMS
+ connection, session, etc on another node and the application can continue.</para>
+ <para>Application-layer failover is an alternative approach to High Availability (HA).
+ Application-layer failover differs from automatic failover in that some client side
+ coding is required in order to implement this. Also, with Application-layer
+ failover, since the old session object dies and a new one is created, any
+ uncommitted work in the old session will be lost, and any unacknowledged messages
+ might be redelivered.</para>
+ </section>
+ <section id="automatic-failover">
+ <title>Automatic (Transparent) Failover</title>
+ <para>The <literal>automatic-failover</literal> example demonstrates two servers coupled
+ as a live-backup pair for high availability (HA), and a client connection
+ transparently failing over from live to backup when the live server is
+ crashed.</para>
+ <para>JBoss Messaging implements seamless, transparent failover of client connections
+ between live and backup servers. This is implemented by the replication of state
+ between live and backup nodes. When replication is configured and a live node
+ crashes, the client connections can carry on as if nothing happened and carry on
+ sending and consuming messages.</para>
+ </section>
+ <section>
+ <title>Automatic Reconnect</title>
+ <para>The <literal>reconnect-same-node</literal> example demonstrates how JBoss
+ Messaging connections can be configured to be resilient to temporary network
+ failures.</para>
+ <para> In the case of a network failure being detected, either as a result of a failure
+ to read/write to the connection, or the failure of a pong to arrive back from the
+ server in good time after a ping is sent, instead of failing the connection
+ immediately and notifying any user <literal>ExceptionListener</literal> objects,
+ JBoss Messaging can be configured to automatically retry the connection, and
+ reconnect to the server when it becomes available again across the network.</para>
+ </section>
+ <section id="examples.browsers">
+ <title>Browser</title>
+ <para>The <literal>browser</literal> example shows you how to use a JMS <literal
+ >QueueBrowser</literal> with JBoss Messaging.</para>
+ <para>Queues are a standard part of JMS, please consult the JMS 1.1 specification for
+ full details.</para>
+ <para> A <literal>QueueBrowser</literal> is used to look at messages on the queue
+ without removing them. It can scan the entire content of a queue or only messages
+ matching a message selector.</para>
+ </section>
+ <section id="examples.bridge">
+ <title>Core Bridge Example</title>
+ <para>The <literal>bridge</literal> example demonstrates a core bridge deployed on one
+ server, which consumes messages from a local queue and forwards them to an address
+ on a second server.</para>
+ <para>Core bridges are used to create message flows between any two JBoss Messaging
+ servers which are remotely separated. Core bridges are resilient and will cope with
+ temporary connection failure allowing them to be an ideal choice for forwarding over
+ unreliable connections, e.g. a WAN.</para>
+ </section>
+ <section>
+ <title>Client Kickoff</title>
+ <para>The <literal>client-kickoff</literal> example shows how to terminate client
+ connections given an IP address using the JMX management API.</para>
+ </section>
+ <section>
+ <title>Client Side Load-Balancing</title>
+ <para>The <literal>client-side-load-balancing</literal> example demonstrates how
+ subsequent connections created from a JMS <literal>ConnectionFactory</literal> can
+ be created to different nodes of the cluster. In other words it demonstrates how
+ JBoss Messaging does client side load balancing of connections across the
+ cluster.</para>
+ </section>
+ <section>
+ <title>Clustered Queue</title>
+ <para>The <literal>clustered-queue</literal> example demonstrates a JMS queue deployed
+ on two different nodes. The two nodes are configured to form a cluster. We then
+ create a consumer for the queue on each node, and we create a producer on only one
+ of the nodes. We then send some messages via the producer, and we verify that both
+ consumers receive the sent messages in a round-robin fashio.</para>
+ </section>
+ <section>
+ <title>Clustered Standalone</title>
+ <para>The <literal>clustered-standalone</literal> example demonstrates how to configure
+ and starts 3 cluster nodes on the same machine to form a cluster. A subscriber for a
+ JMS topic is created on each node, and we create a producer on only one of the
+ nodes. We then send some messages via the producer, and we verify that the 3
+ subscribers receive all the sent messages.</para>
+ </section>
+ <section>
+ <title>Clustered Topic</title>
+ <para>The <literal>clustered-topic</literal> example demonstrates a JMS topic deployed
+ on two different nodes. The two nodes are configured to form a cluster. We then
+ create a subscriber on the topic on each node, and we create a producer on only one
+ of the nodes. We then send some messages via the producer, and we verify that both
+ subscribers receive all the sent messages.</para>
+ </section>
+ <section id="examples.dead-letter">
+ <title>Dead Letter</title>
+ <para>The <literal>dead-letter</literal> example shows you how to define and deal with
+ dead letter messages. Messages can be delivered unsuccessfully (e.g. if the
+ transacted session used to consume them is rolled back). </para>
+ <para>Such a message goes back to the JMS destination ready to be redelivered. However,
+ this means it is possible for a message to be delivered again and again without any
+ success and remain in the destination, clogging the system.</para>
+ <para>To prevent this, messaging systems define dead letter messages: after a specified
+ unsuccessful delivery attempts, the message is removed from the destination and put
+ instead in a dead letter destination where they can be consumed for further
+ investigation.</para>
+ </section>
+ <section id="examples.delayed-redelivery">
+ <title>Delayed Redelivery</title>
+ <para>The <literal>delayed-redelivery</literal> example demonstrates how JBoss Messaging
+ can be configured to provide a delayed redelivery in the case a message needs to be
+ redelivered.</para>
+ <para>Delaying redelivery can often be useful in the case that clients regularly fail or
+ roll-back. Without a delayed redelivery, the system can get into a "thrashing"
+ state, with delivery being attempted, the client rolling back, and delivery being
+ re-attempted in quick succession, using up valuable CPU and network
+ resources.</para>
+ </section>
+ <section id="divert-example">
+ <title>Divert</title>
+ <para>JBoss Messaging diverts allow messages to be transparently "diverted" from one
+ address to another with just some simple configuration defined on the server
+ side.</para>
+ </section>
+ <section>
+ <title>Durable Subscription</title>
+ <para>The <literal>durable-subscription</literal> example shows you how to use a durable
+ subscription with JBoss Messaging. Durable subscriptions are a standard part of JMS,
+ please consult the JMS 1.1 specification for full details.</para>
+ <para>Unlike non-durable subscriptions, the key function of durable subscriptions is
+ that the messages contained in them persist longer than the lifetime of the
+ subscriber - i.e. they will accumulate messages sent to the topic even if there is
+ no active subscriber on them. They will also survive server restarts. Note that for
+ the messages to be persisted, the messages sent to them must be marked as persistent
+ messages. </para>
+ </section>
+ <section>
+ <title>Embedded</title>
+ <para>The <literal>embedded</literal> example shows how to embed the JBoss Messaging
+ Server within your own code.</para>
+ </section>
+ <section>
+ <title>HTTP Transport</title>
+ <para>The <literal>http-transport</literal> example shows you how to configure JBoss
+ Messaging to use the HTTP protocol as its transport layer.</para>
+ </section>
+ <section>
+ <title>Instantiate JMS Objects Directly</title>
+ <para>Usually, JMS Objects such as <literal>ConnectionFactory</literal>, <literal
+ >Queue</literal> and <literal>Topic</literal> instances are looked up from JNDI
+ before being used by the client code. This objects are called "administered objects"
+ in JMS terminology.</para>
+ <para>However, in some cases a JNDI server may not be available or desired. To come to
+ the rescue JBoss Messaging also supports the direct instantiation of these
+ administered objects on the client side so you don't have to use JNDI for
+ JMS.</para>
+ </section>
+ <section id="examples.interceptor">
+ <title>Interceptor</title>
+ <para>JBoss Messaging allows an application to use an interceptor to hook into the
+ messaging system. Interceptors allow you to handle various message events in JBoss
+ Messaging.</para>
+ </section>
+ <section id="examples.jaas">
+ <title>JAAS</title>
+ <para>The <literal>jaas</literal> example shows you how to configure JBoss Messaging to
+ use JAAS for security. JBoss Messaging can leverage JAAS to delegate user
+ authentication and authorization to existing security infrastructure.</para>
+ </section>
+ <section id="examples.jmx">
+ <title>JMX Management</title>
+ <para>The <literal>jmx</literal> example shows how to manage JBoss Messaging using
+ JMX.</para>
+ </section>
+ <section id="examples.large-message">
+ <title>Large Message</title>
+ <para>The <literal>large-message</literal> example shows you how to send and receive
+ very large messages with JBoss Messaging. JBoss Messaging supports the sending and
+ receiving of huge messages, much larger than can fit in available RAM on the client
+ or server. Effectively the only limit to message size is the amount of disk space
+ you have on the server.</para>
+ <para>Large messages are persisted on the server so they can survive a server restart.
+ In other words JBoss Messaging doesn't just do a simple socket stream from the
+ sender to the consumer.</para>
+ </section>
+ <section id="examples.last-value-queue">
+ <title>Last-Value Queue</title>
+ <para>The <literal>last-value-queue</literal> example shows you how to define and deal
+ with last-value queues. Last-Value queues are special queues which discard any
+ messages when a newer message with the same value for a well-defined last-value
+ property is put in the queue. In other words, a last-value queue only retains the
+ last value.</para>
+ <para>A typical example for last-value queue is for stock prices, where you are only
+ interested by the latest value for a particular stock.</para>
+ </section>
+ <section>
+ <title>Load Balanced Clustered Queue</title>
+ <para>The <literal>clustered-queue</literal> example demonstrates a JMS queue deployed
+ on two different nodes. The two nodes are configured to form a cluster.</para>
+ <para>We then create a consumer on the queue on each node, and we create a producer on
+ only one of the nodes. We then send some messages via the producer, and we verify
+ that both consumers receive the sent messages in a round-robin fashion.</para>
+ <para>In other words, JBoss Messaging load balances the sent messages across all
+ consumers on the cluster</para>
+ </section>
+ <section id="examples.management">
+ <title>Management</title>
+ <para>The <literal>management</literal> example shows how to manage JBoss Messaging
+ using JMS Messages to invoke management operations on the server.</para>
+ </section>
+ <section id="examples.management-notifications">
+ <title>Management Notification</title>
+ <para>The <literal>management-notification</literal> example shows how to receive
+ management notifications from JBoss Messaging using JMS messages. JBoss Messaging
+ servers emit management notifications when events of interest occur (consumers are
+ created or closed, destinations are created or deleted, security authentication
+ fails, etc.).</para>
+ </section>
+ <section id="examples.consumer-rate-limit">
+ <title>Message Consumer Rate Limiting</title>
+ <para>With JBoss Messaging you can specify a maximum consume rate at which a JMS
+ MessageConsumer will consume messages. This can be specified when creating or
+ deploying the connection factory.</para>
+ <para>If this value is specified then JBoss Messaging will ensure that messages are
+ never consumed at a rate higher than the specified rate. This is a form of consumer
+ throttling.</para>
+ </section>
+ <section id="examples.message-counters">
+ <title>Message Counter</title>
+ <para>The <literal>message-counters</literal> example shows you how to use message
+ counters to obtain message information for a JMS queue.</para>
+ </section>
+ <section id="examples.expiry">
+ <title>Message Expiration</title>
+ <para>The <literal>expiry</literal> example shows you how to define and deal with
+ message expiration. Messages can be retained in the messaging system for a limited
+ period of time before being removed. JMS specification states that clients should
+ not receive messages that have been expired (but it does not guarantee this will not
+ happen).</para>
+ <para>JBoss Messaging can assign an expiry destination to a given queue so that when
+ messages are expired, they are removed from the queue and sent to the expiry
+ destination. These "expired" messages can later be consumed from the expiry
+ destination for further inspection.</para>
+ </section>
+ <section id="examples.message-group">
+ <title>Message Group</title>
+ <para>The <literal>message-group</literal> example shows you how to configure and use
+ message groups with JBoss Messaging. Message groups allow you to pin messages so
+ they are only consumed by a single consumer. Message groups are sets of messages
+ that has the following characteristics:</para>
+ <para>
+ <itemizedlist>
+ <listitem>
+ <para>Messages in a message group share the same group id, i.e. they have
+ same JMSXGroupID string property values</para>
+ </listitem>
+ <listitem>
+ <para>The consumer that receives the first message of a group will receive
+ all the messages that belongs to the group</para>
+ </listitem>
+ </itemizedlist>
+ </para>
+ </section>
+ <section id="producer-rate-limiting-example">
+ <title>Message Producer Rate Limiting</title>
+ <para>The <literal>producer-rte-limit</literal> example demonstrates how, with JBoss
+ Messaging, you can specify a maximum send rate at which a JMS message producer will
+ send messages.</para>
+ </section>
+ <section id="examples.message-priority">
+ <title>Message Priority</title>
+ <para>Message Priority carries the delivery preference of messages.</para>
+ <para> It can be retrieved by the message's standard header field 'JMSPriority' as
+ defined in JMS specification version 1.1. </para>
+ <para>The value is of type integer, ranging from 0 (the lowest) to 9 (the highest). When
+ messages are being delivered, their priorities will effect their order of delivery.
+ Messages of higher priorities will likely be delivered before those of lower
+ priorities. </para>
+ <para>Messages of equal priorities are delivered in the natural order of their arrival
+ at their destinations. Please consult the JMS 1.1 specification for full
+ details.</para>
+ </section>
+ <section>
+ <title>Message Redistribution</title>
+ <para>The <literal>queue-message-redistribution</literal> example demonstrates message
+ redistribution between queues with the same name deployed in different nodes of a
+ cluster.</para>
+ </section>
+ <section id="examples.no-consumer-buffering">
+ <title>No Consumer Buffering</title>
+ <para>By default, JBoss Messaging consumers buffer messages from the server in a client
+ side buffer before you actually receive them on the client side. This improves
+ performance since otherwise every time you called receive() or had processed the
+ last message in a <literal>MessageListener onMessage()</literal> method, the JBoss
+ Messaging client would have to go the server to request the next message, which
+ would then get sent to the client side, if one was available.</para>
+ <para>This would involve a network round trip for every message and really reduce
+ performance. Therefore, by default, JBoss Messaging pre-fetches messages into a
+ buffer on each consumer.</para>
+ <para>In some case buffering is not desirable, and JBoss Messaging allows it to be
+ switched off. This example demonstrates that.</para>
+ </section>
+ <section id="examples.paging">
+ <title>Paging</title>
+ <para>The <literal>paging</literal> example shows how JBoss Messaging can support huge
+ queues even when the server is running in limited RAM. It does this by transparently
+ <emphasis>paging</emphasis> messages to disk, and <emphasis>depaging</emphasis>
+ them when they are required.</para>
+ </section>
+ <section id="examples.pre-acknowledge">
+ <title>Pre-Acknowledge</title>
+ <para>Standard JMS supports three acknowledgement modes:<literal>
+ AUTO_ACKNOWLEDGE</literal>, <literal>CLIENT_ACKNOWLEDGE</literal>, and <literal
+ >DUPS_OK_ACKNOWLEDGE</literal>. For a full description on these modes please
+ consult the JMS specification, or any JMS tutorial.</para>
+ <para>All of these standard modes involve sending acknowledgements from the client to
+ the server. However in some cases, you really don't mind losing messages in event of
+ failure, so it would make sense to acknowledge the message on the server before
+ delivering it to the client. This example demonstrates how JBoss Messaging allows
+ this with an extra acknowledgement mode.</para>
+ </section>
+ <section>
+ <title>Queue</title>
+ <para>A simple example demonstrating a JMS queue.</para>
+ </section>
+ <section>
+ <title>Queue Requestor</title>
+ <para>A simple example demonstrating a JMS queue requestor.</para>
+ </section>
+ <section>
+ <title>Queue with Message Selector</title>
+ <para>The <literal>queue-selector</literal> example shows you how to selectively consume
+ messages using message selectors with queue consumers.</para>
+ </section>
+ <section>
+ <title>Request-Response</title>
+ <para>A simple example showing the JMS request-response pattern.</para>
+ </section>
+ <section id="examples.scheduled-message">
+ <title>Scheduled Message</title>
+ <para>The <literal>scheduled-message</literal> example shows you how to send a scheduled
+ message to a JMS Queue with JBoss Messaging. Scheduled messages won't get delivered
+ until a specified time in the future.</para>
+ </section>
+ <section>
+ <title>Security</title>
+ <para>The <literal>security</literal> example shows you how configure and use role based
+ queue security with JBoss Messaging.</para>
+ </section>
+ <section id="asynchronous-send-acknowledgements-example">
+ <title>Send Acknowledgements</title>
+ <para>The <literal>send-acknowledgements</literal> example shows you how to use JBoss
+ Messaging's advanced <emphasis>asynchronous send acknowledgements</emphasis> feature
+ to obtain acknowledgement from the server that sends have been received and
+ processed in a separate stream to the sent messages. </para>
+ </section>
+ <section>
+ <title>Static Message Selector</title>
+ <para>The <literal>static-selector</literal> example shows you how to configure a JBoss
+ Messaging core queue with static message selectors (filters).</para>
+ </section>
+ <section>
+ <title>Static Message Selector Using JMS</title>
+ <para>The <literal>static-selector-jms</literal> example shows you how to configure a
+ JBoss Messaging queue with static message selectors (filters) using JMS.</para>
+ </section>
+ <section>
+ <title>SSL Transport</title>
+ <para>The <literal>ssl-enabled</literal> shows you how to configure SSL with JBoss
+ Messaging to send and receive message.</para>
+ </section>
+ <section>
+ <title>Symmetric Cluster</title>
+ <para>The <literal>symmetric-cluster</literal> example demonstrates a symmetric cluster
+ set-up with JBoss Messaging.</para>
+ <para>JBoss Messaging has extremely flexible clustering which allows you to set-up
+ servers in many different topologies. The most common topology that you'll perhaps
+ be familiar with if you are used to application server clustering is a symmetric
+ cluster.</para>
+ <para>With a symmetric cluster, the cluster is homogeneous, i.e. each node is configured
+ the same as every other node, and every node is connected to every other node in the
+ cluster.</para>
+ </section>
+ <section>
+ <title>Temporary Queue</title>
+ <para>A simple example demonstrating how to use a JMS temporary queue.</para>
+ </section>
+ <section>
+ <title>Topic</title>
+ <para>A simple example demonstrating a JMS topic.</para>
+ </section>
+ <section id="topic-hierarchy-example">
+ <title>Topic Hierarchy</title>
+ <para>JBoss Messaging supports topic hierarchies. With a topic hierarchy you can
+ register a subscriber with a wild-card and that subscriber will receive any messages
+ sent to an address that matches the wild card.</para>
+ </section>
+ <section>
+ <title>Topic Selector 1</title>
+ <para>The <literal>topic-selector-example1</literal> example shows you how to send
+ message to a JMS Topic, and subscribe them using selectors with JBoss
+ Messaging.</para>
+ </section>
+ <section>
+ <title>Topic Selector 2</title>
+ <para>The <literal>topic-selector-example1</literal> example shows you how to
+ selectively consume messages using message selectors with topic consumers.</para>
+ </section>
+ <section>
+ <title>Transactional Session</title>
+ <para>The <literal>transactional</literal> example shows you how to use a transactional
+ Session with JBoss Messaging.</para>
+ </section>
+ <section>
+ <title>XA Heuristic</title>
+ <para>The <literal>xa-heuristic</literal> example shows you how to make an XA heuristic
+ decision through JBoss Messaging Management Interface. A heuristic decision is a
+ unilateral decision to commit or rollback an XA transaction branch after it has been
+ prepared.</para>
+ </section>
+ <section>
+ <title>XA Receive</title>
+ <para>The <literal>xa-receive</literal> example shows you how message receiving behaves
+ in an XA transaction in JBoss Messaging.</para>
+ </section>
+ <section>
+ <title>XA Send</title>
+ <para>The <literal>xa-send</literal> example shows you how message sending behaves in an
+ XA transaction in JBoss Messaging.</para>
+ </section>
+ <section>
+ <title>XA with Transaction Manager</title>
+ <para>The <literal>xa-with-jta</literal> example shows you how to use JTA interfaces to
+ control transactions with JBoss Messaging.</para>
+ </section>
+ </section>
+ <section>
+ <title>Core API Examples</title>
+ <para>To run a core example, simply <literal>cd</literal> into the appropriate example
+ directory and type <literal>ant</literal></para>
+ <section id="examples.embedded">
+ <title>Embedded</title>
+ <para>This example shows how to embed the JBoss Messaging server within your own
+ code.</para>
+ </section>
+ </section>
+ <section>
+ <title>Java EE Examples</title>
+ <para>Most of the Java EE examples can be run the following way. simply cd into the
+ appropriate example directory an type <literal>ant deploy</literal>. This will create a
+ new JBoss AS profile and start the server. When the server is started from a different
+ window type <literal>ant run</literal> to run the example. Some examples require further
+ steps, please refer to the examples documentation for further instructions.</para>
+ <section>
+ <title>EJB/JMS Transaction</title>
+ <para>An example that shows using an EJB and JMS together within a transaction.</para>
+ </section>
+ <section>
+ <title>HAJNDI (High Availability)</title>
+ <para>A simple example demonstrating using JNDI within a cluster.</para>
+ </section>
+ <section>
+ <title>Resource Adapter Configuration</title>
+ <para>This example demonstrates how to configure several properties on the JBoss
+ Messaging JCA resource adaptor.</para>
+ </section>
+ <section id="jms-bridge-example">
+ <title>JMS Bridge</title>
+ <para>An example demonstrating the use of the JBoss Messaging JMS bridge.</para>
+ </section>
+ <section>
+ <title>MDB (Message Driven Bean)</title>
+ <para>A simple example of a message driven bean.</para>
+ </section>
+ <section>
+ <title>Servlet Transport</title>
+ <para>An example of how to use the JBoss Messaging servlet transport.</para>
+ </section>
+ <section>
+ <title>Servlet SSL Transport</title>
+ <para>An example of how to use the JBoss Messaging servlet transport over SSL.</para>
+ </section>
+ <section id="xa-recovery-example">
+ <title>XA Recovery</title>
+ <para>An example of how XA recovery works within the JBoss Application server using
+ JBoss Messaging.</para>
+ </section>
+ </section>
+</chapter>
Added: projects/docs/enterprise/5.0/JBoss_Messaging_2.0.0/JBoss_Messaging_User_Guide/en-US/Filter_Expressions.xml
===================================================================
--- projects/docs/enterprise/5.0/JBoss_Messaging_2.0.0/JBoss_Messaging_User_Guide/en-US/Filter_Expressions.xml (rev 0)
+++ projects/docs/enterprise/5.0/JBoss_Messaging_2.0.0/JBoss_Messaging_User_Guide/en-US/Filter_Expressions.xml 2009-10-05 01:37:17 UTC (rev 94324)
@@ -0,0 +1,63 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<chapter id="filter-expressions">
+ <title>Filter Expressions</title>
+ <para>JBoss Messaging provides a powerful filter language based on a subset of the SQL 92
+ expression syntax.</para>
+ <para>It is the same as the syntax used for JMS selectors, but the predefined identifiers are
+ different. For documentation on JMS selector syntax please the JMS javadoc for <ulink
+ url="http://java.sun.com/javaee/5/docs/api/javax/jms/Message.html"
+ >javax.jms.Message</ulink>.</para>
+ <para>Filter expressions are used in several places in JBossMessaging</para>
+ <itemizedlist>
+ <listitem>
+ <para>Predefined Queues. When pre-defining a queue, either in <literal
+ >jbm-configuration.xml</literal> or <literal>jbm-jms.xml</literal> a filter
+ expression can be defined for a queue. Only messages that match the filter
+ expression will enter the queue.</para>
+ </listitem>
+ <listitem>
+ <para>Core bridges can be defined with an optional filter expression, only matching
+ messages will be bridged (see <xref linkend="core-bridges"/>).</para>
+ </listitem>
+ <listitem>
+ <para>Diverts can be defined with an optional filter expression, only matching messages
+ will be diverted (see <xref linkend="diverts" />).</para>
+ </listitem>
+ <listitem>
+ <para>Filter are also used programmatically when creating consumers, queues and in
+ several places as described in <xref linkend="management"/>.</para>
+ </listitem>
+ </itemizedlist>
+ <para>There are some differences between JMS selector expressions and JBoss Messaging core
+ filter expressions. Whereas JMS selector expressions operate on a JMS message, JBoss
+ Messaging core filter expressions operate on a core message.</para>
+ <para>The following identifiers can be used in a core filter expressions to refer to attributes
+ of the core message in an expression:</para>
+ <itemizedlist>
+ <listitem>
+ <para><literal>JBMPriority</literal>. To refer to the priority of a message. Message
+ priorities are integers with valid values from <literal>0 - 9</literal>. <literal
+ >0</literal> is the lowest priority and <literal>9</literal> is the highest.
+ E.g. <literal>JBMPriority = 3 AND animal = 'aardvark'</literal></para>
+ </listitem>
+ <listitem>
+ <para><literal>JBMExpiration</literal>. To refer to the expiration time of a message.
+ The value is a long integer.</para>
+ </listitem>
+ <listitem>
+ <para><literal>JBMDurable</literal>. To refer to whether a message is durable or not.
+ The value is a string with valid values: <literal>DURABLE</literal> or <literal
+ >NON_DURABLE</literal>.</para>
+ </listitem>
+ <listitem>
+ <para><literal>JBMTimestamp</literal>. The timestamp of when the message was created.
+ The value is a long integer.</para>
+ </listitem>
+ <listitem>
+ <para><literal>JBMSize</literal>. The size of a message in bytes. The value is an
+ integer.</para>
+ </listitem>
+ </itemizedlist>
+ <para>Any other identifiers used in core filter expressions will be assumed to be properties of
+ the message.</para>
+</chapter>
Added: projects/docs/enterprise/5.0/JBoss_Messaging_2.0.0/JBoss_Messaging_User_Guide/en-US/HA_and_Failover.xml
===================================================================
--- projects/docs/enterprise/5.0/JBoss_Messaging_2.0.0/JBoss_Messaging_User_Guide/en-US/HA_and_Failover.xml (rev 0)
+++ projects/docs/enterprise/5.0/JBoss_Messaging_2.0.0/JBoss_Messaging_User_Guide/en-US/HA_and_Failover.xml 2009-10-05 01:37:17 UTC (rev 94324)
@@ -0,0 +1,163 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<chapter id="ha">
+ <title>High Availability and Failover</title>
+ <para>We define high availability as the <emphasis>ability for the system to continue
+ functioning after failure of one or more of the servers</emphasis>. A part of high
+ availability is <emphasis>failover</emphasis> which we define as the <emphasis>ability for
+ client connections to migrate from one server to another in event of server failure so
+ client applications can continue to operate</emphasis>.</para>
+ <para>JBoss Messaging provides high availability by replicating servers in pairs. It also
+ provides both 100% transparent client failover and application-level client failover.</para>
+ <section>
+ <title>Server replication</title>
+ <para>JBoss Messaging allows pairs of servers to be linked together as <emphasis>live -
+ backup</emphasis> pairs. In this release there is a single backup server for each
+ live server. Backup servers are not operational until failover occurs. In later releases
+ we will most likely support replication onto multiple backup servers.</para>
+ <para>When a <emphasis>live - backup</emphasis> pair is configured, JBoss Messaging ensures
+ that the live server state is replicated to the backup server. Replicated state includes
+ session state, and also global state such as the set of queues and addresses on the
+ server. </para>
+ <para>When a client fails over from live to backup server, the backup server will already
+ have the correct global and session state, so the client will be able to resume its
+ session(s) on the backup server as if nothing happened.</para>
+ <para>Replication is performed in an asynchronous fashion between live and backup server.
+ Data is replicated one way in a stream, and responses that the data has reached the
+ backup is returned in another stream. By pipelining replications and responses to
+ replications in separate streams allows replication throughput to be much higher than if
+ we synchronously replicated data and waited for a response serially in an RPC manner
+ before replicating the next piece of data.</para>
+ <section id="configuring.live.backup">
+ <title>Configuring live-backup pairs</title>
+ <para>First, on the live server, in <literal>jbm-configuration.xml</literal> configure
+ the live server with knowledge of its backup server. This is done by specifying a
+ <literal>backup-connector-ref</literal> element. This element references a
+ connector, also specified on the live server which contains knowledge of how to
+ connect to the backup server. Here's a snippet from <literal
+ >jbm-configuration.xml</literal> showing a live server configured with a backup
+ server:</para>
+ <programlisting><backup-connector-ref connector-name="backup-connector"/>
+
+<!-- Connectors -->
+
+<connectors>
+
+ ...
+
+ <!-- This connector specifies how to connect to the backup server -->
+ <connector name="backup-connector">
+ <factory-class>
+ org.jboss.messaging.integration.transports.netty.NettyConnectorFactory
+ </factory-class>
+ <param key="jbm.remoting.netty.port" value="5445" type="Integer"/>
+ </connector>
+
+</connectors></programlisting>
+ <para>Secondly, on the backup server, also in <literal>jbm-configuration.xml</literal> ,
+ the element <literal>backup</literal> must be set to true. I.e. :</para>
+ <programlisting><backup>true</backup>
+</programlisting>
+ </section>
+ <section>
+ <title>Synchronization of live-backup pairs</title>
+ <para>In order for live - backup pairs to operate properly, they must be identical
+ replicas. This means you cannot just use any backup server that's previously been
+ used for other purposes as a backup server, since it will have different data in its
+ persistent storage. If you try to do so you will receive an exception in the logs
+ and the server will fail to start.</para>
+ <para>To create a backup server for a live server that's already been used for other
+ purposes, it's necessary to copy the <literal>data</literal> directory from the live
+ server to the backup server. This means the backup server will have an identical
+ persistent store to the backup server.</para>
+ <para>Similarly when a client fails over from a live server <literal>L</literal> to a
+ backup server <literal>B</literal>, the server <literal>L</literal> becomes invalid
+ since, from that point on, the data on <literal>L</literal> and <literal>B</literal>
+ may diverge. After such a failure, at the next available opportunity the <literal
+ >B</literal> server should be taken down, and its <literal>data</literal>
+ directory copied back to the <literal>L</literal> server. Live and backup servers
+ can then be restarted. In this release of JBoss Messaging we do not provide any
+ automatic facility for re-assigning a backup node with a live node while it is
+ running.</para>
+ <para>For a backup server to function correctly it's also important that it has the same
+ set of bridges, predefined queues, cluster connections, broadcast groups and
+ discovery groups as defined on the live node. The easiest way to ensure this is just
+ to copy the entire server side configuration from live to backup and just make the
+ changes as specified in the previous section. </para>
+ </section>
+ <section id="queue.activation.timeout">
+ <title>Queue activation timeout</title>
+ <para>If a live server fails, as client connections failover from the live node to the
+ backup, they do so at a rate determined by the client, and it might be the case that
+ some client connections never fail over.</para>
+ <para>Different client connections may have different consumers on the same queue(s).
+ The queue on the backup will wait for all its consumers to reattach before
+ activating delivery on itself. If all connections have not reattached with this
+ timeout then the queue will activate regardless.</para>
+ <para>This param is defined in <literal>jbm-configuration.xml</literal> using the
+ setting <literal>queue-activation-timeout</literal>. Its default value is <literal
+ >30000</literal> milliseconds.</para>
+ </section>
+ </section>
+ <section id="ha.client.automatic">
+ <title>Automatic client failover</title>
+ <para>JBoss Messaging clients can be configured with knowledge of live and backup servers,
+ so that in event of connection failure of the client - live server connection, the
+ client will detect this and reconnect its sessions to the backup server. Because of
+ server replication, then backup server will already have those sessions in the same
+ state they were left on the live server and the client will be able to reconnect them
+ and resume them 100% transparently as if nothing happened.</para>
+ <para>For automatic failover JBoss Messaging requires <emphasis>zero</emphasis> coding of
+ special failover code on the client or server. This differs from other messaging systems
+ which intrusively require you to code special failover handling code. JBoss Messaging
+ automatic failover preserves all your normal JMS or core API semantics and allows your
+ client code to continue 100% uninterrupted on event of connection failure and failover
+ from a live to a backup server.</para>
+ <para>JBoss Messaging clients detect connection failure when it has not received packets
+ from the server within the time given by <literal>client-failure-check-period</literal>
+ as explained in section <xref linkend="connection-ttl"/>. If the client does not receive
+ data in good time, it will assume the connection has failed and attempt failover.</para>
+ <para>JBoss Messaging clients can be configured with the list of live-backup server pairs in
+ a number of different ways. They can be configured explicitly or probably the most
+ common way of doing this is to use <emphasis>server discovery</emphasis> for the client
+ to automatically discover the list. For full details on how to configure clients please
+ see <xref linkend="clusters.server-discovery"/>.</para>
+ <para>Sometimes you want a client to failover onto a backup server even if the live server
+ is just cleanly shutdown rather than having crashed or the connection failed. To
+ configure this you can set the property <literal>FailoverOnServerShutdown</literal> to
+ false either on the <literal>JBossConnectionFactory</literal> if you're using JMS or in
+ the <literal>jbm-jms.xml</literal> file when you define the connection factory, or if
+ using core by setting the property directly on the <literal
+ >ClientSessionFactoryImpl</literal> instance after creation. The default value for
+ this property is <literal>false</literal>, this means that by default <emphasis>JBoss
+ Messaging clients will not failover to a backup server if the live server is simply
+ shutdown cleanly.</emphasis></para>
+ <para>For a fully functional example of automatic failover, please see <xref
+ linkend="automatic-failover"/>.</para>
+ </section>
+ <section>
+ <title>Application-level client failover</title>
+ <para>In some cases you may not want automatic client failover, and prefer to handle any
+ connection failure yourself, and code your own manually reconnection logic in your own
+ failure handler. We define this as <emphasis>application-level</emphasis> failover,
+ since the failover is handled at the user application level.</para>
+ <para>If all your clients use application-level failover then you do not need server
+ replication on the server side, and should disabled this. Server replication has some
+ performance overhead and should be disabled if it is not required. To disable server
+ replication simply do not specify a <literal>backup-connector</literal> element for each
+ live server.</para>
+ <para>To implement application-level failover, if you're using JMS then you need to code an
+ <literal>ExceptionListener</literal> class on the JMS connection. The <literal
+ >ExceptionListener</literal> will be called by JBoss Messaging in the event that
+ connection failure is detected. In your <literal>ExceptionListener</literal> you would
+ close your old JMS connections, potentially look up new connection factory instances
+ from JNDI and creating new connections. In this case you may well be using
+ <ulink url="http://www.jboss.org/community/wiki/JBossHAJNDIImpl">HA-JNDI</ulink>
+ to ensure that the new connection factory is looked up from a different
+ server.</para>
+ <para>For a working example of application-level failover, please see <xref
+ linkend="application-level-failover"/>.</para>
+ <para>If you are using the core API, then the procedure is very similar: you would code a
+ <literal>FailureListener</literal> on your core <literal>ClientSession</literal>
+ instances.</para>
+ </section>
+</chapter>
Added: projects/docs/enterprise/5.0/JBoss_Messaging_2.0.0/JBoss_Messaging_User_Guide/en-US/JBoss_Messaging_User_Guide.xml
===================================================================
--- projects/docs/enterprise/5.0/JBoss_Messaging_2.0.0/JBoss_Messaging_User_Guide/en-US/JBoss_Messaging_User_Guide.xml (rev 0)
+++ projects/docs/enterprise/5.0/JBoss_Messaging_2.0.0/JBoss_Messaging_User_Guide/en-US/JBoss_Messaging_User_Guide.xml 2009-10-05 01:37:17 UTC (rev 94324)
@@ -0,0 +1,54 @@
+<?xml version='1.0'?>
+<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [
+]>
+
+<book id="JBoss_Messaging_User_Guide">
+ <xi:include href="Book_Info.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
+ <xi:include href="Preface.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
+ <xi:include href="Messaging_Concepts.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
+ <xi:include href="Architecture.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
+ <xi:include href="Using_the_Server.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
+ <xi:include href="Using_JMS.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
+ <xi:include href="Using_Core.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
+ <xi:include href="JMS_Core_Mapping.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
+ <xi:include href="Client_Classpath.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
+ <xi:include href="Examples.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
+ <xi:include href="Routing_with_Wildcards.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
+ <xi:include href="JMS_Wildcard_Syntax.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
+ <xi:include href="Filter_Expressions.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
+ <xi:include href="Persistence.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
+ <xi:include href="Configuring_the_Transports.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
+ <xi:include href="Connection_TTL.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
+ <xi:include href="Transaction_Configuration.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
+ <xi:include href="Flow_Control.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
+ <xi:include href="Command_Buffering.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
+ <xi:include href="Send_Guarantees.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
+ <xi:include href="Undelivered_Messages.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
+ <xi:include href="Message_Expiry.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
+ <xi:include href="Large_Messages.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
+ <xi:include href="Paging.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
+ <xi:include href="Queue_Attributes.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
+ <xi:include href="Scheduled_Messages.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
+ <xi:include href="Last-Value_Queues.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
+ <xi:include href="Message_Grouping.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
+ <xi:include href="Pre-acknowledge_Mode.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
+ <xi:include href="Management.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
+ <xi:include href="Security.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
+ <xi:include href="AS_Integration.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
+ <xi:include href="Client_Reconnection.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
+ <xi:include href="Message_Flow_Diverts.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
+ <xi:include href="Core_Bridges.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
+ <xi:include href="Duplicate_Detection.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
+ <xi:include href="Clusters.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
+ <xi:include href="HA_and_Failover.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
+ <xi:include href="Libaio.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
+ <xi:include href="Thread_Management.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
+ <xi:include href="Logging.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
+ <xi:include href="Embedding_JBM.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
+ <xi:include href="Intercepting_Operations.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
+ <xi:include href="Performance_Tuning.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
+ <xi:include href="Project_Information.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
+ <xi:include href="Revision_History.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
+ <index />
+</book>
+
Added: projects/docs/enterprise/5.0/JBoss_Messaging_2.0.0/JBoss_Messaging_User_Guide/en-US/JMS_Wildcard_Syntax.xml
===================================================================
--- projects/docs/enterprise/5.0/JBoss_Messaging_2.0.0/JBoss_Messaging_User_Guide/en-US/JMS_Wildcard_Syntax.xml (rev 0)
+++ projects/docs/enterprise/5.0/JBoss_Messaging_2.0.0/JBoss_Messaging_User_Guide/en-US/JMS_Wildcard_Syntax.xml 2009-10-05 01:37:17 UTC (rev 94324)
@@ -0,0 +1,20 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<chapter id="wildcard-syntax">
+ <title>Understanding the JBoss Messaging Wildcard Syntax</title>
+ <para>JBoss Messaging uses a specific syntax for representing wildcards in security settings,
+ address settings and when creating consumers.</para>
+ <para>The syntax is similar to that used by <ulink url="www.amqp.org">AMQP</ulink>.</para>
+ <para>A JBoss Messaging wildcard expression contains words delimited by the character '<literal
+ >.</literal>' (full stop).</para>
+ <para>The special characters '<literal>#</literal>' and '<literal>*</literal>' also have special
+ meaning and can take the place of a word.</para>
+ <para>The character '<literal>#</literal>' means 'match any sequence of zero or more
+ words'.</para>
+ <para>The character '<literal>*</literal>' means 'match a single word'.</para>
+ <para>So the wildcard 'news.europe.#' would match 'news.europe', 'news.europe.sport',
+ 'news.europe.politics', and 'news.europe.politics.regional' but would not match 'news.usa',
+ 'news.usa.sport' nor 'entertainment'.</para>
+ <para>The wildcard 'news.*' would match 'news.europe', but not 'news.europe.sport'.</para>
+ <para>The wildcard 'news.*.sport' would match 'news.europe.sport' and also 'news.usa.sport', but
+ not 'news.europe.politics'.</para>
+</chapter>
Added: projects/docs/enterprise/5.0/JBoss_Messaging_2.0.0/JBoss_Messaging_User_Guide/en-US/Message_Flow_Diverts.xml
===================================================================
--- projects/docs/enterprise/5.0/JBoss_Messaging_2.0.0/JBoss_Messaging_User_Guide/en-US/Message_Flow_Diverts.xml (rev 0)
+++ projects/docs/enterprise/5.0/JBoss_Messaging_2.0.0/JBoss_Messaging_User_Guide/en-US/Message_Flow_Diverts.xml 2009-10-05 01:37:17 UTC (rev 94324)
@@ -0,0 +1,92 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<chapter id="diverts">
+ <title>Diverting and Splitting Message Flows</title>
+ <para>JBoss Messaging allows you to configure objects called <emphasis>diverts</emphasis> with
+ some simple server configuration.</para>
+ <para>Diverts allow you to transparently divert messages routed to one address to some other
+ address, without making any changes to any client application logic.</para>
+ <para>Diverts can be <emphasis>exclusive</emphasis>, meaning that that the message is diverted
+ to the new address, and does not go to the old address at all, or they can be
+ <emphasis>non-exclusive</emphasis> which means the message continues to go the old
+ address, and a <emphasis>copy</emphasis> of it is also sent to the new address.
+ Non-exclusive diverts can therefore be used for <emphasis>splitting</emphasis> message
+ flows, e.g. there may be a requirement to monitor every order sent to an order queue.</para>
+ <para>Diverts can also be configured to have an optional message filter. If specified then only
+ messages that match the filter will be diverted.</para>
+ <para>Diverts can also be configured to apply a <literal>Transformer</literal>. If specified,
+ all diverted messages will have the opportunity of being transformed by the <literal
+ >Transformer</literal>.</para>
+ <para>A divert will only divert a message to an address on the <emphasis>same server</emphasis>,
+ however, if you want to divert to an address on a different server, a common pattern would
+ be to divert to a local store-and-forward queue, then set up a bridge which consumes from
+ that queue and forwards to an address on a different server.</para>
+ <para>Diverts are therefore a very sophisticated concept, which when combined with bridges can
+ be used to create interesting and complex routings. The set of diverts on a server can be
+ thought of as a type of routing table for messages. Combining diverts with bridges allows
+ you to create a distributed network of reliable routing connections between multiple
+ geographically distributed servers, creating your global messaging mesh.</para>
+ <para>Diverts are defined as xml in the <literal>jbm-configuration.xml</literal> file. There can
+ be zero or more diverts in the file.</para>
+ <para>Please see <xref linkend="divert-example" /> for a full working
+ example showing you how to configure and use diverts.</para>
+ <para>Let's take a look at some divert examples:</para>
+ <section>
+ <title>Exclusive Divert</title>
+ <para>Let's take a look at an exclusive divert. An exclusive divert diverts all matching
+ messages that are routed to the old address to the new address. Matching messages do not
+ get routed to the old address.</para>
+ <para>Here's some example xml configuration for an exclusive divert, it's taken from the
+ divert example:</para>
+ <programlisting>
+<divert name="prices-divert">
+ <address>jms.topic.priceUpdates</address>
+ <forwarding-address>jms.queue.priceForwarding</forwarding-address>
+ <filter string="office='New York'"/>
+ <transformer-class-name>
+ org.jboss.jms.example.AddForwardingTimeTransformer
+ </transformer-class-name>
+ <exclusive>true</exclusive>
+</divert>
+ </programlisting>
+ <para>We define a divert called '<literal>prices-divert</literal>' that will divert any
+ messages sent to the address '<literal>jms.topic.priceUpdates</literal>' (this
+ corresponds to any messages sent to a JMS Topic called '<literal
+ >priceUpdates</literal>') to another local address '<literal
+ >jms.queue.priceForwarding</literal>' (this corresponds to a local JMS queue called
+ '<literal>priceForwarding</literal>'</para>
+ <para>We also specify a message filter string so only messages with the message property
+ <literal>office</literal> with value <literal>New York</literal> will get diverted,
+ all other messages will continue to be routed to the normal address. The filter string
+ is optional, if not specified then all messages will be considered matched.</para>
+ <para>In this example a transformer class is specified. Again this is optional, and if
+ specified the transformer will be executed for each matching message. This allows you to
+ change the messages body or properties before it is diverted. In this example the
+ transformer simply adds a header that records the time the divert happened.</para>
+ <para>This example is actually diverting messages to a local store and forward queue, which
+ is configured with a bridge which forwards the message to an address on another JBoss
+ Messaging server. Please see the example for more details.</para>
+ </section>
+ <section>
+ <title>Non-exclusive Divert</title>
+ <para>Now we'll take a look at a non-exclusive divert. Non exclusive diverts are the same as
+ exclusive diverts, but they only forward a <emphasis>copy</emphasis> of the message to
+ the new address. The original message continues to the old address</para>
+ <para>You can therefore think of non-exclusive diverts as <emphasis>splitting</emphasis> a
+ message flow.</para>
+ <para>Non exclusive diverts can be configured in the same was as exclusive diverts with an
+ optional filter and transformer, here's an example non-exclusive divert, again from the
+ divert example:</para>
+ <programlisting>
+<divert name="order-divert">
+ <address>jms.queue.orders</address>
+ <forwarding-address>jms.topic.spyTopic</forwarding-address>
+ <exclusive>false</exclusive>
+</divert>
+ </programlisting>
+ <para>The above divert example takes a copy of every message sent to the address '<literal
+ >jms.queue.orders</literal>' (Which corresponds to a JMS Queue called '<literal
+ >orders</literal>') and sends it to a local address called '<literal
+ >jms.topic.SpyTopic</literal>' (which corresponds to a JMS Topic called '<literal
+ >SpyTopic</literal>').</para>
+ </section>
+</chapter>
Added: projects/docs/enterprise/5.0/JBoss_Messaging_2.0.0/JBoss_Messaging_User_Guide/en-US/Messaging_Concepts.xml
===================================================================
--- projects/docs/enterprise/5.0/JBoss_Messaging_2.0.0/JBoss_Messaging_User_Guide/en-US/Messaging_Concepts.xml (rev 0)
+++ projects/docs/enterprise/5.0/JBoss_Messaging_2.0.0/JBoss_Messaging_User_Guide/en-US/Messaging_Concepts.xml 2009-10-05 01:37:17 UTC (rev 94324)
@@ -0,0 +1,183 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<chapter id="messaging-concepts">
+ <title>Messaging Concepts</title>
+ <para>
+ JBoss Messaging is an asynchronous messaging system in support of Message-Oriented Middleware (MOM). This chapter contains a brief overview of the purpose and function of a message system, and the concepts associated with messaging systems. If you are already familiar with messaging systems, feel free to skip this chapter.
+ </para>
+
+ <section>
+ <title>Messaging Concepts</title>
+ <para>
+ Messaging systems provide a reliable, transactional method of loosely coupling heterogeneous systems. Unlike systems based on a Remote Procedure Call (RPC), messaging systems primarily use an asynchronous message-passing pattern, with no tight relationship between requests and responses. Most messaging systems also support a request-response mode, but this is not a primary feature.
+ </para>
+ <para>
+ A system that is designed to be asynchronous can take advantage of its hardware, minimize the number of threads blocking on input/output operations, and use bandwidth to its full capacity. RPC systems are limited by the network <emphasis>latency</emphasis> (network 'round trip' time); with an asynchronous system, you can pipe message flows in different directions, so that you are limited by network <emphasis>bandwidth</emphasis>, not latency. This lets you create applications with a much higher performance rate.
+ </para>
+ <para>
+ Message senders and consumers in a messaging system work completely independently. This lets you create extremely flexible, loosely-coupled systems.
+ </para>
+ <para>
+ Large enterprises often use messaging systems to implement a message bus to couple heterogeneous systems. Message buses often form the core of an Enterprise Service Bus (ESB). Using a message bus to uncouple disparate systems lets the system easily grow and adapt. It also allows greater flexibility in adding new systems or retiring old ones, since there are no strict dependencies between systems.
+ </para>
+ </section>
+ <section>
+ <title>Messaging styles</title>
+ <para>
+ Messaging systems normally support two styles of asynchronous messaging: <emphasis>message queue</emphasis> messaging (also known as <emphasis>point-to-point</emphasis> messaging), and <emphasis>publish subscribe</emphasis> messaging. The following section summarises the two messaging styles.
+ </para>
+ <section>
+ <title>The Message Queue Pattern</title>
+ <para>
+ When this method is used, a message is send to a queue and then persisted to provide a guarantee of delivery. The messaging system then delivers the message to a consumer. The consumer first processes and then acknowledges the message. Once a message has been acknowledged, it is removed from the queue and is no longer available for subsequent delivery. If the system crashes before the messaging server receives an acknowledgement from the consumer, the message will be available for delivery once the system has recovered.
+ </para>
+ <para>
+ This style of messaging allows many consumers on each queue, but a particular message will only ever be consumed by one queue. <emphasis>Producers</emphasis>, or senders to the queue, are completely separate from <emphasis>consumers</emphasis>, or receivers.
+ </para>
+ <para>
+ One example of the message queue pattern would be a queue of orders in a company's book ordering sytem. Orders can be sent from multiple front-end ordering systems, and each order is represented by a message sent to the order queue. When a message arrives on the queue, it is persisted. (This ensures that order data is not lost if the server crashes.)
+ </para>
+ <para>
+ There are many consumers on the order queue, each representing an instance of an order-processing component. These consumers can be on physically separate machines. The messaging system delivers each message to <emphasis>one</emphasis> order processing component. (An order can be processed by any order processing component, but a single order is processed only once, by one order processor. This ensures that orders are not processed twice.)
+ </para>
+ <para>
+ When an order processor receives a message, it fulfills the order, sends order information to the warehouse system, and then updates the order database with the order details. It then acknowledges the message so that the server knows it can be deleted. Often the send to warehouse, update database, and acknowledgement operations will be completed in a single transaction to ensure ACID (Atomicity, Consistency, Isolation, Durability) properties.
+ </para>
+ </section>
+ <section>
+ <title>The Publish-Subscribe Pattern</title>
+ <para>
+ Publish-subscribe messaging lets multiple producers send messages to a server entity, often called a <emphasis>topic</emphasis>. A topic can hold multiple <emphasis>subscriptions</emphasis>. Each subscription receives a copy of each message sent to the topic, unlike the message queue pattern, where each message is consumed by a single consumer.
+ </para>
+ <para>
+ Subscriptions can be <emphasis>durable</emphasis> — that is, they retain a copy of each message sent to the topic until a subscriber consumes the message.
+ </para>
+ <para>
+ One common example of publish-subscribe messaging would be a news feed. As news articles are created by writers and editors worldwide, they are sent to a news feed topic. Subscribers interested in reading these articles create subscriptions. The messaging system ensures that a copy of each news message is delivered to each subscription.
+ </para>
+ </section>
+ </section>
+ <section>
+ <title>Delivery guarantees</title>
+ <para>
+ <emphasis>Reliable messaging</emphasis> is a key feature of most messaging systems, in which the server guarantees that the message will be delivered once and only once to each consumer of a queue or each durable subscription of a topic, even in the event of system failure. This is crucial for many businesses, so that orders are not lost or fulfilled more than once.
+ </para>
+ <para>
+ If once and only once delivery is not crucial, you can configure the messaging system appropriately to improve performance under more relaxed circumstances.
+ </para>
+ </section>
+ <section>
+ <title>Transactions</title>
+ <para>
+ Messaging systems usually support the sending and acknowledgement of multiple messages in a single local transaction. JBoss Messaging also supports the sending and acknowledgement as a large global transaction using the Java Transaction API.
+ </para>
+ </section>
+ <section>
+ <title>Durability</title>
+ <para>
+ Messages can be durable or non-durable. Durable messages will persist in permanent storage and survive server failure. You might use a durable message to store an order or a trade so that they cannot be lost. Non-durable messages will not survive server failure or restart. You might use non-durable messages to update stock prices, since they are transitory and need not survive server restarts.
+ </para>
+ </section>
+ <section>
+ <title>Messaging APIs and protocols</title>
+ <para>
+ Some messaging systems provide their own proprietary APIs with which the client application can communicate with the messaging system. There are also some standard methods of communicating with messaging systems:
+ </para>
+ <section>
+ <title>Java Message Service (JMS)</title>
+ <para>
+ The Java Message Service (JMS) is part of Sun's Java EE specification. It is a Java API that encapsulates both message queue and publish-subscribe messaging patterns. JMS was created to encapsulate the common functions between the messaging systems available at the time of its creation.
+ </para>
+ <para>
+ JMS is a popular API implemented by most mesaging systems, but is only available to clients running Java.
+ </para>
+ <para>
+ JMS only defines a programmatic API, not a standard wire format. This means that JMS clients and servers from different vendors cannot interoperate when they use the vendor's internal wire protocol.
+ </para>
+ <para>
+ JBoss Messaging provides a fully compliant Java Message Service 1.1 API.
+ </para>
+ </section>
+ <section>
+ <title>System specific APIs</title>
+ <para>
+ Many systems provide their own programmatic API, which is used to interact with the messaging system. This allows complete system functionality to be exposed to the client application. APIs are not usually rich enough to expose the additional features provided by most messaging systems.
+ </para>
+ <para>
+ JBoss Messaging provides its own core client API, which provides clients with access to greater functionality than that available via the JMS API.
+ </para>
+ </section>
+ <section>
+ <title>STOMP</title>
+ <para>
+ STOMP (Streaming Text Oriented Messaging Protocol) is a simple protocol enabling messaging system interoperability. It defines a wire format, so any STOMP client can theoretically work with any messaging system that supports STOMP. STOMP clients are available in many different programming languages.
+ </para>
+ <para>
+ JBoss Messaging can be used by any STOMP client when using the <literal>StompConnect</literal> broker, which translates the STOMP protocol to the JMS API.
+ </para>
+ <!--<para>JBoss Messaging will be shortly implementing the STOMP protocol on the broker, thus avoiding having to use StompConnect.</para>-->
+ </section>
+ <section>
+ <title>AMQP</title>
+ <para><ulink url="http://en.wikipedia.org/wiki/AMQP">AMQP</ulink> is an emerging
+ standard for interoperable messaging. It also defines a wire format, so any AMQP
+ client can work with any messaging system that supports AMQP. AMQP clients are
+ available in many different programming languages.</para>
+ <para>JBoss Messaging will shortly be implementing AMQP.</para>
+ </section>
+ <section>
+ <title>REST</title>
+ <para>
+ A Representational State Transfer (REST) approach to messaging means that messaging resources are manipulated as resources defined by a URI, typically through a simple set of operations on those resources (for example, <literal>PUT</literal>, <literal>POST</literal>, <literal>GET</literal>, etc.). REST approaches often use HTTP as their underlying protocol.
+ </para>
+ <para>
+ The REST approach is advantageous because it is simple, and the internet is already optimally tuned to handle HTTP information.
+ </para>
+ <!--<para>JBoss Messaging will shortly be implementing REST.</para>-->
+ </section>
+ </section>
+ <section>
+ <title>High Availability</title>
+ <para>
+ High Availability (HA) means that the system should remain operational even after one or more servers fails. The degree of support for HA varies between messaging systems.
+ </para>
+ <para>
+ Some messaging systems require you to implement client-side code to reconnect to another server following server failure. JBoss Messaging provides 100% transparent failover — that is, your JBoss Messaging client connections will automatically failover to another server, allowing your client sessions to continue uninterrupted.
+ </para>
+ <para>
+ See <xref linkend="ha" /> for further information about High Availability.
+ </para>
+ </section>
+ <section>
+ <title>Clusters</title>
+ <para>
+ Many messaging servers let you create groups of messaging servers called <emphasis>clusters</emphasis>. Clustering servers spreads the message load over multiple servers, which lets your system scale horizontally.
+ </para>
+ <para>
+ Clustering support varies between messaging systems. JBoss Messaging provides highly-configurable clustering, allowing messages to be intelligently load-balanced between servers in the cluster according to the number of active consumers on each node.
+ </para>
+ <para>
+ JBoss Messaging can automatically redistribute messages between the nodes of a cluster to prevent starvation of any particular node.
+ </para>
+ <para>
+ See <xref linkend="clusters" /> for full details on clustering.
+ </para>
+ </section>
+ <section>
+ <title>Bridges and routing</title>
+ <para>
+ Some messaging systems allow isolated clusters or single nodes to be connected via a <emphasis>bridge</emphasis>, typically over an unreliable connection such as a wide area network (WAN).
+ </para>
+ <para>
+ Bridges consume from a queue on one server and forward messages to other queues on different servers. They handle unreliable connections, automatically reconnecting whenever the connection becomes available.
+ </para>
+ <para>
+ JBoss Messaging bridges can be configured with filter expressions so that only certain messages are forwarded. Messages can also be transformed across a message bridge.
+ </para>
+ <para>
+ JBoss Messaging allows server-side configuration of routing between queues. This lets you set up complex routing networks to forward or copy messages from one destination to another, forming a global network of interconnected brokers.
+ </para>
+ <para>
+ See <xref linkend="core-bridges" /> and <xref linkend="diverts" /> for further information.
+ </para>
+ </section>
+</chapter>
Added: projects/docs/enterprise/5.0/JBoss_Messaging_2.0.0/JBoss_Messaging_User_Guide/en-US/Paging.xml
===================================================================
--- projects/docs/enterprise/5.0/JBoss_Messaging_2.0.0/JBoss_Messaging_User_Guide/en-US/Paging.xml (rev 0)
+++ projects/docs/enterprise/5.0/JBoss_Messaging_2.0.0/JBoss_Messaging_User_Guide/en-US/Paging.xml 2009-10-05 01:37:17 UTC (rev 94324)
@@ -0,0 +1,148 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<chapter id="paging">
+ <title>Paging</title>
+ <para>JBoss Messaging transparently supports huge queues containing millions of messages while
+ the server is running with limited memory.</para>
+ <para>In such a situation it's not possible to store all of the queues in memory at any one
+ time, so JBoss Messaging transparently <emphasis>pages</emphasis> messages into and out of
+ memory as they are needed, thus allowing massive queues with a low memory footprint.</para>
+ <para>JBoss Messaging will start paging messages to disk, when either the size of the queue
+ reaches a total configured maximum size.</para>
+ <section>
+ <title>Page Files</title>
+ <para>Messages are stored per address on the file system. Each address has an individual
+ folder where messages are stored in multiple files (page files). Each file will contain
+ messages up to a max configured size (<literal>page-size-bytes</literal>). When reading
+ page-files all messages on the page-file are read, routed and the file is deleted as
+ soon as the messages are recovered.</para>
+ </section>
+ <section id="paging.main.config">
+ <title>Configuration</title>
+ <para>You can configure the location of the paging folder</para>
+ <para>Global paging parameters are specified on the main configuration file (<literal
+ >jbm-configuration.xml</literal>).</para>
+ <programlisting><configuration xmlns="urn:jboss:messaging"
+ xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+ xsi:schemaLocation="urn:jboss:messaging /schema/jbm-configuration.xsd">
+
+ ...
+
+ <paging-directory>/somewhere/paging-directory</paging-directory>
+
+ ... </programlisting>
+ <para>
+ <table frame="topbot">
+ <title>Paging Configuration Parameters</title>
+ <tgroup cols="3">
+ <colspec colname="c1" colnum="1"/>
+ <colspec colname="c2" colnum="2"/>
+ <colspec colname="c3" colnum="3"/>
+ <thead>
+ <row>
+ <entry>Property Name</entry>
+ <entry>Description</entry>
+ <entry>Default</entry>
+ </row>
+ </thead>
+ <tbody>
+ <row>
+ <entry><literal>paging-directory</literal></entry>
+ <entry>Where page files are stored. JBoss Messaging will create one
+ folder for each address being paged under this configured
+ location.</entry>
+ <entry>data/paging</entry>
+ </row>
+ </tbody>
+ </tgroup>
+ </table>
+ </para>
+ </section>
+ <section id="paging.mode">
+ <title>Paging Mode</title>
+ <para>As soon as messages delivered to an address exceed the configured size, that address
+ alone goes into page mode.</para>
+ <section>
+ <title>Configuration</title>
+ <para>Configuration is done at the address settings, done at the main configuration file
+ (<literal>jbm-configuration.xml</literal>).</para>
+ <programlisting> <address-settings>
+ <address-setting match="jms.someaddress">
+ <max-size-bytes>104857600</max-size-bytes>
+ <page-size-bytes>10485760</page-size-bytes>
+ <drop-messages-when-full>false</drop-messages-when-full>
+ </address-setting>
+ </address-settings>
+ </programlisting>
+ <para>This is the list of available parameters on the address settings.</para>
+ <para>
+ <table frame="topbot">
+ <title>Paging Address Settings</title>
+ <tgroup cols="3">
+ <colspec colname="c1" colnum="1"/>
+ <colspec colname="c2" colnum="2"/>
+ <colspec colname="c3" colnum="3"/>
+ <thead>
+ <row>
+ <entry>Property Name</entry>
+ <entry>Description</entry>
+ <entry>Default</entry>
+ </row>
+ </thead>
+ <tbody>
+ <row>
+ <entry><literal>max-size-bytes</literal></entry>
+ <entry>What's the max memory the address could have before entering
+ on page mode.</entry>
+ <entry>-1 (disabled)</entry>
+ </row>
+ <row>
+ <entry><literal>page-size-bytes</literal></entry>
+ <entry>The size of each page file used on the paging system</entry>
+ <entry>10MiB (10 * 1024 * 1024 bytes)</entry>
+ </row>
+ <row>
+ <entry><literal>drop-messages-when-full</literal></entry>
+ <entry>if true, messages are dropped instead of paged when <literal
+ >used-memory</literal> is greater than <literal
+ >max-size</literal></entry>
+ <entry>false</entry>
+ </row>
+ </tbody>
+ </tgroup>
+ </table>
+ </para>
+ </section>
+ </section>
+ <section>
+ <title>Caution with Addresses with Multiple Queues</title>
+ <para>When a message is routed to an address that has multiple queues bound to it, e.g. a
+ JMS subscription, there is only 1 copy of the message in memory. Each queue only deals
+ with a reference to this. Because of this the memory is only freed up once all queues
+ referencing the message have delivered it. This means that if not all queues deliver the
+ message we can end up in a state where messages are not delivered. </para>
+ <para>For example:</para>
+ <itemizedlist>
+ <listitem>
+ <para>An address has 10 queues </para>
+ </listitem>
+ <listitem>
+ <para>One of the queues does not deliver its messages (maybe because of a slow
+ consumer).</para>
+ </listitem>
+ <listitem>
+ <para>Messages continually arrive at the address and paging is started.</para>
+ </listitem>
+ <listitem>
+ <para>The other 9 queues are empty even though messages have been sent.</para>
+ </listitem>
+ </itemizedlist>
+ <para>In this example we have to wait until the last queue has delivered some of its
+ messages before we depage and the other queues finally receive some more
+ messages.</para>
+ </section>
+ <section>
+ <title>Example</title>
+ <para>See <xref linkend="examples.paging"/> for an example which shows how to use paging
+ with JBoss Messaging.</para>
+ </section>
+</chapter>
Added: projects/docs/enterprise/5.0/JBoss_Messaging_2.0.0/JBoss_Messaging_User_Guide/en-US/Performance_Tuning.xml
===================================================================
--- projects/docs/enterprise/5.0/JBoss_Messaging_2.0.0/JBoss_Messaging_User_Guide/en-US/Performance_Tuning.xml (rev 0)
+++ projects/docs/enterprise/5.0/JBoss_Messaging_2.0.0/JBoss_Messaging_User_Guide/en-US/Performance_Tuning.xml 2009-10-05 01:37:17 UTC (rev 94324)
@@ -0,0 +1,233 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<chapter id="perf-tuning">
+ <title>Performance Tuning</title>
+ <para>In this chapter we'll discuss how to tune JBoss Messaging for optimum performance.</para>
+ <section>
+ <title>Tuning the journal</title>
+ <itemizedlist>
+ <listitem>
+ <para>Minimum number of journal files. Set <literal>journal-min-files</literal> to a
+ number of files that would fit your average sustainable rate. If you see new
+ files being created on the journal data directory too often, i.e. lots of data
+ is being persisted, you need to increase the minimal number of files, this way
+ the journal would reuse more files instead of creating new data files.</para>
+ </listitem>
+ <listitem>
+ <para>Journal file size. The journal file size should be aligned to the capacity of
+ a cylinder on the disk. The default value 10MiB should be enough on most
+ systems.</para>
+ </listitem>
+ <listitem>
+ <para>Use AIO journal. If using Linux, try to keep your journal type as AIO.</para>
+ </listitem>
+ <listitem>
+ <para><literal>journal-aio-flush-on-sync</literal>. If you don't have many producers
+ in your system you may consider setting journal-aio-flush-on-sync to true. JBoss
+ Messaging by default is optimized by the case where you have many producers. We
+ try to combine multiple writes in a single OS operation. However if that's not
+ your case setting this option to true will give you a performance boost.</para>
+ <para>On the other hand when you have multiple producers, keeping <literal
+ >journal-aio-flush-on-sync</literal> set to false. This will make your
+ system flush multiple syncs in a single OS call making your system scale much
+ better.</para>
+ </listitem>
+ </itemizedlist>
+ </section>
+ <section>
+ <title>Tuning JMS</title>
+ <para>There are a few areas where some tweaks can be done if you are using the JMS
+ API</para>
+ <itemizedlist>
+ <listitem>
+ <para>Disable message id. Use the <literal>setDisableMessageID()</literal> method on
+ the <literal>MessageProducer</literal> class to disable message ids if you don't
+ need them. This decreases the size of the message and also avoids the overhead
+ of creating a unique ID.</para>
+ </listitem>
+ <listitem>
+ <para> Disable message timestamp. Use the <literal
+ >setDisableMessageTimeStamp()</literal> method on the <literal
+ >MessageProducer</literal> class to disable message timestamps if you don't
+ need them. Again this makes the message smaller.</para>
+ </listitem>
+ <listitem>
+ <para>Avoid <literal>ObjectMessage</literal>. <literal>ObjectMessage</literal> is
+ convenient but it comes at a cost. The body of a <literal
+ >ObjectMessage</literal> uses Java serialization to serialize it to bytes.
+ The Java serialized form of even small objects is very verbose so takes up a lot
+ of space on the wire, also Java serialization is slow compared to customer
+ marshalling techniques. Only use <literal>ObjectMessage</literal> if you really
+ can't use one of the other message types, i.e. if you really don't know the type
+ of the payload until run-time.</para>
+ </listitem>
+ <listitem>
+ <para>Avoid <literal>AUTO_ACKNOWLEDGE</literal>. <literal>AUTO_ACKNOWLEDGE</literal>
+ mode requires an acknowledgement to be sent from the server for each message
+ received on the client, this means more traffic on the network. If you can, use
+ <literal>DUPS_OK_ACKNOWLEDGE</literal> or use <literal
+ >CLIENT_ACKNOWLEDGE</literal> or a transacted session and batch up many
+ acknowledgements with one acknowledge/commit.</para>
+ </listitem>
+ <listitem>
+ <para>Avoid persistent messages. By default JMS messages are persistent. If you
+ don't really need persistent messages then set them to be non persistent.
+ Persistent messages incur a lot more overhead in persisting them to
+ storage.</para>
+ </listitem>
+ </itemizedlist>
+ </section>
+ <section>
+ <title>Other Tunings</title>
+ <para>There are various other places in JBoss Messaging where we can perform some
+ tuning:</para>
+ <itemizedlist>
+ <listitem>
+ <para>Use Asynchronous Send Acknowledgements. If you need to send persistent
+ messages non transactionally and you need a guarantee that they have reached the
+ server by the time the call to send() returns, don't set persistent messages to
+ be sent blocking, instead use asynchronous send acknowledgements to get your
+ acknowledgements of send back in a separate stream, see <xref
+ linkend="send-guarantees"/> for more information on this.</para>
+ </listitem>
+ <listitem>
+ <para>Use pre-acknowledge mode. With pre-acknowledge mode, messages are acknowledged
+ <literal>before</literal> they are sent to the client. This reduces the
+ amount of acknowledgment traffic on the wire. For more information on this, see
+ <xref linkend="pre-acknowledge"/>.</para>
+ </listitem>
+ <listitem>
+ <para>Disable security. You may get a small performance boost by disabling security
+ by setting the <literal>security-enabled</literal> parameter to <literal
+ >false</literal> in <literal>jbm-configuration.xml</literal>.</para>
+ </listitem>
+ <listitem>
+ <para>Disable persistence. If you don't need message persistence, turn it off
+ altogether by setting <literal>persistence-enabled</literal> to false in
+ <literal>jbm-configuration.xml</literal>.</para>
+ </listitem>
+ <listitem>
+ <para>Sync transactions lazily. Setting <literal
+ >journal-sync-transactional</literal> to <literal>false</literal> in
+ <literal>jbm-configuration.xml</literal> can give you better transactional
+ persistent performance at the expense of some possibility of loss of
+ transactions on failure. See <xref linkend="send-guarantees"/> for more
+ information.</para>
+ </listitem>
+ <listitem>
+ <para>Use the core API not JMS. Using the JMS API you will have slightly lower
+ performance than using the core API, since all JMS operations need to be
+ translated into core operations before the server can handle them.</para>
+ </listitem>
+ </itemizedlist>
+ </section>
+ <section>
+ <title>Tuning Transport Settings</title>
+ <itemizedlist>
+ <listitem>
+ <para>Enable <ulink url="http://en.wikipedia.org/wiki/Nagle's_algorithm">Nagle's
+ algorithm</ulink>. If you are sending many small messages, such that more
+ than one can fit in a single IP packet thus providing better performance. This
+ is done by setting <literal>jbm.remoting.netty.tcpnodelay</literal> to false
+ with the Netty transports. See <xref linkend="configuring-transports"/> for more
+ information on this. </para>
+ </listitem>
+ <listitem>
+ <para>TCP buffer sizes. If you have a fast network and fast machines you may get a
+ performance boost by increasing the TCP send and receive buffer sizes. See the
+ <xref linkend="configuring-transports"/> for more information on this.
+ </para>
+ </listitem>
+ <listitem>
+ <para>Increase limit on file handles on the server. If you expect a lot of
+ concurrent connections on your servers, or if clients are rapidly opening and
+ closing connections, you should make sure the user running the server has
+ permission to create sufficient file handles.</para>
+ <para>This varies from operating system to operating system. On Linux systems you
+ can increase the number of allowable open file handles in the file <literal
+ >/etc/security/limits.conf</literal> e.g. add the lines
+ <programlisting>
+serveruser soft nofile 20000
+serveruser hard nofile 20000
+ </programlisting>
+ This would allow up to 20000 file handles to be open by the user <literal
+ >serveruser</literal>. </para>
+ </listitem>
+ </itemizedlist>
+ </section>
+ <section>
+ <title>Tuning the VM</title>
+ <para>We highly recommend you use the latest Java 6 JVM, especially in the area of
+ networking many improvements have been made since Java 5. We test internally using the
+ Sun JVM, so some of these tunings won't apply to JDKs from other providers (e.g. IBM or
+ JRockit)</para>
+ <itemizedlist>
+ <listitem>
+ <para>Garbage collection. For smooth server operation we recommend using a parallel
+ garbage collection algorithm, e.g. using the JVM argument <literal
+ >-XX:+UseParallelGC</literal> on Sun JDKs.</para>
+ </listitem>
+ <listitem>
+ <para>Memory settings. Give as much memory as you can to the server. JBoss Messaging
+ can run in low memory by using paging (described in <xref linkend="paging"/>)
+ but if it can run with all queues in RAM this will improve performance. The
+ amount of memory you require will depend on the size and number of your queues
+ and the size and number of your messages. Use the JVM arguments <literal
+ >-Xms</literal> and <literal>-Xmx</literal> to set server available RAM. We
+ recommend setting them to the same high value.</para>
+ </listitem>
+ <listitem>
+ <para>Aggressive options. Different JVMs provide different sets of JVM tuning
+ parameters, for the Sun Hotspot JVM the full list of options is available <ulink
+ url="http://java.sun.com/javase/technologies/hotspot/vmoptions.jsp"
+ >here</ulink>. We recommend at least using <literal
+ >-XX:+AggressiveOpts</literal> and<literal>
+ -XX:+UseFastAccessorMethods</literal>. You may get some mileage with the
+ other tuning parameters depending on your OS platform and application usage
+ patterns.</para>
+ </listitem>
+ </itemizedlist>
+ </section>
+ <section>
+ <title>Avoiding Anti-Patterns</title>
+ <itemizedlist>
+ <listitem>
+ <para>Re-use connections / sessions / consumers / producers. Probably the most
+ common messaging anti-pattern we see is users who create a new
+ connection/session/producer for every message they send or every message they
+ consume. This is a poor use of resources. These objects take time to create and
+ may involve several network round trips. Always re-use them.</para>
+ <note>
+ <para>Some popular libraries such as the Spring JMS Template are known to use
+ these anti-patterns. If you're using Spring JMS Template and you're getting
+ poor performance you know why. Don't blame JBoss Messaging!</para>
+ </note>
+ </listitem>
+ <listitem>
+ <para>Avoid fat messages. Verbose formats such as XML take up a lot of space on the
+ wire and performance will suffer as result. Avoid XML in message bodies if you
+ can.</para>
+ </listitem>
+ <listitem>
+ <para>Avoid many selectors on a queue. Another common anti-pattern is a single queue
+ which has many consumers, each one with a distinct message selector. As messages
+ come into the queue they will typically only match one of the consumers. This
+ does not normally give good performance since as new consumers are added the
+ entire queue has to be scanned for matching messages.</para>
+ <para>This anti-pattern can normally be avoided by instead using a topic with many
+ durable subscriptions, each subscription defines a message selector. With topic
+ subscriptions the selector expression is evaluated by JBoss Messaging before the
+ message goes into the subscription, so no scanning is involved.</para>
+ </listitem>
+ <listitem>
+ <para>Don't create temporary queues for each request. This common anti-pattern
+ involves the temporary queue request-response pattern. With the temporary queue
+ request-response pattern a message is sent to a target and a reply-to header is
+ set with the address of a local temporary queue. When the recipient receives the
+ message they process it then send back a response to the address specified in
+ the reply-to. A common mistake made with this pattern is to create a new
+ temporary queue on each message sent. This will drastically reduce performance.
+ Instead the temporary queue should be re-used for many requests.</para>
+ </listitem>
+ </itemizedlist>
+ </section>
+</chapter>
Added: projects/docs/enterprise/5.0/JBoss_Messaging_2.0.0/JBoss_Messaging_User_Guide/en-US/Persistence.xml
===================================================================
--- projects/docs/enterprise/5.0/JBoss_Messaging_2.0.0/JBoss_Messaging_User_Guide/en-US/Persistence.xml (rev 0)
+++ projects/docs/enterprise/5.0/JBoss_Messaging_2.0.0/JBoss_Messaging_User_Guide/en-US/Persistence.xml 2009-10-05 01:37:17 UTC (rev 94324)
@@ -0,0 +1,250 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<chapter id="persistence">
+ <title>Persistence</title>
+ <para>In this chapter we will describe how persistence works with JBoss Messaging and how to
+ configure it.</para>
+ <para>JBoss Messaging ships with a high performance journal. This journal has been implemented
+ by the JBoss Messaging team with a view to providing high performance in a messaging system.
+ Since JBoss Messaging handles its own persistence, rather than relying on a database or
+ other 3rd party persistence engine, we have been able to tune the journal to gain optimal
+ performance for the persistence of messages and transactions.</para>
+ <para>A JBoss Messaging journal is an <emphasis>append only</emphasis> journal. It consists of a
+ set of files on disk. Each file is pre-created to a fixed size and initially filled with
+ padding. As operations are performed on the server, e.g. add message, update message, delete
+ message, records are appended to the journal. When one journal file is full we move to the
+ next one.</para>
+ <para>Because records are only appended, i.e. added to the end of the journal we minimise disk
+ head movement, i.e. we minimise random access operations.</para>
+ <para>Making the file size configurable means that an optimal size can be chosen, i.e. making
+ each file fit on a disk cylinder. Modern disk topologies are complex and we are not in
+ control over which cylinder(s) the file is mapped onto so this is not an exact science. But
+ by minimising the number of disk cylinders the file is using, we can minimise the amount of
+ disk head movement, since an entire disk cylinder is accessible simply by the disk rotating
+ - the head does not have to move.</para>
+ <para>As delete records are added to the journal, JBoss Messaging has a sophisticated file
+ garbage collection algorithm which can determine if a particular journal file is needed any
+ more - i.e. has all it's data been deleted in the same or other files. If so, the file can
+ be reclaimed and re-used. </para>
+ <para>JBoss Messaging also has a compaction algorithm which removes dead space from the journal
+ and compresses up the data so it takes up less files on disk.</para>
+ <para>The journal also fully supports transactional operation if required, supporting both local
+ and XA transactions.</para>
+ <para>The majority of the journal is written in Java, however we abstract out the interaction
+ with the actual file system to allow different pluggable implementations. We ship JBoss
+ Messaging with two implementations:</para>
+ <itemizedlist>
+ <listitem>
+ <para>Java <ulink url="http://en.wikipedia.org/wiki/New_I/O">NIO</ulink>.</para>
+ <para>The first implementation uses standard Java NIO to interface with the file system.
+ This provides very good performance and runs on any platform where there's a
+ JDK.</para>
+ </listitem>
+ <listitem id="aio-journal">
+ <para>Linux Asynchronous IO</para>
+ <para>The second implementation uses a thin native code wrapper to talk to the Linux
+ asynchronous IO library (AIO). In a highly concurrent environment, AIO can provide
+ better overall persistent throughput since it does not require each individual
+ transaction boundary to be synced to disk. Most disks can only support a limited
+ number of syncs per second, so a syncing approach does not scale well when the
+ number of concurrent transactions needed to be committed grows too large. With AIO,
+ JBoss Messaging will be called back when the data has made it to disk, allowing us
+ to avoid explicit syncs altogether and simply send back confirmation of completion
+ when AIO informs us that the data has been persisted.</para>
+ <para>The AIO journal is only available when running Linux kernel 2.6 or later and after
+ having installed libaio (if it's not already installed). For instructions on how to
+ install libaio please see <xref linkend="installing-aio"/>.</para>
+ <para>For more information on libaio please see <xref linkend="libaio"/>.</para>
+ <para>libaio is part of the kernel project.</para>
+ </listitem>
+ </itemizedlist>
+ <para>The standard JBoss Messaging core server uses two instances of the journal:</para>
+ <itemizedlist>
+ <listitem>
+ <para>Bindings journal.</para>
+ <para>This journal is used to store bindings related data. That includes the set of
+ queues that are deployed on the server and their attributes. It also stores data
+ such as id sequence counters. </para>
+ <para>The bindings journal is always a NIO journal as it is typically low throughput
+ compared to the message journal.</para>
+ </listitem>
+ <listitem>
+ <para>Message journal.</para>
+ <para>This journal instance stores all message related data, including the message
+ themselves and also duplicate id caches.</para>
+ <para>By default JBoss Messaging will try and use an AIO journal. If AIO is not
+ available, e.g. the platform is not Linux with the correct kernel version or AIO has
+ not been installed then it will automatically fall back to using Java NIO which is
+ available on any Java platform.</para>
+ </listitem>
+ </itemizedlist>
+ <para>For large messages, JBoss Messaging persists them outside the message journal. This is
+ discussed in <xref linkend="large-messages"/>.</para>
+ <para>JBoss Messaging also pages messages to disk in low memory situations. This is discussed in
+ <xref linkend="paging"/>.</para>
+ <para>If no persistence is required at all, JBoss Messaging can also be configured not to
+ persist any data at all to storage as discussed in <xref linkend="persistence.enabled"
+ />.</para>
+ <section id="configuring.bindings.journal">
+ <title>Configuring the bindings journal</title>
+ <para>The bindings journal is configured using the following attributes in <literal
+ >jbm-configuration.xml</literal></para>
+ <itemizedlist>
+ <listitem>
+ <para><literal>bindings-directory</literal></para>
+ <para>This is the directory in which the bindings journal lives. The default value
+ is <literal>data/bindings</literal>.</para>
+ </listitem>
+ <listitem>
+ <para><literal>create-bindings-dir</literal></para>
+ <para>If this is set to <literal>true</literal> then the bindings directory will be
+ automatically created at the location specified in <literal
+ >bindings-directory</literal> if it does not already exist. The default
+ value is <literal>true</literal></para>
+ </listitem>
+ </itemizedlist>
+ </section>
+ <section id="configuring.message.journal">
+ <title>Configuring the message journal</title>
+ <para>The message journal is configured using the following attributes in <literal
+ >jbm-configuration.xml</literal></para>
+ <itemizedlist>
+ <listitem id="configuring.message.journal.journal-directory">
+ <para><literal>journal-directory</literal></para>
+ <para>This is the directory in which the message journal lives. The default value is
+ <literal>data/journal</literal>.</para>
+ <para>For the best performance, we recommend the journal is located on its own
+ physical volume in order to minimise disk head movement. If the journal is on a
+ volume which is shared with other processes which might be writing other files
+ (e.g. bindings journal, database, or transaction coordinator) then the disk head
+ may well be moving rapidly between these files as it writes them, thus reducing
+ performance.</para>
+ <para>When the message journal is stored on a SAN we recommend each journal instance
+ that is stored on the SAN is given its own LUN (logical unit).</para>
+ </listitem>
+ <listitem id="configuring.message.journal.create-journal-dir">
+ <para><literal>create-journal-dir</literal></para>
+ <para>If this is set to <literal>true</literal> then the journal directory will be
+ automatically created at the location specified in <literal
+ >journal-directory</literal> if it does not already exist. The default value
+ is <literal>true</literal></para>
+ </listitem>
+ <listitem id="configuring.message.journal.journal-type">
+ <para><literal>journal-type</literal></para>
+ <para>Valid values are <literal>NIO</literal> or <literal>ASYNCIO</literal>.</para>
+ <para>Choosing <literal>NIO</literal> chooses the Java NIO journal. Choosing
+ <literal>AIO</literal> chooses the Linux asynchronous IO journal. If you
+ choose <literal>AIO</literal> but are not running Linux or you do not have
+ libaio installed then JBoss Messaging will detect this and automatically fall
+ back to using <literal>NIO</literal>.</para>
+ </listitem>
+ <listitem id="configuring.message.journal.journal-sync-transactional">
+ <para><literal>journal-sync-transactional</literal></para>
+ <para>If this is set to true then JBoss Messaging will wait for all transaction data
+ to be persisted to disk on a commit before sending a commit response OK back to
+ the client. The default value is <literal>true</literal>.</para>
+ </listitem>
+ <listitem id="configuring.message.journal.journal-sync-non-transactional">
+ <para><literal>journal-sync-non-transactional</literal></para>
+ <para>If this is set to true then JBoss Messaging will wait for any non
+ transactional data to be persisted to disk on a send before sending the response
+ back to the client. The default value for this is <literal
+ >false</literal>.</para>
+ </listitem>
+ <listitem id="configuring.message.journal.journal-file-size">
+ <para><literal>journal-file-size</literal></para>
+ <para>The size of each journal file in bytes. The default value for this is <literal
+ >10485760</literal> bytes (10MiB).</para>
+ </listitem>
+ <listitem id="configuring.message.journal.journal-min-files">
+ <para><literal>journal-min-files</literal></para>
+ <para>The minimum number of files the journal will maintain. When JBoss Messaging
+ starts and there is no initial message data, JBoss Messaging will pre-create
+ <literal>journal-min-files</literal> number of files.</para>
+ <para>Creating journal files and filling them with padding is a fairly expensive
+ operation and we want to minimise doing this at run-time as files get filled. By
+ precreating files, as one is filled the journal can immediately resume with the
+ next one without pausing to create it.</para>
+ <para>Depending on how much data you expect your queues to contain at steady state
+ you should tune this number of files to match that total amount of data.</para>
+ </listitem>
+ <listitem id="configuring.message.journal.journal-max-aio">
+ <para><literal>journal-max-aio</literal></para>
+ <para>When using an AIO journal, write requests are queued up before being submitted
+ to AIO for execution. Then when AIO has completed them it calls JBoss Messaging
+ back. This parameter controls the maximum number of write requests that can be
+ in the AIO queue at any one time. If the queue becomes full then writes will
+ block until space is freed up. This parameter has no meaning when using the NIO
+ journal.</para>
+ <para>There is a limit and the total max AIO can't be higher than what is configured
+ at the OS level (/proc/sys/fs/aio-max-nr) usually at 65536.</para>
+ <para>The default value for this is <literal>500</literal>.
+ </para>
+ </listitem>
+ <listitem id="configuring.message.journal.journal-aio-buffer-timeout">
+ <para><literal>journal-aio-buffer-timeout</literal></para>
+ <para>Flush period on the internal AIO timed buffer, configured in nano seconds. For
+ performance reasons we buffer data before submitting it to the kernel in a single batch.
+ This parameter determines the maximum amount of time to wait before flushing the buffer, if it does not get full
+ by itself in that time.</para>
+ <para>The default value for this paramater is <literal>20000</literal> nano seconds (i.e. 20 microseconds).
+ </para>
+ </listitem>
+ <listitem id="configuring.message.journal.journal-aio-flush-on-sync">
+ <para><literal>journal-aio-flush-on-sync</literal></para>
+ <para>If this is set to true, the internal buffers are flushed right away when a
+ sync request is performed. Sync requests are performed on transactions if
+ <literal>journal-sync-transactional</literal> is true, or on sending regular
+ messages if <literal>journalsync-non-transactional</literal> is true.</para>
+ <para>JBoss Messaging was made to scale up to hundreds of producers. We try to use
+ most of the hardware resources by scheduling multiple writes and syncs in a
+ single OS call.</para>
+ <para>However in some use cases it may be better to not wait any data and just flush
+ and write to the OS right away. For example if you have a single producer
+ writing small transactions. On this case it would be better to always
+ flush-on-sync.</para>
+ <para>The default value for this parameter is <literal>false</literal>.
+ </para>
+ </listitem>
+ <listitem id="configuring.message.journal.journal-aio-buffer-size">
+ <para><literal>journal-aio-buffer-size</literal></para>
+ <para>The size of the timed buffer on AIO. The default value is <literal>128KiB</literal>.</para>
+ </listitem>
+ <listitem id="configuring.message.journal.journal-compact-min-files">
+ <para><literal>journal-compact-min-files</literal></para>
+ <para>The minimal number of files before we can consider compacting the journal. The compacting algorithm won't start until you have at least <literal>journal-compact-min-files</literal></para>
+ <para>The default for this parameter is <literal>10</literal></para>
+ </listitem>
+ <listitem id="configuring.message.journal.journal-compact-percentage">
+ <para><literal>journal-compact-percentage</literal></para>
+ <para>The threshold to start compacting. When less than this percentage is considered live data, we start compacting.
+ Note also that compacting won't kick in until you have at least <literal>journal-compact-min-files</literal> data files on the journal</para>
+ <para>The default for this parameter is <literal>30</literal></para>
+ </listitem>
+ </itemizedlist>
+ </section>
+ <section id="installing-aio">
+ <title>Installing AIO</title>
+ <para>The Java NIO journal gives great performance, but If you are running JBoss Messaging
+ using Linux Kernel 2.6 or later, we highly recommend you use the <literal>AIO</literal>
+ journal for the best persistence performance especially under high concurrency.</para>
+ <para>It's not possible to use the AIO journal under other operating systems or earlier
+ versions of the Linux kernel.</para>
+ <para>If you are running Linux kernel 2.6 or later and don't already have <literal
+ >libaio</literal> installed, you can easily install it using the following
+ steps:</para>
+ <para>Using yum, (e.g. on Fedora or Red Hat Enterprise Linux):
+ <programlisting>sudo yum install libaio</programlisting></para>
+ <para>Using aptitude, (e.g. on Ubuntu or Debian system):
+ <programlisting>sudo apt-get install libaio</programlisting></para>
+ </section>
+ <section id="persistence.enabled">
+ <title>Configuring JBoss Messaging for Zero Persistence</title>
+ <para> In some situations, zero persistence is sometimes required for a messaging system.
+ Configuring JBoss Messaging to perform zero persistence is straightforward. Simply set
+ the parameter <literal>persistence-enabled</literal> in <literal
+ >jbm-configuration.xml</literal> to <literal>false</literal>. </para>
+ <para>Please note that if you set this parameter to false, then <emphasis>zero</emphasis>
+ persistence will occur. That means no bindings data, message data, large message data,
+ duplicate id caches or paging data will be persisted.</para>
+ </section>
+</chapter>
Added: projects/docs/enterprise/5.0/JBoss_Messaging_2.0.0/JBoss_Messaging_User_Guide/en-US/Pre-acknowledge_Mode.xml
===================================================================
--- projects/docs/enterprise/5.0/JBoss_Messaging_2.0.0/JBoss_Messaging_User_Guide/en-US/Pre-acknowledge_Mode.xml (rev 0)
+++ projects/docs/enterprise/5.0/JBoss_Messaging_2.0.0/JBoss_Messaging_User_Guide/en-US/Pre-acknowledge_Mode.xml 2009-10-05 01:37:17 UTC (rev 94324)
@@ -0,0 +1,56 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<chapter id="pre-acknowledge">
+ <title>Pre-Acknowledge Mode</title>
+ <para>JMS specifies 3 acknowledgement modes:</para>
+ <itemizedlist>
+ <listitem>
+ <para><literal>AUTO_ACKNOWLEDGE</literal></para>
+ </listitem>
+ <listitem>
+ <para><literal>CLIENT_ACKNOWLEDGE</literal></para>
+ </listitem>
+ <listitem>
+ <para><literal>DUPS_OK_ACKNOWLEDGE</literal></para>
+ </listitem>
+ </itemizedlist>
+ <para>The acknowledgement modes all involve sending acknowledgements from the client to the
+ server. However, in the case where you can afford to lose messages in event of failure, it
+ would make sense to acknowledge the message on the server <emphasis>before</emphasis>
+ delivering it to the client.</para>
+ <para>The disadvantage of acknowledging on the server before delivery is that the message will be
+ lost if the system crashes <emphasis>after</emphasis> acknowledging the message on the server
+ but <emphasis>before</emphasis> it is delivered to the client. In that case, the message is
+ lost and will not be recovered when the system restart.</para>
+ <para>Depending on your messaging case, <literal>pre-acknowledgement</literal> mode can avoid
+ extra network traffic and CPU at the cost of coping with message loss.</para>
+ <para>An example of a use case for pre-acknowledgement is for stock price update messages. With
+ these messages it might be reasonable to lose a message in event of crash, since the next
+ price update message will arrive soon, overriding the previous price. </para>
+ <section id="pre-acknowledge.configure">
+ <title>Using PRE_ACKNOWLEDGE</title>
+ <para>This can be configured in the <literal>jbm-jms.xml</literal> file on the <literal
+ >connection factory</literal> like this:</para>
+ <programlisting><connection-factory name="ConnectionFactory">
+ <connector-ref connector-name="netty-connector"/>
+ <entries>
+ <entry name="ConnectionFactory"/>
+ </entries>
+ <pre-acknowledge>true</pre-acknowledge>
+</connection-factory></programlisting>
+ <para>Alternatively use pre-acknowledgement mode using the JMS API, create a JMS Session with
+ the <literal>JBossSession.PRE_ACKNOWLEDGE</literal> constant.</para>
+ <programlisting>
+// messages will be acknowledge on the server *before* being delivered to the client
+Session session = connection.createSession(false, JBossSession.PRE_ACKNOWLEDGE);
+ </programlisting>
+ <para>Or you can set pre-acknowledge directly on the <literal>JBossConnectionFactory</literal>
+ instance using the setter method.</para>
+ <para>To use pre-acknowledgement mode using the core API you can set it directly on the
+ <literal>ClientSessionFactory</literal> instance using the setter method.</para>
+ </section>
+ <section>
+ <title>Example</title>
+ <para>See <xref linkend="examples.pre-acknowledge" /> for an example which
+ shows how to use pre-acknowledgement mode with with JMS.</para>
+ </section>
+</chapter>
Added: projects/docs/enterprise/5.0/JBoss_Messaging_2.0.0/JBoss_Messaging_User_Guide/en-US/Queue_Attributes.xml
===================================================================
--- projects/docs/enterprise/5.0/JBoss_Messaging_2.0.0/JBoss_Messaging_User_Guide/en-US/Queue_Attributes.xml (rev 0)
+++ projects/docs/enterprise/5.0/JBoss_Messaging_2.0.0/JBoss_Messaging_User_Guide/en-US/Queue_Attributes.xml 2009-10-05 01:37:17 UTC (rev 94324)
@@ -0,0 +1,110 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<chapter id="queue-attributes">
+ <title>Queue Attributes</title>
+ <para>Queue attributes can be set in one of two ways. Either by configuring them using the
+ configuration file or by using the core API. This chapter will explain how to configure each
+ attribute and what effect the attribute has.</para>
+ <section id="predefined.queues">
+ <title>Predefined Queues</title>
+ <para>Queues can be predefined via configuration at a core level or at a JMS level. Firstly
+ lets look at a JMS level.</para>
+ <para>The following shows a queue predefined in the <literal>jbm-jms.xml</literal>
+ configuration file.</para>
+ <programlisting><queue name="selectorQueue">
+ <entry name="/queue/selectorQueue"/>
+ <selector string="color='red'"/>
+ <durable>true</durable>
+</queue></programlisting>
+ <para>This name attribute of queue defines the name of the queue. When we do this at a jms
+ level we follow a naming convention so the actual name of the core queue will be
+ <literal>jms.queue.selectorQueue</literal>.</para>
+ <para>The entry element configures the name that will be used to bind the queue to JNDI.
+ This is a mandatory element and the queue can contain multiple of these to bind the same
+ queue to different names.</para>
+ <para>The selector element defines what JMS message selector the predefined queue will have.
+ Only messages that match the selector will be added to the queue. This is an optional
+ element with a default of null when omitted.</para>
+ <para>The durable element specifies whether the queue will be persisted. This again is
+ optional and defaults to true if omitted.</para>
+ <para>Secondly a queue can be predefined at a core level in the <literal
+ >jbm-configuration.xml</literal> file. The following is an example.</para>
+ <programlisting><queues>
+ <queue name="jms.queue.selectorQueue">
+ <address>jms.queue.selectorQueue</address>
+ <filter string="color='red'"/>
+ <durable>true</durable>
+ </queue>
+</queues></programlisting>
+ <para>This is very similar to the JMS configuration, with 3 real differences which
+ are.</para>
+ <orderedlist>
+ <listitem>
+ <para>The name attribute of queue is the actual name used for the queue with no
+ naming convention as in JMS.</para>
+ </listitem>
+ <listitem>
+ <para>The address element defines what address is used for routing messages.</para>
+ </listitem>
+ <listitem>
+ <para>There is no entry element.</para>
+ </listitem>
+ <listitem>
+ <para>The filter uses the <emphasis>Core filter syntax</emphasis>
+ (described in <xref linkend="filter-expressions" />),
+ <emphasis>not</emphasis> the JMS selector syntax.</para>
+ </listitem>
+ </orderedlist>
+ </section>
+ <section>
+ <title>Using the API</title>
+ <para>Queues can also be created using the core API or the management API.</para>
+ <para>For the core API, queues can be created via the <literal
+ >org.jboss.messaging.core.client.ClientSession</literal> interface. There are
+ multiple <literal>createQueue</literal> methods that support setting all of the
+ previously mentioned attributes. There is one extra attribute that can be set via this
+ API which is <literal>temporary</literal>. setting this to true means that the queue
+ will be deleted once the session is disconnected.</para>
+ <para>Take a look at <xref linkend="management" /> for a description of the management API
+ for creating queues.</para>
+ </section>
+ <section id="queue-attributes.address-settings">
+ <title>Configuring Queues Via Address Settings</title>
+ <para>There are some attributes that are defined against a queue rather than a specific
+ queue. Here an example of an <literal>address-setting</literal> entry that would be
+ found in the <literal>jbm-configuration.xml</literal> file.</para>
+ <programlisting><address-settings>
+ <address-setting match="jms.queue.exampleQueue">
+ <dead-letter-address>jms.queue.deadLetterQueue</dead-letter-address>
+ <max-delivery-attempts>3</max-delivery-attempts>
+ <redelivery-delay>5000</redelivery-delay>
+ <expiry-address>jms.queue.expiryQueue</expiry-address>
+ <last-value-queue>true</last-value-queue>
+ <distribution-policy-class>org.jboss.messaging.core.server.impl.RoundRobinDistributor</distribution-policy-class>
+ <max-size-bytes>100000</max-size-bytes>
+ <page-size-bytes>20000</page-size-bytes>
+ <redistribution-delay>0</redistribution-delay>
+ </address-setting>
+</address-settings></programlisting>
+ <para>These are explained fully throughout the user manual, howvere here is a breif
+ description with a link to the appropriate chapter if available. </para>
+ <para><literal>max-delivery-attempts</literal> defines how many time a cancelled message can
+ be redelivered before sending to the <literal>dead-letter-address</literal>. A full
+ explanation can be found <link linkend="undelivered-messages.configuring"
+ >here</link>.</para>
+ <para><literal>redelivery-delay</literal> defines how long to wait before attempting
+ redelivery of a cancelled message. see <link linkend="undelivered-messages.delay"
+ >here</link>.</para>
+ <para><literal>expiry-address</literal> defines where to send a message that has expired.
+ see <link linkend="message-expiry.configuring">here</link>.</para>
+ <para><literal>last-value-queue</literal> defines whether a queue only uses last values or
+ not. see <link linkend="last-value-queues">here</link>.</para>
+ <para><literal>distribution-policy-class</literal> define the class to use for distribution
+ of messages by a queue to consumers. By default this is <literal
+ >org.jboss.messaging.core.server.impl.RoundRobinDistributor</literal>.</para>
+ <para><literal>max-size-bytes</literal> and <literal>page-size-bytes</literal> are used to
+ set paging on an address. This is explained <link linkend="paging">here</link>.</para>
+ <para><literal>redistribution-delay</literal> defines how long to wait when the last
+ consumer is closed on a queue before redistributing any messages. see <link
+ linkend="clusters.message-redistribution">here</link>.</para>
+ </section>
+</chapter>
Added: projects/docs/enterprise/5.0/JBoss_Messaging_2.0.0/JBoss_Messaging_User_Guide/en-US/Security.xml
===================================================================
--- projects/docs/enterprise/5.0/JBoss_Messaging_2.0.0/JBoss_Messaging_User_Guide/en-US/Security.xml (rev 0)
+++ projects/docs/enterprise/5.0/JBoss_Messaging_2.0.0/JBoss_Messaging_User_Guide/en-US/Security.xml 2009-10-05 01:37:17 UTC (rev 94324)
@@ -0,0 +1,258 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<chapter id="security">
+ <title>Security</title>
+ <para>This chapter describes how security works with JBoss Messaging and how you can configure
+ it. To disable security completely simply set the <literal>security-enabled</literal>
+ property to false in the <literal>jbm-configuration.xml</literal> file.</para>
+ <para>For performance reasons security is cached and invalidated every so long. To change this
+ period set the property <literal>security-invalidation-interval</literal>, which is in
+ milliseconds. The default is <literal>10000</literal> ms.</para>
+ <section id="security.settings.roles">
+ <title>Role based security for addresses</title>
+ <para>JBoss Messaging contains a flexible role-based security model for applying security to
+ queues, based on their addresses.</para>
+ <para>As explained in <xref linkend="using-core" />, JBoss Messaging core consists
+ mainly of sets of queues bound to addresses. A message is sent to an address and the
+ server looks up the set of queues that are bound to that address, the server then routes
+ the message to those set of queues.</para>
+ <para>JBoss Messaging allows sets of permissions to be defined against the queues based on
+ their address. An exact match on the address can be used or a wildcard match can be used
+ using the wildcard characters '<literal>#</literal>' and '<literal>*</literal>'.</para>
+ <para>Seven different permissions can be given to the set of queues which match the address.
+ Those permissions are:</para>
+ <itemizedlist>
+ <listitem>
+ <para><literal>createDurableQueue</literal>. This permission allows the user to
+ create a durable queue under matching addresses.</para>
+ </listitem>
+ <listitem>
+ <para><literal>deleteDurableQueue</literal>. This permission allows the user to
+ delete a durable queue under matching addresses.</para>
+ </listitem>
+ <listitem>
+ <para><literal>createTempQueue</literal>. This permission allows the user to create
+ a temporary queue under matching addresses.</para>
+ </listitem>
+ <listitem>
+ <para><literal>deleteTempQueue</literal>. This permission allows the user to delete
+ a temporarry queue under matching addresses.</para>
+ </listitem>
+ <listitem>
+ <para><literal>send</literal>. This permission allows the user to send a message to
+ matching addresses.</para>
+ </listitem>
+ <listitem>
+ <para><literal>consume</literal>. This permission allows the user to consume a
+ message from a queue bound to matching addresses.</para>
+ </listitem>
+ <listitem>
+ <para><literal>manage</literal>. This permission allows the user to invoke
+ management operations by sending management messages to the management
+ address.</para>
+ </listitem>
+ </itemizedlist>
+ <para>For each permission, a list of roles who are granted that permission is specified. If
+ the user has any of those roles, he/she will be granted that permission for that set of
+ addresses.</para>
+ <para>Let's take a simple example, here's a security block from <literal
+ >jbm-configuration.xml</literal> or <literal>jbm-queues.xml</literal> file:</para>
+ <programlisting>
+<security-setting match="globalqueues.europe.#">
+ <permission type="createDurableQueue" roles="admin"/>
+ <permission type="deleteDurableQueue" roles="admin"/>
+ <permission type="createTempQueue" roles="admin, guest, europe-users"/>
+ <permission type="deleteTempQueue" roles="admin, guest, europe-users"/>
+ <permission type="send" roles="admin, europe-users"/>
+ <permission type="consume" roles="admin, europe-users"/>
+</security-setting>
+ </programlisting>
+ <para>The '<literal>#</literal>' character signifies "any sequence of words". Words are
+ delimited by the '<literal>.</literal>' character. For a full description of the
+ wildcard syntax please see <xref linkend="wildcard-syntax"/>.
+ The above security block applies to any address that starts with the
+ string "globalqueues.europe.":</para>
+ <para>Only users who have the <literal>admin</literal> role can create or delete durable
+ queues bound to an address that starts with the string "globalqueues.europe."</para>
+ <para>Only users who have the <literal>admin</literal> role can create or delete durable
+ queues bound to an address that starts with the string "globalqueues.europe."</para>
+ <para>Any users with the roles <literal>admin</literal>, <literal>guest</literal>, or
+ <literal>europe-users</literal> can create or delete temporary queues bound to an
+ address that starts with the string "globalqueues.europe."</para>
+ <para>Any users with the roles <literal>admin</literal> or <literal>europe-users</literal>
+ can send messages to these addresses or consume messages from queues bound to an address
+ that starts with the string "globalqueues.europe."</para>
+ <para>The mapping between a user and what roles they have is handled by the security
+ manager. JBoss Messaging ships with a user manager that reads user credentials from a
+ file on disk, and can also plug into JAAS or JBoss Application Server security.</para>
+ <para>For more information on configuring the security manager, please see <xref
+ linkend="change-security-manager" />.</para>
+ <para>There can be zero or more <literal>security-setting</literal> elements in each xml
+ file. Where more than one match applies to a set of addresses the <emphasis>more
+ specific</emphasis> match takes precedence.</para>
+ <para>Let's look at an example of that, here's another <literal>security-setting</literal>
+ block:</para>
+ <programlisting>
+<security-setting match="globalqueues.europe.orders.#">
+ <permission type="send" roles="europe-users"/>
+ <permission type="consume" roles="europe-users"/>
+</security-setting>
+ </programlisting>
+ <para>In this <literal>security-setting</literal> block the match
+ 'globalqueues.europe.orders.#' is more specific than the previous match
+ 'globalqueues.europe.#'. So any addresses which match 'globalqueues.europe.orders.#'
+ will take their security settings <emphasis>only</emphasis> from the latter
+ security-setting block.</para>
+ <para>Note that settings are not inherited from the former block. All the settings will be
+ taken from the more specific matching block, so for the address
+ 'globalqueues.europe.orders.plastics' the only permissions that exist are <literal
+ >send</literal> and <literal>consume</literal> for the role europe-users. The
+ permissions <literal>createDurableQueue</literal>, <literal
+ >deleteDurableQueue</literal>, <literal>createTempQueue</literal>, <literal
+ >deleteTempQueue</literal> are not inherited from the other security-setting
+ block.</para>
+ <para>By not inheriting permissions, it allows you to effectively deny permissions in more
+ specific security-setting blocks by simply not specifying them. Otherwise it would not
+ be possible to deny permissions in sub-groups of addresses.</para>
+ </section>
+ <section>
+ <title>Secure Sockets Layer (SSL) Transport</title>
+ <para>When messaging clients are connected to servers, or servers are connected to other
+ servers (e.g. via bridges) over an untrusted network then JBoss Messaging allows that
+ traffic to be encrypted using the Secure Sockets Layer (SSL) transport.</para>
+ <para>For more information on configuring the SSL transport, please see <xref
+ linkend="configuring-transports" />.</para>
+ </section>
+ <section>
+ <title>Basic user credentials</title>
+ <para> JBoss Messaging ships with a security manager implementation that reads user
+ credentials, i.e. user names, passwords and role information from an xml file on the
+ classpath called <literal>jbm-users.xml</literal>. This is the default security
+ manager.</para>
+ <para>If you wish to use this security manager, then users, passwords and roles can easily
+ be added into this file.</para>
+ <para>Let's take a look at an example file:</para>
+ <programlisting>
+<configuration xmlns="urn:jboss:messaging"
+ xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+ xsi:schemaLocation="urn:jboss:messaging ../schemas/jbm-users.xsd ">
+
+ <defaultuser name="guest" password="guest">
+ <role name="guest"/>
+ </defaultuser>
+
+ <user name="tim" password="marmite">
+ <role name="admin"/>
+ </user>
+
+ <user name="andy" password="doner_kebab">
+ <role name="admin"/>
+ <role name="guest"/>
+ </user>
+
+ <user name="jeff" password="camembert">
+ <role name="europe-users"/>
+ <role name="guest"/>
+ </user>
+
+</configuration>
+ </programlisting>
+ <para>The first thing to note is the element <literal>default-user</literal>. This defines
+ what user will be assumed when the client does not specify a username/password when
+ creating a session. In this case they will be the user <literal>guest</literal> and have
+ the role also called <literal>guest</literal>. Multiple roles can be specified for a
+ default user.</para>
+ <para>We then have three more users, the user <literal>tim</literal> has the role <literal
+ >admin</literal>. The user <literal>andy</literal> has the roles <literal
+ >admin</literal> and <literal>guest</literal>, and the user <literal>jeff</literal>
+ has the roles <literal>europe-users</literal> and <literal>guest</literal>.</para>
+ </section>
+ <section id="change-security-manager">
+ <title>Changing the security manager</title>
+ <para>If you do not want to use the default security manager then you can specify a
+ different one by editing the <literal>jbm-jboss-beans.xml</literal> file and changing
+ the class for the <literal>JBMSecurityManager</literal> bean.</para>
+ <para>Let's take a look at a snippet from the default beans file:</para>
+ <programlisting>
+<bean name="JBMSecurityManager"
+ class="org.jboss.messaging.core.security.impl.JBMSecurityManagerImpl">
+ <start ignored="true"/>
+ <stop ignored="true"/>
+</bean>
+ </programlisting>
+ <para>The class <literal
+ >org.jboss.messaging.core.security.impl.JBMSecurityManagerImpl</literal> is the
+ default security manager that reads used by the standalone server.</para>
+ <para>JBoss Messaging ships with two other security manager implementations you can use
+ off-the-shelf; one a JAAS security manager and another for integrating with JBoss
+ Application Sever security, alternatively you could write your own implementation by
+ implementing the <literal>org.jboss.messaging.core.security.SecurityManager</literal>
+ interface, and specifying the classname of your implementation in the <literal
+ >jbm-jboss-beans.xml</literal> file.</para>
+ <para>These two implementations are discussed in the next two sections.</para>
+ </section>
+ <section>
+ <title>JAAS Security Manager</title>
+ <para>JAAS stands for 'Java Authentication and Authorization Service' and is a standard part
+ of the Java platform. It provides a common API for security authentication and
+ authorization, allowing you to plugin your pre-built implementations.</para>
+ <para>To configure the JAAS security manager to work with your pre-built JAAS infrastructure
+ you need to specify the security manager as a <literal>JAASSecurityManager</literal> in
+ the beans file. Here's an example:</para>
+ <programlisting>
+<bean name="JBMSecurityManager"
+ class="org.jboss.messaging.integration.security.JAASSecurityManager">
+ <start ignored="true"/>
+ <stop ignored="true"/>
+
+ <property name="ConfigurationName">org.jboss.jms.example.ExampleLoginModule</property>
+ <property name="Configuration">
+ <inject bean="ExampleConfiguration"/>
+ </property>
+ <property name="CallbackHandler">
+ <inject bean="ExampleCallbackHandler"/>
+ </property>
+</bean>
+ </programlisting>
+ <para>Note that you need to feed the JAAS security manager with three properties:</para>
+ <itemizedlist>
+ <listitem>
+ <para>ConfigurationName: the name of the <literal>LoginModule</literal>
+ implementation that JAAS must use</para>
+ </listitem>
+ <listitem>
+ <para>Configuration: the <literal>Configuration</literal> implementation used by
+ JAAS</para>
+ </listitem>
+ <listitem>
+ <para>CallbackHandler: the <literal>CallbackHandler</literal> implementation to use
+ if user interaction are required</para>
+ </listitem>
+ </itemizedlist>
+ <section>
+ <title>Example</title>
+ <para>See <xref linkend="examples.jaas" /> for an example which
+ shows how JBoss Messaging can be configured to use JAAS.</para>
+ </section>
+ </section>
+ <section>
+ <title>JBoss AS Security Manager</title>
+ <para>The JBoss AS security manager is used when running JBoss Messaging inside the JBoss
+ Application server. This allows tight integration with the JBoss Application Server's
+ security model.</para>
+ <para>The class name of this security manager is <literal
+ >org.jboss.messaging.integration.security.JBossASSecurityManager</literal></para>
+ <para>Take a look at one of the default <literal>jbm-jboss-beans.xml</literal> files for
+ JBoss Application Server that are bundled in the distribution for an example of how this
+ is configured.</para>
+ </section>
+ <section>
+ <title>Changing the Management Password for Clustering</title>
+ <para>In order for cluster connections to work correctly, each node in the cluster must
+ register for management notifications from other nodes. To do this they must perform
+ these actions as a user with a role that has <literal>admin</literal> permissions on the
+ management addresses.</para>
+ <para>This password should always be changed from its default after installation. Please see
+ <xref linkend="management" /> for instructions on how to do
+ this.</para>
+ </section>
+</chapter>
Added: projects/docs/enterprise/5.0/JBoss_Messaging_2.0.0/JBoss_Messaging_User_Guide/en-US/Send_Guarantees.xml
===================================================================
--- projects/docs/enterprise/5.0/JBoss_Messaging_2.0.0/JBoss_Messaging_User_Guide/en-US/Send_Guarantees.xml (rev 0)
+++ projects/docs/enterprise/5.0/JBoss_Messaging_2.0.0/JBoss_Messaging_User_Guide/en-US/Send_Guarantees.xml 2009-10-05 01:37:17 UTC (rev 94324)
@@ -0,0 +1,131 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<chapter id="send-guarantees">
+ <title>Guarantees of Transactional and Non-Transactional Sends and Asynchronous Send
+ Acknowledgements</title>
+ <section>
+ <title>Guarantees of Transaction Completion</title>
+ <para>When committing or rolling back a transaction with JBoss Messaging, the request to
+ commit or rollback is sent to the server, and the call will block on the client side
+ until a response has been received from the server that the commit or rollback was
+ executed.</para>
+ <para>When the commit or rollback is received on the server, it will be committed to the
+ journal, and depending on the value of the parameter <literal
+ >journal-sync-transactional</literal> the server will ensure that the commit or
+ rollback is durably persisted to storage before sending the response back to the client.
+ If this parameter has the value <literal>false</literal> then commit or rollback may not
+ actually get persisted to storage until some time after the response has been sent to
+ the client. In event of server failure this may mean the commit or rollback never gets
+ persisted to storage. The default value of this parameter is <literal>true</literal> so
+ the client can be sure all transaction commits or rollbacks have been persisted to
+ storage by the time the call to commit or rollback returns.</para>
+ <para>Setting this parameter to <literal>false</literal> can improve performance at the
+ expense of some loss of transaction durability.</para>
+ <para>This parameter is set in <literal>jbm-configuration.xml</literal></para>
+ </section>
+ <section id="non-transactional-sends">
+ <title>Guarantees of Non Transactional Message Sends</title>
+ <para>If you are sending messages to a server using a non transacted session, JBoss
+ Messaging can be configured to block the call to send until the message has definitely
+ reached the server, and a response has been sent back to the client. This can be
+ configured individually for persistent and non-persistent messages, and is determined by
+ the following two parameters:</para>
+ <itemizedlist>
+ <listitem>
+ <para><literal>BlockOnPersistentSend</literal>. If this is set to <literal
+ >true</literal> then all calls to send for persistent messages on non
+ transacted sessions will block until the message has reached the server, and a
+ response has been sent back. The default value is <literal>false</literal>.
+ </para>
+ </listitem>
+ <listitem>
+ <para><literal>BlockOnNonPersistentSend</literal>. If this is set to <literal
+ >true</literal> then all calls to send for non-persistent messages on non
+ transacted sessions will block until the message has reached the server, and a
+ response has been sent back. The default value is <literal
+ >false</literal>.</para>
+ </listitem>
+ </itemizedlist>
+ <para>Setting block on sends to <literal>true</literal> can reduce performance since each
+ send requires a network round trip before the next send can be performed. This means the
+ performance of sending messages will be limited by the network round trip time (RTT) of
+ your network, rather than the bandwidth of your network. For better performance we
+ recommend either batching many messages sends together in a transaction since with a
+ transactional session, only the commit / rollback blocks not every send, or, using JBoss
+ Messaging's advanced <emphasis>asynchronous send acknowledgements feature</emphasis>
+ described in <xref linkend="asynchronous-send-acknowledgements" />.</para>
+ <para>If you are using JMS and you're using the JMS service on the server to load your JMS
+ connection factory instances into JNDI then these parameters can be configured in
+ <literal>jbm-jms.xml</literal> using the elements <literal
+ >block-on-persistent-send</literal> and <literal
+ >block-on-non-persistent-send</literal>. If you're using JMS but not using JNDI then
+ you can set these values directly on the <literal>JBossConnectionFactory</literal>
+ instance using the appropriate setter methods.</para>
+ <para>If you're using core you can set these values directly on the <literal
+ >ClientSessionFactory</literal> instance using the appropriate setter
+ methods.</para>
+ <para>When the server receives a message sent from a non transactional session, and that
+ message is persistent and the message is routed to at least one durable queue, then the
+ server will persist the message in permanent storage. If the journal parameter <literal
+ >journal-sync-non-transactional</literal> is set to <literal>true</literal> the
+ server will not send a response back to the client until the message has been persisted
+ and the server has a guarantee that the data has been persisted to disk. The default
+ value for this parameter is <literal>false</literal>.</para>
+ </section>
+ <section id="send-guarantees.nontrans.acks">
+ <title>Guarantees of Non Transactional Acknowledgements</title>
+ <para>If you are acknowledging the delivery of a message at the client side using a non
+ transacted session, JBoss Messaging can be configured to block the call to acknowledge
+ until the acknowledge has definitely reached the server, and a response has been sent
+ back to the client. This is configured with the parameter <literal
+ >BlockOnAcknowledge</literal>. If this is set to <literal>true</literal> then all
+ calls to acknowledge on non transacted sessions will block until the acknowledge has
+ reached the server, and a response has been sent back. You might want to set this to
+ <literal>true</literal> if you want to implement a strict <emphasis>at most
+ once</emphasis> delivery policy. The default value is <literal
+ >false</literal></para>
+ </section>
+ <section id="asynchronous-send-acknowledgements">
+ <title>Asynchronous Send Acknowledgements</title>
+ <para>If you are using a non transacted session but want a guarantee that every message sent
+ to the server has reached it, then, as discussed in <xref
+ linkend="non-transactional-sends"/>, you can configure JBoss Messaging to block the
+ call to send until the server has received the message, persisted it and sent back a
+ response. This works well but has a severe performance penalty - each call to send needs
+ to block for at least the time of a network round trip (RTT) - the performance of
+ sending is thus limited by the latency of the network, <emphasis>not</emphasis> limited
+ by the network bandwidth.</para>
+ <para>Let's do a little bit of maths to see how severe that is. We'll consider a standard
+ 1Gib ethernet network with a network round trip between the server and the client of
+ 0.25 ms.</para>
+ <para>With a RTT of 0.25 ms, the client can send <emphasis>at most</emphasis> 1000/ 0.25 =
+ 4000 messages per second if it blocks on each message send.</para>
+ <para>If each message is < 1500 bytes and a standard 1500 bytes MTU size is used on the
+ network, then a 1GiB network has a <emphasis>theoretical</emphasis> upper limit of (1024
+ * 1024 * 1024 / 8) / 1500 = 89478 messages per second if messages are sent without
+ blocking! These figures aren't an exact science but you can clearly see that being
+ limited by network RTT can have serious effect on performance.</para>
+ <para>To remedy this, JBoss Messaging provides an advanced new feature called
+ <emphasis>asynchronous send acknowledgements</emphasis>. With this feature, JBoss
+ Messaging can be configured to send messages without blocking in one direction and
+ asynchronously getting acknowledgement from the server that the messages were received
+ in a separate stream. By de-coupling the send from the acknowledgement of the send, the
+ system is not limited by the network RTT, but is limited by the network bandwidth.
+ Consequently better throughput can be achieved than is possible using a blocking
+ approach, while at the same time having absolute guarantees that messages have
+ successfully reached the server.</para>
+ <section>
+ <title>Asynchronous Send Acknowledgements</title>
+ <para>To use the feature using the core API, you implement the interface <literal
+ >org.jboss.messaging.core.client.SendAcknowledgementHandler</literal> and set a
+ handler instance on your <literal>ClientSession</literal>.</para>
+ <para>Then, you just send messages as normal using your <literal
+ >ClientSession</literal>, and as messages reach the server, the server will send
+ back an acknowledgment of the send asynchronously, and some time later you are
+ informed at the client side by JBoss Messaging calling your handler's <literal
+ >sendAcknowledged(ClientMessage message)</literal> method, passing in a
+ reference to the message that was sent.</para>
+ <para>Please see <xref linkend="asynchronous-send-acknowledgements-example" />
+ for a full working example.</para>
+ </section>
+ </section>
+</chapter>
Added: projects/docs/enterprise/5.0/JBoss_Messaging_2.0.0/JBoss_Messaging_User_Guide/en-US/Thread_Management.xml
===================================================================
--- projects/docs/enterprise/5.0/JBoss_Messaging_2.0.0/JBoss_Messaging_User_Guide/en-US/Thread_Management.xml (rev 0)
+++ projects/docs/enterprise/5.0/JBoss_Messaging_2.0.0/JBoss_Messaging_User_Guide/en-US/Thread_Management.xml 2009-10-05 01:37:17 UTC (rev 94324)
@@ -0,0 +1,109 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<chapter id="thread-pooling">
+ <title>Thread management</title>
+ <para>This chapter describes how JBoss Messaging uses and pools threads and how you can manage
+ them.</para>
+ <para>First we'll discuss how threads are managed and used on the server side, then we'll look
+ at the client side.</para>
+ <section>
+ <title>Server-Side Thread Management</title>
+ <para>Each JBoss Messaging Server maintains a single thread pool for general use, and a
+ scheduled thread pool for scheduled use. A Java scheduled thread pool cannot be
+ configured to use a standard thread pool, otherwise we could use a single thread pool
+ for both scheduled and non scheduled activity.</para>
+ <para>There are also a small number of other places where threads are used directly, we'll
+ discuss each in turn.</para>
+ <section id="server.scheduled.thread.pool">
+ <title>Server Scheduled Thread Pool</title>
+ <para>The server scheduled thread pool is used for most activities on the server side
+ that require running periodically or with delays. It maps internally to a <literal
+ >java.util.concurrent.ScheduledThreadPoolExecutor</literal> instance.</para>
+ <para>The maximum number of thread used by this pool is configure in <literal
+ >jbm-configuration.xml</literal> with the <literal
+ >scheduled-thread-pool-max-size</literal> parameter. The default value is
+ <literal>5</literal> threads. A small number of threads is usually sufficient
+ for this pool.</para>
+ </section>
+ <section>
+ <title>General Purpose Server Thread Pool</title>
+ <para>This general purpose thread pool is used for most asynchronous actions on the
+ server side. It maps internally to a <literal
+ >java.util.concurrent.ThreadPoolExecutor</literal> instance.</para>
+ <para>The maximum number of thread used by this pool is configure in <literal
+ >jbm-configuration.xml</literal> with the <literal
+ >thread-pool-max-size</literal> parameter.</para>
+ <para>If a value of <literal>-1</literal> is used this signifies that the thread pool
+ has no upper bound and new threads will be created on demand if there are enough
+ threads available to satisfy a request. If activity later subsides then threads are
+ timed-out and closed.</para>
+ <para>If a value of <literal>n</literal> where <literal>n</literal>is a positive integer
+ greater than zero is used this signifies that the thread pool is bounded. If more
+ requests come in and there are no free threads in the pool and the pool is full then
+ requests will block until a thread becomes available. It is recommended that a
+ bounded thread pool is used with caution since it can lead to dead-lock situations
+ if the upper bound is chosen to be too low.</para>
+ <para>The default value for <literal>thread-pool-max-size</literal> is <literal
+ >-1</literal>, i.e. the thread pool is unbounded.</para>
+ <para>See the <ulink
+ url="http://java.sun.com/j2se/1.5.0/docs/api/java/util/concurrent/ThreadPoolExecutor.html"
+ >J2SE javadoc</ulink> for more information on unbounded (cached), and bounded
+ (fixed) thread pools.</para>
+ </section>
+ <section>
+ <title>Expiry Reaper Thread</title>
+ <para>A single thread is also used on the server side to scan for expired messages in
+ queues. We cannot use either of the thread pools for this since this thread needs to
+ run at its own configurable priority.</para>
+ <para>For more information on configuring the reaper, please see <xref
+ linkend="message-expiry"/>.</para>
+ </section>
+ <section>
+ <title>Asynchronous IO</title>
+ <para>Asynchronous IO has a thread pool for receiving and dispatching events out of the
+ native layer. You will find it on a thread dump with the prefix JBM-AIO-poller-pool.
+ JBoss Messaging uses one thread per opened file on the journal (there is usually
+ one).</para>
+ <para>There is also a single thread used to invoke writes on libaio. We do that to avoid
+ context switching on libaio what would cause performance issues. You will find this
+ thread on a thread dump with the prefix JBM-AIO-writer-pool.</para>
+ </section>
+ </section>
+ <section id="thread-pooling.client.side">
+ <title>Client-Side Thread Management</title>
+ <para>On the client side, JBoss Messaging maintains a single static scheduled thread pool
+ and a single static general thread pool for use by all clients using the same
+ classloader in that JVM instance.</para>
+ <para>The static scheduled thread pool has a maximum size of <literal>2</literal> threads,
+ and the general purpose thread pool has an unbounded maximum size.</para>
+ <para>If required JBoss Messaging can also be configured so that each <literal
+ >ClientSessionFactory</literal> instance does not use these static pools but instead
+ maintains its own scheduled and general purpose pool. Any sessions created from that
+ <literal>ClientSessionFactory</literal> will use those pools instead.</para>
+ <para>To configure a <literal>ClientSessionFactory</literal> instance to use its own pools,
+ simply use the appropriate setter methods immediately after creation, for
+ example:</para>
+ <programlisting>ClientSessionFactory myFactory = new ClientSessionFactory(...);
+myFactory.setUseGlobalPools(false);
+myFactory.setScheduledThreadPoolMaxSize(10);
+myFactory.setThreadPoolMaxSize(-1); </programlisting>
+ <para>If you're using the JMS API, you can set the same parameters directly on the <literal
+ >JBossConnectionFactory</literal> instance, for example:</para>
+ <programlisting>JBossConnectionFactory myFactory = new JBossConnectionFactory(...);
+myFactory.setUseGlobalPools(false);
+myFactory.setScheduledThreadPoolMaxSize(10);
+myFactory.setThreadPoolMaxSize(-1); </programlisting>
+ <para>If you're using JNDI to instantiate <literal>JBossConnectionFactory</literal>
+ instances, you can also set these parameters in the <literal>jbm-jms.xml</literal> file
+ where you describe your connection factory, for example:</para>
+ <programlisting><connection-factory name="ConnectionFactory">
+ <connector-ref connector-name="netty"/>
+ <entries>
+ <entry name="ConnectionFactory"/>
+ <entry name="XAConnectionFactory"/>
+ </entries>
+ <use-global-pools>false</use-global-pools>
+ <scheduled-thread-pool-max-size>10</scheduled-thread-pool-max-size>
+ <thread-pool-max-size>-1</thread-pool-max-size>
+</connection-factory></programlisting>
+ </section>
+</chapter>
Added: projects/docs/enterprise/5.0/JBoss_Messaging_2.0.0/JBoss_Messaging_User_Guide/en-US/Using_Core.xml
===================================================================
--- projects/docs/enterprise/5.0/JBoss_Messaging_2.0.0/JBoss_Messaging_User_Guide/en-US/Using_Core.xml (rev 0)
+++ projects/docs/enterprise/5.0/JBoss_Messaging_2.0.0/JBoss_Messaging_User_Guide/en-US/Using_Core.xml 2009-10-05 01:37:17 UTC (rev 94324)
@@ -0,0 +1,123 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<chapter id="using-core">
+ <title>Using Core</title>
+ <para>
+ JBoss Messaging Core has its own Core API, and does not rely on the Java Message Service (JMS) API. You can use the Core API directly to get all the functions of JMS without the complexity. The Core API also provides several additional features.
+ </para>
+
+ <section>
+ <title>Core Messaging Concepts</title>
+ <para>
+ Some Core Messaging concepts will be familiar from JMS, but they do differ in some ways. The The Core API is simpler than the JMS API, since it removes the distinctions between queues, topics and subscriptions. This section takes you through the basics of Core Messaging concepts. For further detail, please see the JavaDoc.
+ </para>
+ <section>
+ <title>Message</title>
+ <para>
+ A <emphasis>message</emphasis> is a unit of data that is sent between clients and servers.
+ </para>
+ <para>
+ A message has a <emphasis>body</emphasis>, which is effectively a <literal>byte[]</literal>. A message also has a set of properties that form <varname>key</varname> and <varname>value</varname> pairs. A <varname>key</varname> takes a String as a value; a <varname>property</varname> can take any of the following data types as a value: Integer, Long, Short, byte, byte[], String, Double, Float, or Boolean.
+ </para>
+ <para>
+ A message has a <varname>destination</varname> attribute, which represents the address to which the message will be sent. When a message arrives on a server, it is routed to any queue or queues bound to the address. (An address can have zero or more queues bound to it.)
+ </para>
+ <para>
+ A message can be <emphasis>durable</emphasis> or <emphasis>non-durable</emphasis>. Durable messages in a durable queue will survive server failure or restart. Non-durable messages will never survive server failure or restart.
+ </para>
+ <para>
+ Messages can also be assigned a priority value between <literal>0</literal> and <literal>9</literal>. <literal>0</literal> represents the highest priority, and <literal>9</literal> represents the lowest. JBoss Messaging attempts to deliver higher priority messages before lower priority messages.
+ </para>
+ <para>
+ You can also specify an expiry time for a message. This is optional. JBoss Messaging will not deliver messages after the expiry time has passed.
+ </para>
+ <para>
+ A message can also be assigned a <emphasis>timestamp</emphasis>, which represents the time at which the message was sent.
+ </para>
+ </section>
+ <section>
+ <title>Address</title>
+ <para>
+ A server maintains the mapping between an address and a queue or set of queues. Zero or more queues can be bound to a single address. Each queue can also be bound with an optional <emphasis>message filter</emphasis>. When a message is routed to an address, it is also routed to the set of queues mapped to that address. Binding your message with a filter expression ensures that the message is sent only to those queues with a matching filter expression.
+ </para>
+ <note>
+ <para>
+ Topics are JMS-specific, so the Core API does not deal with topics — it deals only with addresses and queues. A JMS topic is implemented as a single address with many bound queues. Each queue therefore represents a <emphasis>subscription</emphasis> to the topic. A JMS queue is a single address with a single bound queue. Since the server can map to more than one queue with the Core API, there is no need for a concept to match the JMS topic.
+ </para>
+ </note>
+ </section>
+ <section>
+ <title>Queue</title>
+ <para>
+ A queue can be <emphasis>durable</emphasis> or <emphasis>non-durable</emphasis>. A durable queue's messages will survive server failure or restart as long as the messages themselves are durable. Non-durable queues will not survive even if their messages are durable.
+ </para>
+ <para>
+ A queue can also be <emphasis>temporary</emphasis>: it will be deleted automatically when the client connection is closed, if it has not already been explicitly deleted.
+ </para>
+ <para>
+ A queue can be bound with an optional <emphasis>filter expression</emphasis>. When specified, the server will only route messages with a matching filter expression to that queue.
+ </para>
+ <para>
+ Many queues can be bound to a single address, but a queue cannot be bound to multiple addresses.
+ </para>
+ </section>
+ <section>
+ <title>ClientSessionFactory</title>
+ <para>
+ Clients use <literal>ClientSessionFactory</literal> instances to create <literal>ClientSession</literal> instances. A <literal>ClientSessionFactory</literal> connects to the server to create a session, and has many configurable settings.
+ </para>
+ </section>
+ <section>
+ <title>ClientSession</title>
+ <para>
+ A client uses a <literal>ClientSession</literal> to consume and produce messages, and to group messages into transactions. A <literal>ClientSession</literal> instance can support transactional and non-transactional semantics. It can also provide an <literal>XAResource</literal> interface to let you perform messaging operations as part of a Java Transaction API transaction.
+ </para>
+ <para>
+ <literal>ClientSession</literal> instances group <literal>ClientConsumer</literal>s and <literal>ClientProducer</literal>s.
+ </para>
+ </section>
+ <section>
+ <title>ClientConsumer</title>
+ <para>
+ A client uses a <literal>ClientConsumer</literal> instance to consume messages from a queue. Core messaging supports both synchronous and asynchronous message consumption semantics. If you configure your <literal>ClientConsumer</literal> with a filter expression, it will only consume messages with a matching filter expression defined.
+ </para>
+ </section>
+ <section>
+ <title>ClientProducer</title>
+ <para>
+ Clients create <literal>ClientProducer</literal> instances on <literal>ClientSession</literal> instances in order to send messages. A <literal>ClientProducer</literal> can specify an address to which all messages are routed. If this is not specified, the address can be specified per-message at send-time.
+ </para>
+ </section>
+ </section>
+ <section>
+ <title>Example Core Use</title>
+ <para>
+ This is a simple program that uses the Core Messaging API to send and receive a message:
+ </para>
+ <programlisting>
+ClientSessionFactory factory = new ClientSessionFactoryImpl(
+ new TransportConfiguration(
+ InVMConnectorFactory.class.getName()));
+
+ClientSession session = factory.createSession();
+
+session.createQueue("example", "example", true);
+
+ClientProducer producer = session.createProducer("example");
+
+ClientMessage message = session.createClientMessage(true);
+
+message.getBody().writeString("Hello");
+
+producer.send(message);
+
+session.start();
+
+ClientConsumer consumer = session.createConsumer("example");
+
+ClientMessage msgReceived = consumer.receive();
+
+System.out.println("message = " + msgReceived.getBody().readString());
+
+session.close();</programlisting>
+ </section>
+</chapter>
Added: projects/docs/enterprise/5.0/JBoss_Messaging_2.0.0/JBoss_Messaging_User_Guide/en-US/Using_the_Server.xml
===================================================================
--- projects/docs/enterprise/5.0/JBoss_Messaging_2.0.0/JBoss_Messaging_User_Guide/en-US/Using_the_Server.xml (rev 0)
+++ projects/docs/enterprise/5.0/JBoss_Messaging_2.0.0/JBoss_Messaging_User_Guide/en-US/Using_the_Server.xml 2009-10-05 01:37:17 UTC (rev 94324)
@@ -0,0 +1,310 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<chapter id="using-server">
+ <title>Using the Server</title>
+ <para>
+ This chapter will let you become familiar with the JBoss Messaging server. We show you how to start and stop the server and take you through the directory layout and the purpose of the files.
+ </para>
+ <para>
+ This chapter refers to the JBoss Messaging stand-alone server in its default configuration, with both JMS and JNDI services enabled. When you run JBoss Messaging embedded in JBoss Application Server (JBoss AS), the layout will be slightly different.
+ </para>
+ <section id="using-server.starting">
+ <title>Starting and stopping the standalone server</title>
+ <para>
+ Your JBoss Messaging distribution contains a <filename>bin</filename> directory, which contains the <filename>run.sh</filename> script (or <filename>run.bat</filename> for Windows).
+ </para>
+ <para>
+ Use <command>cd</command> to move to the <filename>bin</filename> directory, and run the script. On a Linux system, use <command>./run.sh</command>; on a Windows system, use <command>run.bat</command>.
+ </para>
+ <para>
+ These scripts set up the classpath and some JVM parameters, and start the JBoss Microcontainer. JBoss Microcontainer is a lightweight container used to deploy the Plain Old Java Objects (POJOs) used in JBoss Messaging.
+ </para>
+ <para>
+ Similarly, there are <filename>stop.sh</filename> and <filename>stop.bat</filename> scripts in the <filename>bin</filename> directory, which are used to stop the server. On a Linux system, use <command>./stop.sh</command> to stop the server. On a Windows system, use <command>stop.bat</command>.
+ </para>
+ <para>
+ JBoss Messaging requires a Java Development Kit version with Java 5 or later. We recommend running on Java 6.
+ </para>
+ <para>
+ Both the run and stop scripts use the configuration details in <filename>config/stand-alone/non-clustered</filename> by default. To use an alternative configuration type, run <command>./run.sh ../config/stand-alone/$CONFIG</command>, where <literal>$CONFIG</literal> represents the directory containing your preferred configuration type. This applies to the stop and start scripts for both Linux and Windows systems.
+ </para>
+ </section>
+ <section>
+ <title>Server JVM settings</title>
+ <para>
+ The run script sets the classpath and some JVM (Java Virtual Machine) parameters, starts JBoss Microcontainer, and selects a garbage collection policy. We recommend using a parallel garbage collection algorithm to smooth latency and minimize large garbage collection pauses.
+ </para>
+ <para>
+ By default, JBoss Messaging runs with a maximum of one gigabyte of RAM. To increase the memory settings, alter the <literal>-Xms</literal> and <literal>-Xmx</literal> memory parameters. You can also edit the run scripts if you wish to add further JVM arguments, or tune the existing ones.
+ </para>
+ </section>
+ <section>
+ <title>Server classpath</title>
+ <para>
+ JBoss Messaging looks for its configuration files on the Java <emphasis>classpath</emphasis> specified by the run script.
+ </para>
+ <para>
+ By default the run scripts add the <filename>non-clustered</filename> configuration directory to the classpath. This directory contains the configuration files required to run the JBoss Messaging server in a basic non-clustered configuration. The path for this configuration option is <filename>config/stand-alone/non-clustered</filename> from the distribution's root directory.
+ </para>
+ <para>
+ The JBoss Messaging distribution contains several standard configuration sets for running:
+ </para>
+ <itemizedlist>
+ <listitem>
+ <para>Non-clustered stand-alone</para>
+ </listitem>
+ <listitem>
+ <para>Clustered stand-alone</para>
+ </listitem>
+ <listitem>
+ <para>Non-clustered in JBoss Application Server</para>
+ </listitem>
+ <listitem>
+ <para>Clustered in JBoss Application Server</para>
+ </listitem>
+ </itemizedlist>
+ <para>
+ You can also create your own configuration and specify any configuration directory when you start the server with the run script. Ensure that the configuration directory is on the classpath and JBoss Messaging will lookup the details when the server starts.
+ </para>
+ </section>
+ <section id="using-server.library.path">
+ <title>Library Path</title>
+ <para>
+ If you use the <xref linkend="aio-journal" /> on Linux, you must specify <literal>java.library.path</literal> as a property on your Java options. (This is done automatically in the <filename>run.sh</filename> script. If <literal>java.library.path</literal> is not specified, then JVM uses the <literal>LD_LIBRARY_PATH</literal> environment variable.
+ </para>
+ </section>
+ <section>
+ <title>System properties</title>
+ <para>
+ JBoss Messaging takes several Java system properties at the command line level in order to configure logging properties.
+ </para>
+ <para>
+ JBoss Messaging uses JDK logging to minimize dependencies on other logging systems. You can then configure JDK logging to delegate to another framework, such as <literal>log4j</literal>, if you prefer.
+ </para>
+ <para>
+ For further information about configuring logging, please see <xref linkend="logging" />.
+ </para>
+ </section>
+ <section id="using-server.configuration">
+ <title>Configuration files</title>
+ <para>
+ The configuration directory is specified on the classpath in the run script (<filename>run.sh</filename> or <filename>run.bat</filename>). This directory contains the following files:
+ </para>
+ <variablelist>
+ <varlistentry>
+ <term><filename>jbm-jboss-beans.xml</filename></term>
+ <listitem>
+ <para>
+ The JBoss Microcontainer beans file. Defines which beans the Microcontainer should create and what dependencies to enforce between them. See <xref linkend="usingserver.mainconfig" /> for further information about this file.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><filename>jbm-configuration.xml</filename></term>
+ <listitem>
+ <para>
+ The main JBoss Messaging configuration file. The parameters in this file are described in detail in <xref linkend="configuration-index" />.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><filename>jbm-queues.xml</filename></term>
+ <listitem>
+ <para>
+ <emphasis>Optional</emphasis>. Contains predefined queues, queue settings, and security settings. By default, this information is stored in <filename>jbm-configuration.xml</filename>. However, you can store the configuration details for separate queues in separate <filename>jbm-queues.xml</filename> files. All found <filename>jbm-queues.xml</filename> files will be loaded if found on the classpath.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><filename>jbm-users.xml</filename></term>
+ <listitem>
+ <para>
+ Contains user, password, and role information to be passed to the JBoss Messaging security manager implementation. For more information about security in JBoss Messaging, see <xref linkend="security" />.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><filename>jbm-jms.xml</filename></term>
+ <listitem>
+ <para>
+ By default, the JBoss Messaging distribution includes a server-side JMS service, which deploys JMS queues, topics and connection factories from this file into JNDI. If you are not using JMS, or you do not need to deploy JMS objects on the server side, you will not need this file. For more information about using JMS, see <xref linkend="using-jms" />.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><filename>logging.properties</filename></term>
+ <listitem>
+ <para>
+ Configures the logging handlers used by the Java logger. For further information about configuring logging, see <xref linkend="logging" />.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><filename>log4j.xml</filename></term>
+ <listitem>
+ <para>
+ Contains configuration details for <literal>log4j</literal>, if configured.
+ </para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ <note>
+ <para>
+ When the <varname>file-deployment-enabled</varname> property in the <filename>jbm-configuration.xml</filename> configuration file is set to <literal>false</literal>, the other configuration files are not loaded. By default, <varname>file-deployment-enabled</varname> is set to <literal>true</literal>.
+ </para>
+ </note>
+ <para>
+ You can use system property substitution in all configuration files, by replacing a parameter value with the name of the system property. The following code shows system property substitution in the configuration of a connector:
+ </para>
+
+ <programlisting><connector name="netty">
+ <factory-class>org.jboss.messaging.integration.transports.netty.NettyConnectorFactory</factory-class>
+ <param key="jbm.remoting.netty.host" value="${jbm.remoting.netty.host:localhost}" type="String"/>
+ <param key="jbm.remoting.netty.port" value="${jbm.remoting.netty.port:5445}" type="Integer"/>
+</connector></programlisting>
+ <para>
+ Here, the values of <varname>jbm.remoting.netty.host</varname> and <varname>jbm.remoting.netty.port</varname> have been replaced with system properties. The values of these parameters will be replaced by the value defined by the specified system property, if available. (If the system property has no value or cannot be found, the parameter's default value — localhost or 5445, in this case — will be used instead.)
+ </para>
+ </section>
+ <section id="server.microcontainer.configuration">
+ <title>JBoss Microcontainer Beans File</title>
+ <para>
+ The stand-alone server is a set of POJOs instantiated by the lightweight JBoss Microcontainer engine.
+ </para>
+ <note>
+ <para>
+ When the server is deployed in the JBoss Application Server, a beans file is also required. This deploys a slightly different set of objects, since the application server will have preexisting security objects, etc.
+ </para>
+ </note>
+ <para>
+ The following is an example beans file from a stand-alone server:
+ </para>
+ <programlisting><?xml version="1.0" encoding="UTF-8"?>
+
+<deployment xmlns="urn:jboss:bean-deployer:2.0">
+
+<bean name="Naming" class="org.jnp.server.NamingBeanImpl"/>
+
+<!-- JNDI server. Disable this if you don't want JNDI -->
+<bean name="JNDIServer" class="org.jnp.server.Main">
+ <property name="namingInfo">
+ <inject bean="Naming"/>
+ </property>
+ <property name="port">1099</property>
+ <property name="bindAddress">localhost</property>
+ <property name="rmiPort">1098</property>
+ <property name="rmiBindAddress">localhost</property>
+</bean>
+
+<!-- MBean server -->
+<bean name="MBeanServer" class="javax.management.MBeanServer">
+ <constructor factoryClass="java.lang.management.ManagementFactory"
+ factoryMethod="getPlatformMBeanServer"/>
+</bean>
+
+<!-- The core configuration -->
+<bean name="Configuration" class="org.jboss.messaging.core.config.impl.FileConfiguration">
+</bean>
+
+<!-- The security manager -->
+<bean name="JBMSecurityManager"
+ class="org.jboss.messaging.core.security.impl.JBMSecurityManagerImpl">
+ <start ignored="true"/>
+ <stop ignored="true"/>
+</bean>
+
+<!-- The core server -->
+<bean name="MessagingServer" class="org.jboss.messaging.core.server.impl.MessagingServerImpl">
+ <start ignored="true"/>
+ <stop ignored="true"/>
+ <constructor>
+ <parameter>
+ <inject bean="Configuration"/>
+ </parameter>
+ <parameter>
+ <inject bean="MBeanServer"/>
+ </parameter>
+ <parameter>
+ <inject bean="JBMSecurityManager"/>
+ </parameter>
+ </constructor>
+</bean>
+
+<!-- The JMS server -->
+<bean name="JMSServerManager"
+ class="org.jboss.messaging.jms.server.impl.JMSServerManagerImpl">
+ <constructor>
+ <parameter>
+ <inject bean="MessagingServer"/>
+ </parameter>
+ </constructor>
+</bean>
+
+</deployment>
+ </programlisting>
+ <para>
+ The stand-alone server instantiates several POJOs in addition to the core JBoss Messaging server:
+ </para>
+ <variablelist>
+ <varlistentry>
+ <term><literal>JNDIServer</literal></term>
+ <listitem>
+ <para>
+ Lets the client lookup JMS objects from JNDI. This can be commented out or removed if JNDI is not required.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><literal>MBeanServer</literal></term>
+ <listitem>
+ <para>
+ Where the objects to be managed by the JMX management interface are registered. Normally, this is the default platform <literal>MBeanServer</literal> available in the JVM instance. This can be commented out or removed if you do not require a JMX management interface.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><literal>Configuration</literal></term>
+ <listitem>
+ <para>
+ The messaging server is configured with a Configuration object. In the default stand-alone configuration, the messaging server uses a <literal>FileConfiguration</literal> object that reads configuration details from the file system. In other configuration options, such as <literal>embedded</literal>, you may wish to provide configuration details from another source.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><literal>Security Manager</literal></term>
+ <listitem>
+ <para>
+ The messaging server uses a pluggable security manager. The default security manager reads user and role information from the <filename>jbm-users.xml</filename> file. You can replace this with a JAAS security manager or, when running within JBoss AS, the JBoss AS security manager. If you have disabled security altogether, this can be commented out or removed.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><literal>MessagingServer</literal></term>
+ <listitem>
+ <para>
+ The core server. Handles most operations.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><literal>JMSServerManager</literal></term>
+ <listitem>
+ <para>
+ Deploys any JMS objects, such as <literal>Queue</literal>, <literal>Topic</literal> and <literal>ConnectionFactory</literal> instances. Also provides a simple management API for manipulating JMS objects. If you do not need to deploy JMS queues, topics and connection factories from the server-side and do not require the JMS management interface, this can be disabled.
+ </para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ </section>
+ <section id="usingserver.mainconfig">
+ <title>The main configuration file</title>
+ <para>
+ JBoss Messaging core server configuration details are stored in the <filename>jbm-configuration.xml</filename> file. The <literal>FileConfiguration</literal> bean uses this information to configure the messaging server.
+ </para>
+ <para>
+ JBoss Messaging has many configurable attributes. The default values are appropriate in most cases, and all parameters have default values, so even a single file with an empty <literal><configuration></literal> element is a valid configuration file.
+ </para>
+ <para>
+ Configuration details are outlined in relevant chapters throughout this guide. For complete configuration details, refer to <xref linkend="configuration-index" />.
+ </para>
+ </section>
+</chapter>
Added: projects/docs/enterprise/5.0/JBoss_Messaging_2.0.0/JBoss_Messaging_User_Guide/en-US/images/architecture1.jpg
===================================================================
(Binary files differ)
Property changes on: projects/docs/enterprise/5.0/JBoss_Messaging_2.0.0/JBoss_Messaging_User_Guide/en-US/images/architecture1.jpg
___________________________________________________________________
Name: svn:mime-type
+ application/octet-stream
Added: projects/docs/enterprise/5.0/JBoss_Messaging_2.0.0/JBoss_Messaging_User_Guide/en-US/images/architecture2.jpg
===================================================================
(Binary files differ)
Property changes on: projects/docs/enterprise/5.0/JBoss_Messaging_2.0.0/JBoss_Messaging_User_Guide/en-US/images/architecture2.jpg
___________________________________________________________________
Name: svn:mime-type
+ application/octet-stream
Added: projects/docs/enterprise/5.0/JBoss_Messaging_2.0.0/JBoss_Messaging_User_Guide/en-US/images/architecture3.jpg
===================================================================
(Binary files differ)
Property changes on: projects/docs/enterprise/5.0/JBoss_Messaging_2.0.0/JBoss_Messaging_User_Guide/en-US/images/architecture3.jpg
___________________________________________________________________
Name: svn:mime-type
+ application/octet-stream
Added: projects/docs/enterprise/5.0/JBoss_Messaging_2.0.0/JBoss_Messaging_User_Guide/en-US/interoperability.xml
===================================================================
--- projects/docs/enterprise/5.0/JBoss_Messaging_2.0.0/JBoss_Messaging_User_Guide/en-US/interoperability.xml (rev 0)
+++ projects/docs/enterprise/5.0/JBoss_Messaging_2.0.0/JBoss_Messaging_User_Guide/en-US/interoperability.xml 2009-10-05 01:37:17 UTC (rev 94324)
@@ -0,0 +1,35 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<chapter id="interoperability">
+ <title>Interoperability</title>
+ <section>
+ <title>Stomp and StompConnect</title>
+ <para><ulink url="http://stomp.codehaus.org/">Stomp</ulink> is a wire protocol that allows
+ Stomp clients to communicate with Stomp Brokers. <ulink
+ url="http://stomp.codehaus.org/StompConnect">StompConnect</ulink> is a server that
+ can act as a Stomp broker and proxy the Stomp protocol to the standard JMS API.
+ Consequently, using StompConnect it is possible to turn JBM into a Stomp Broker and use
+ any of the available stomp clients. These include clients written in C, C++, c# and .net
+ etc.</para>
+ <para>To run StompConnect first start the JBoss Messaging server and make sure that it is
+ using JNDI.</para>
+ <para>Stomp requires the file <literal>jndi.properties</literal> to be available on the
+ classpath. This should look something like:</para>
+ <programlisting>java.naming.factory.initial=org.jnp.interfaces.NamingContextFactory
+java.naming.provider.url=jnp://localhost:1099
+java.naming.factory.url.pkgs=org.jboss.naming:org.jnp.interfaces</programlisting>
+ <para>Make sure this file is in the classpath along with the StompConnect jar and the JBoss
+ Messaging jars and simply run <literal>java
+ org.codehaus.stomp.jms.Main</literal>.</para>
+ <para>JBoss Messaging will shortly be implementing the Stomp protocol directly, so you won't
+ have to use StompConnect to be able to use JBoss Messaging with Stomp clients.</para>
+ </section>
+ <section>
+ <title>AMQP</title>
+ <para>AMQP support coming soon!</para>
+ </section>
+ <section>
+ <title>REST</title>
+ <para>REST support coming soon!</para>
+ </section>
+
+</chapter>
More information about the jboss-cvs-commits
mailing list