[jboss-cvs] JBoss Messaging SVN: r7004 - trunk/docs/user-manual/en.
jboss-cvs-commits at lists.jboss.org
jboss-cvs-commits at lists.jboss.org
Fri May 22 13:59:11 EDT 2009
Author: timfox
Date: 2009-05-22 13:59:11 -0400 (Fri, 22 May 2009)
New Revision: 7004
Modified:
trunk/docs/user-manual/en/appserver-integration.xml
trunk/docs/user-manual/en/client-reconnection.xml
trunk/docs/user-manual/en/clusters.xml
trunk/docs/user-manual/en/command-buffering.xml
trunk/docs/user-manual/en/configuring-transports.xml
trunk/docs/user-manual/en/connection-ttl.xml
trunk/docs/user-manual/en/core-bridges.xml
trunk/docs/user-manual/en/diverts.xml
trunk/docs/user-manual/en/duplicate-detection.xml
trunk/docs/user-manual/en/embedding-jbm.xml
trunk/docs/user-manual/en/examples.xml
trunk/docs/user-manual/en/filter-expressions.xml
trunk/docs/user-manual/en/flow-control.xml
trunk/docs/user-manual/en/ha.xml
trunk/docs/user-manual/en/intercepting-operations.xml
trunk/docs/user-manual/en/interoperability.xml
trunk/docs/user-manual/en/jms-core-mapping.xml
trunk/docs/user-manual/en/large-messages.xml
trunk/docs/user-manual/en/last-value-queues.xml
trunk/docs/user-manual/en/logging.xml
trunk/docs/user-manual/en/management.xml
trunk/docs/user-manual/en/message-expiry.xml
trunk/docs/user-manual/en/message-grouping.xml
trunk/docs/user-manual/en/paging.xml
trunk/docs/user-manual/en/perf-tuning.xml
trunk/docs/user-manual/en/persistence.xml
trunk/docs/user-manual/en/pre-acknowledge.xml
trunk/docs/user-manual/en/queue-attributes.xml
trunk/docs/user-manual/en/scheduled-messages.xml
trunk/docs/user-manual/en/security.xml
trunk/docs/user-manual/en/send-guarantees.xml
trunk/docs/user-manual/en/thread-pooling.xml
trunk/docs/user-manual/en/undelivered-messages.xml
trunk/docs/user-manual/en/using-core.xml
trunk/docs/user-manual/en/using-server.xml
trunk/docs/user-manual/en/wildcard-routing.xml
trunk/docs/user-manual/en/wildcard-syntax.xml
Log:
more on docs
Modified: trunk/docs/user-manual/en/appserver-integration.xml
===================================================================
--- trunk/docs/user-manual/en/appserver-integration.xml 2009-05-22 12:04:34 UTC (rev 7003)
+++ trunk/docs/user-manual/en/appserver-integration.xml 2009-05-22 17:59:11 UTC (rev 7004)
@@ -1,8 +1,11 @@
<?xml version="1.0" encoding="UTF-8"?>
<chapter id="appserver-integration">
<title>Application Server Integration and JavaEE</title>
- <para>JBM is fully integrated with the JBoss Application Server version 5.1. For details on
- installing JBM in the Application Server refer to Quick Start guide.</para>
+ <para>JBoss Messaging can be easily installed in JBoss Application Server 5.1 or JBoss
+ Enterprise Application Platform 5.1 or later. For details on installing JBoss Messaging in
+ the JBoss Application Server refer to quick-start guide.</para>
+ <para>JBoss Messaging can also be integrated with any other JEE compliant application server by
+ using the JBoss Messaging JCA adapter.</para>
<para>This section explains the basics behind configuring the different JEE components in the
AS.</para>
<section>
@@ -12,8 +15,8 @@
consume messages from the JBM server and also how components such as EJB's or Servlet's
can send messages.</para>
<para>The JBM JCA adapter is deployed via the <literal>jms-ra.rar</literal> archive. The
- configuration of the Adapter is found in this archive under
- <literal>META-INF/ra.xml</literal>.</para>
+ configuration of the Adapter is found in this archive under <literal
+ >META-INF/ra.xml</literal>.</para>
<para>The configuration will look something like the following:</para>
<programlisting><resourceadapter>
<resourceadapter-class>org.jboss.messaging.ra.JBMResourceAdapter</resourceadapter
@@ -99,11 +102,11 @@
</listitem>
<listitem>
<para>The configuration for the outbound part of the adapter. This is used for
- creating JMS resources within EE components</para>
+ creating JMS resources within EE components. </para>
</listitem>
<listitem>
<para>The configuration of the inbound part of the adapter. This is used for
- controlling the consumption of messages via MDB's.</para>
+ controlling the consumption of messages via MDB's. </para>
</listitem>
</orderedlist>
<section>
@@ -313,14 +316,18 @@
</section>
<section>
<title>Adapter Outbound configuration</title>
- <para>The outbound configuration should remain unchanged as they define Connection
- Factories that are used by EE components. These Connection Factories can be defined
- inside a configuration file that matches the name <literal>*-ds.xml</literal>.
- You'll find a default <literal>jms-ds.xml</literal> configuration under the
- <literal>messaging.sar</literal> directory in the Jboss AS deployment. the
- connection factories defined in the config file inherit their properties from the
- main <literal>ra.xml</literal> config but can also be overridden, the following
- example show how to define one.</para>
+ <para>The outbound configuration should remain unchanged as they define connection
+ factories that are used by JavaEE components. These Connection Factories can be
+ defined inside a configuration file that matches the name <literal
+ >*-ds.xml</literal>. You'll find a default <literal>jms-ds.xml</literal>
+ configuration under the <literal>messaging.sar</literal> directory in the Jboss AS
+ deployment. The connection factories defined in the config file inherit their
+ properties from the main <literal>ra.xml</literal> config but can also be
+ overridden, the following example show how to define one.</para>
+ <para>Please note that this configuration only applies to install the JBM resource
+ adapter in the JBoss Application Server. If you are using another JEE application
+ server please refer to your application servers documentation for how to do
+ this.</para>
<programlisting><tx-connection-factory>
<jndi-name>RemoteJmsXA</jndi-name>
<xa-transaction/>
@@ -395,17 +402,22 @@
}
}
}</programlisting>
- <para>In this example we have configured the MDB to consume from the queue named
- <literal>queue/testQueue</literal>. It is also possible to override properties for
- the inbound resource adapter here is well. Here the MDB is configured to connect to a
+ <para>In this example we have configured the MDB to consume from the queue named <literal
+ >queue/testQueue</literal>. It is also possible to override properties for the
+ inbound resource adapter here is well. Here the MDB is configured to connect to a
different server.</para>
<para>It is also possible to define these properties in the <literal>web.xml</literal>
deployment descriptor. Refer to the JBoss AS documentation on how to do this.</para>
</section>
<section>
- <title>High Availability JNDI (HAJNDI)</title>
- <para>When using JBM in a clustered environment you will need to use the HAJNDI. This will
- round robin look ups for connection factories and give load balanced connections.</para>
+ <title>High Availability JNDI (HA-JNDI)</title>
+ <para>If you are using JNDI to look-up JMS queues, topics and connection factories from a
+ cluster of servers, it is likely you will want to use HA-JNDI so that your JNDI look-ups
+ will continue to work if one or more of the servers in the cluster fail.</para>
+ <para>HA-JNDI is a JBoss Application Server service which allows you to use JNDI from
+ clients without them having to know the exact JNDI connection details of every server in
+ the cluster. This service is only available if using a cluster of JBoss Application
+ Server instances.</para>
<para>To use it use the following properties when connecting to JNDI.</para>
<programlisting>Hashtable<String, String> jndiParameters = new Hashtable<String, String>();
jndiParameters.put("java.naming.factory.initial",
@@ -414,15 +426,44 @@
"org.jboss.naming:org.jnp.interfaces");
initialContext = new InitialContext(jndiParameters);</programlisting>
- <para>For more information visit <ulink
+ <para>For more information on using HA-JNDI see the <ulink
url="http://www.jboss.org/file-access/default/members/jbossas/freezone/docs/Clustering_Guide/5/html/clustering-jndi.html"
- >here</ulink></para>
+ >JBoss Application Server clustering documentation</ulink></para>
</section>
<section>
<title>The JMS Bridge</title>
- <para>The JMS bridge allows different JMS servers from different JMS providers to be
- 'bridged' together. A bridge will have a source destination from which it receives
- messages and a target destination to which it sends messages.</para>
+ <para>JBoss Messaging includes a fully functional message bridge.</para>
+ <para>The function of the bridge is to consume messages from a source queue or topic, and
+ send them to a target queue or topic, typically on a different server.</para>
+ <para>The source and target servers do not have to be in the same cluster which makes
+ bridging suitable for reliably sending messages from one cluster to another, for
+ instance across a WAN, and where the connection may be unreliable.</para>
+ <para>A bridge is deployed inside a JBoss AS instance. The instance can be the same instance
+ as either the source or target server. Or could be on a third, separate JBoss AS
+ instance.</para>
+ <para>A bridge is deployed as an MBean inside JBoss AS. Deployment is trivial - just drop
+ the MBean descriptor into the deploy directory of a JBoss configuration which contains
+ JBoss Messaging.</para>
+ <para>An example in docs/example/bridge demonstrates a simple bridge being deployed in JBoss
+ AS, and moving messages from the source to the target destination</para>
+ <para>The bridge can also be used to bridge messages from other non JBoss Messaging JMS
+ servers, as long as they are JMS 1.1 compliant.<note>
+ <para>Don't confuse a JMS bridge with a core bridge. A JMS bridge can be used to
+ bridge any two JMS 1.1 compliant JMS providers and uses the JMS API. A <xref
+ linkend="core-bridges">core bridge</xref> is used to bridge any two JBoss
+ Messaging instances and uses the core API. Always use a core bridge if you can
+ in preference to a JMS bridge. The core bridge will typically provide better
+ performance than a JMS bridge. Also the core bridge can provide <emphasis>once
+ and only once</emphasis> delivery guarantees without using XA.</para>
+ </note></para>
+ <para>The bridge has built in resilience to failure so if the source or target server
+ connetion is lost, e.g. due to network failure, the bridge will retry connecting to the
+ source and/or target until they come back online. When it comes back online it will
+ resume operation as normal.</para>
+ <para>The bridge can be configured with an optional JMS selector, so it will only consume
+ messages matching that JMS selector</para>
+ <para>It can be configured to consume from a queue or a topic. When it consumes from a topic
+ it can be configured to consume using a non durable or durable subscription</para>
<para>The bridge is deployed by the JBoss Micro Container via a beans configuration file.
This would typically be deployed inside the JBoss Application Server and the following
example shows an example of a beans file that bridges 2 JBM servers although here they
@@ -552,28 +593,29 @@
</bean>
</deployment></programlisting>
+ <para>TODO TODO - please copy the documentation on these params from the JBM 1.4 docs</para>
<para>The main bean deployed is the <literal>JMSBridge</literal> bean. A description of each
of its constructor parameters in order follows:</para>
<itemizedlist>
<listitem>
- <para>Source Connection Factory Factory - This injects the
- <literal>SourceCFF</literal> bean that is the connection factory defined
- later in the beans file.</para>
+ <para>Source Connection Factory Factory - This injects the <literal
+ >SourceCFF</literal> bean that is the connection factory defined later in
+ the beans file.</para>
</listitem>
<listitem>
- <para>Target Connection Factory Factory - This injects the
- <literal>TargetCFF</literal> bean that is the connection factory defined
- later in the beans file.</para>
+ <para>Target Connection Factory Factory - This injects the <literal
+ >TargetCFF</literal> bean that is the connection factory defined later in
+ the beans file.</para>
</listitem>
<listitem>
- <para>Source Destination Factory Factory - This injects the
- <literal>SourceDestinationFactory</literal> bean that is used to create or
- lookup the sourcedestination.</para>
+ <para>Source Destination Factory Factory - This injects the <literal
+ >SourceDestinationFactory</literal> bean that is used to create or lookup
+ the sourcedestination.</para>
</listitem>
<listitem>
- <para>Target Destination Factory Factory - This injects the
- <literal>TargetDestinationFactory</literal> bean that is used to create or
- lookup the target destination.</para>
+ <para>Target Destination Factory Factory - This injects the <literal
+ >TargetDestinationFactory</literal> bean that is used to create or lookup
+ the target destination.</para>
</listitem>
<listitem>
<para>Source User Name - the user name to use for the source connection.</para>
@@ -604,7 +646,7 @@
</listitem>
<listitem>
<para>Batch Time - The maximum time to wait before committing a transaction anyway
- (in MS).</para>
+ (in milliseconds).</para>
</listitem>
<listitem>
<para>Subscription Name - The name of the subscription if using a durable subscriber
@@ -616,9 +658,9 @@
</listitem>
<listitem>
<para>Concatenate Message ID - If this is set the message ID from the received
- message will be concatenated as message header
- <literal>JBM_BRIDGE_MSG_ID_LIST</literal>. This is because it will change
- once the bridge forwards it. When passing through multiple bridges each ID is
+ message will be concatenated as message header <literal
+ >JBM_BRIDGE_MSG_ID_LIST</literal>. This is because it will change once the
+ bridge forwards it. When passing through multiple bridges each ID is
concatenated to the list.</para>
<note>
<para>when you receive the message you can send back a response using the
@@ -635,15 +677,14 @@
<para>In this example we have used the default provided by JBM that look up the
connection factory using JNDI. For other Application Servers or JMS providers a new
implementation may have to be provided. This can easily be done by implementing the
- interface
- <literal>org.jboss.messaging.jms.bridge.ConnectionFactoryFactory</literal>.</para>
+ interface <literal
+ >org.jboss.messaging.jms.bridge.ConnectionFactoryFactory</literal>.</para>
</section>
<section>
<title>Source and Target Destination Factories</title>
<para>Again, similarly, these are used to create or lookup up the destinations. To
- provide a new implementation simple implement
- <literal>org.jboss.messaging.jms.bridge.DestinationFactory</literal>
- interface.</para>
+ provide a new implementation simple implement <literal
+ >org.jboss.messaging.jms.bridge.DestinationFactory</literal> interface.</para>
</section>
<section>
<title>Quality Of Service</title>
@@ -696,9 +737,9 @@
</section>
<section>
<title>Example</title>
- <para>The <literal>javaee/jms-bridge</literal> example shows how to configure and
- use a JMS Bridge to send messages to the source destination and consume them
- from the target destination.</para>
+ <para>The <xref linkend="jms-bridge-example">jms bridge example</xref> shows how to
+ configure and use a JMS Bridge to send messages to the source destination and
+ consume them from the target destination.</para>
</section>
</section>
</section>
@@ -707,7 +748,7 @@
<para><emphasis>XA recovery</emphasis> deals with system or application failures to ensure
that of a transaction are applied consistently to all resources affected by the
transaction, even if any of the application processes or the machine hosting them crash
- or lose network connectivity. For more information on XA Recovery, refer to <ulink
+ or lose network connectivity. For more information on XA Recovery,please refer to <ulink
url="http://www.jboss.org/community/wiki/JBossTransactions">JBoss
Transactions</ulink>.</para>
<para>When JBoss Messaging is integrated with JBoss AS, it can take advantage of JBoss
@@ -717,7 +758,7 @@
(depending on the transaction outcome) when the server is restarted.</para>
<section>
<title>XA Recovery Configuration</title>
- <para>To enable JBoss Messaging's XA Recovery, the following property must be added to
+ <para>To enable JBoss Messagings XA Recovery, the following property must be added to
the <literal>jta</literal> section of <literal>conf/jbossts-properties.xml</literal>
of JBoss AS profiles:</para>
<programlisting>
@@ -730,15 +771,15 @@
</properties>
</programlisting>
<para>This informs the recovery manager that it can recovers JBoss Messaging XA
- Resources using the <literal>XAConnectionFactory</literal> bound to
- <literal>java:/XAConnectionFactory</literal> in JNDI. A ConnectionFactory must
- have been configured with this JNDI name in <literal>jbm-jms.xml</literal> (see
- <xref linkend="using-jms.server.configuration"/>).</para>
+ Resources using the <literal>XAConnectionFactory</literal> bound to <literal
+ >java:/XAConnectionFactory</literal> in JNDI. A ConnectionFactory must have been
+ configured with this JNDI name in <literal>jbm-jms.xml</literal> (see <xref
+ linkend="using-jms.server.configuration"/>).</para>
</section>
<section>
<title>Example</title>
- <para>The <literal>javaee/xarecovery</literal> example shows how to configure XA
- Recovery and recover messages after a server crash.</para>
+ <para>The <xref linkend="xa-recovery-example">xa recovery example</xref> shows how to
+ configure XA Recovery and recover messages after a server crash.</para>
</section>
</section>
</chapter>
Modified: trunk/docs/user-manual/en/client-reconnection.xml
===================================================================
--- trunk/docs/user-manual/en/client-reconnection.xml 2009-05-22 12:04:34 UTC (rev 7003)
+++ trunk/docs/user-manual/en/client-reconnection.xml 2009-05-22 17:59:11 UTC (rev 7004)
@@ -1,30 +1,33 @@
<?xml version="1.0" encoding="UTF-8"?>
<chapter id="client-reconnection">
<title>Client Reconnection</title>
- <para>JBoss Messaging clients can be configured to automatically reconnect to the server in the event that a failure is detected in the connection
- between the client and the server. If the client successfully reconnects, and the server still has a record of the clients session (i.e. the
- server was not restarted) then the client will transparently re-attach to the session and it will be able to resume as if nothing had happened.</para>
- <para>Client reconnnection is also used internally by components such as core bridges to allow them to reconnect to their target servers.</para>
+ <para>JBoss Messaging clients can be configured to automatically reconnect to the server in the
+ event that a failure is detected in the connection between the client and the server. If the
+ client successfully reconnects, and the server still has a record of the clients session
+ (i.e. the server was not restarted) then the client will transparently re-attach to the
+ session and it will be able to resume as if nothing had happened.</para>
+ <para>Client reconnnection is also used internally by components such as core bridges to allow
+ them to reconnect to their target servers.</para>
<para>Client reconnection is configured using the following parameters:</para>
<itemizedlist>
<listitem>
- <para><literal>retry-interval</literal>. This optional parameter determines the
- period in milliseconds between subsequent reconnection attempts, if the
- connection to the target server has failed. The default value is <literal
- >2000</literal>milliseconds.</para>
+ <para><literal>retry-interval</literal>. This optional parameter determines the period
+ in milliseconds between subsequent reconnection attempts, if the connection to the
+ target server has failed. The default value is <literal>2000</literal>
+ milliseconds.</para>
</listitem>
<listitem>
- <para><literal>retry-interval-multiplier</literal>. This optional parameter
- determines determines a multiplier to apply to the time since the last retry to
- compute the time to the next retry.</para>
- <para>This allows you to implement an <emphasis>exponential backoff</emphasis>
- between retry attempts.</para>
+ <para><literal>retry-interval-multiplier</literal>. This optional parameter determines
+ determines a multiplier to apply to the time since the last retry to compute the
+ time to the next retry.</para>
+ <para>This allows you to implement an <emphasis>exponential backoff</emphasis> between
+ retry attempts.</para>
<para>Let's take an example:</para>
- <para>If we set <literal>retry-interval</literal>to <literal>1000</literal> ms and
- we set <literal>retry-interval-multiplier</literal> to <literal>2.0</literal>,
- then, if the first reconnect attempt fails, we will wait <literal>1000</literal>
- ms then <literal>2000</literal> ms then <literal>4000</literal> ms between
- subsequent reconnection attempts.</para>
+ <para>If we set <literal>retry-interval</literal> to <literal>1000</literal> ms and we
+ set <literal>retry-interval-multiplier</literal> to <literal>2.0</literal>, then, if
+ the first reconnect attempt fails, we will wait <literal>1000</literal> ms then
+ <literal>2000</literal> ms then <literal>4000</literal> ms between subsequent
+ reconnection attempts.</para>
<para>The default value is <literal>1.0</literal> meaning each reconnect attempt is
spaced at equal intervals.</para>
</listitem>
@@ -35,28 +38,30 @@
attempts. The default value is <literal>-1</literal>.</para>
</listitem>
</itemizedlist>
- <para>If you're using JMS, and you're using the JMS Service on the server to load your JMS connection factory instances directly into JNDI, then
- you can specify these parameters in the xml configuration in <literal>jbm-jms.xml</literal>, for example:</para>
+ <para>If you're using JMS, and you're using the JMS Service on the server to load your JMS
+ connection factory instances directly into JNDI, then you can specify these parameters in
+ the xml configuration in <literal>jbm-jms.xml</literal>, for example:</para>
<programlisting>
- <connection-factory name="ConnectionFactory">
- <connector-ref connector-name="netty"/>
- <entries>
- <entry name="ConnectionFactory"/>
- <entry name="XAConnectionFactory"/>
- </entries>
- <retry-interval>1000</retry-interval>
- <retry-interval-multiplier>1.5</retry-interval-multiplier>
- <reconnect-attempts>1000</reconnect-attempts>
- </connection-factory>
+<connection-factory name="ConnectionFactory">
+<connector-ref connector-name="netty"/>
+<entries>
+ <entry name="ConnectionFactory"/>
+ <entry name="XAConnectionFactory"/>
+</entries>
+<retry-interval>1000</retry-interval>
+<retry-interval-multiplier>1.5</retry-interval-multiplier>
+<reconnect-attempts>1000</reconnect-attempts>
+</connection-factory>
</programlisting>
- <para>If you're using JMS, but instantiating your JMS connection factory directly, you can specify the params using the appopriate setter methods
- on the <literal>JBossConnectionFactory</literal> immediately after creating it.</para>
- <para>If you're using the core API and instantiating the <literal>ClientSessionFactory</literal> instance directly you can also specify the params using the appopriate setter methods
- on the <literal>ClientSessionFactory</literal> immediately after creating it.</para>
- <para>If your client does manage to reconnect but the session is no longer available on the server, for instance if the server has been restarted or
- it has timed out, then the client won't be able to re-attach, and any ExceptionListener or FailureListener instances registered on the connection
- or session will be called.</para>
-
-
-
- </chapter>
\ No newline at end of file
+ <para>If you're using JMS, but instantiating your JMS connection factory directly, you can
+ specify the params using the appopriate setter methods on the <literal
+ >JBossConnectionFactory</literal> immediately after creating it.</para>
+ <para>If you're using the core API and instantiating the <literal>ClientSessionFactory</literal>
+ instance directly you can also specify the params using the appopriate setter methods on the
+ <literal>ClientSessionFactory</literal> immediately after creating it.</para>
+ <para>If your client does manage to reconnect but the session is no longer available on the
+ server, for instance if the server has been restarted or it has timed out, then the client
+ won't be able to re-attach, and any <literal>ExceptionListener</literal> or <literal
+ >FailureListener</literal> instances registered on the connection or session will be
+ called.</para>
+</chapter>
Modified: trunk/docs/user-manual/en/clusters.xml
===================================================================
--- trunk/docs/user-manual/en/clusters.xml 2009-05-22 12:04:34 UTC (rev 7003)
+++ trunk/docs/user-manual/en/clusters.xml 2009-05-22 17:59:11 UTC (rev 7004)
@@ -10,14 +10,15 @@
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 true, this is false by default</para>
+ 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 core
- bridge (LINK) 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>
+ When a node forms a cluster connection to another node, internally it creates a <xref
+ linkend="core-bridges">core bridge</xref> 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
@@ -55,7 +56,7 @@
<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
- chapter [LINK].</para>
+ <xref linkend="configuring-transports">here</xref>.</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>
@@ -98,9 +99,10 @@
</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
- 224.0.0.0 to 239.255.255.255, inclusive. The address 224.0.0.0 is reserved
- and is not available for use. This parameter is mandatory.</para>
+ 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
@@ -113,12 +115,12 @@
</listitem>
<listitem>
<para><literal>connector-ref</literal>. This specifies the connector and
- optional backup connector that will be broadcast. Please see section [LINK]
- for more information on connectors. The connector to be broadcast is
- specified by the <literal>connector-name</literal> attribute, and the backup
- connector to be broadcast is specified by the <literal
- >backup-connector</literal> attribute. The <literal
- >backup-connector</literal> attribute is optional.</para>
+ optional backup connector that will be broadcast. Please see <xref
+ linkend="configuring-transports">here</xref> for more information on
+ connectors. The connector to be broadcast is specified by the <literal
+ >connector-name</literal> attribute, and the backup connector to be
+ broadcast is specified by the <literal>backup-connector</literal> attribute.
+ The <literal>backup-connector</literal> attribute is optional.</para>
</listitem>
</itemizedlist>
</section>
@@ -211,8 +213,7 @@
<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. For more
- information on client side connection load balancing please see [LINK].</para>
+ 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
@@ -265,8 +266,8 @@
<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
- symmetric cluster [LINK]. We have a queue called <literal>OrderQueue</literal> deployed
- on each node of the cluster.</para>
+ <xref linkend="symmetric-cluster">symmetric cluster</xref>. 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
@@ -288,7 +289,7 @@
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
+ <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>
@@ -314,8 +315,8 @@
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>
+ 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
@@ -350,7 +351,8 @@
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 chapter [LINK].</para>
+ duplicate detection please <xref linkend="duplicate-detection"
+ >here</xref>.</para>
<para>This parameter is optional and has a default value of <literal
>true</literal>.</para>
</listitem>
@@ -391,8 +393,7 @@
<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. For more information
- on discovery groups please see section [LINK].</para>
+ that this cluster connection will make connections to.</para>
</listitem>
</itemizedlist>
</section>
@@ -459,9 +460,7 @@
<para>Specifying servers explicitly</para>
</listitem>
<listitem>
- <para>Using discovery. Please see section [LINK] for an explanation on how to
- configure clients to use server discovery for discovering the list of servers to
- connect to.</para>
+ <para>Using discovery.</para>
</listitem>
</itemizedlist>
</section>
@@ -501,7 +500,7 @@
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 chapter [LINK].</para>
+ see <xref linkend="configuring-transports">here</xref>.</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>
@@ -526,8 +525,7 @@
<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 the
- chapter on connectors [LINK].</para>
+ 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
@@ -535,7 +533,7 @@
</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
+ <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 =
@@ -557,7 +555,7 @@
>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 the
- chapter on connectors [LINK].</para>
+ chapter on <xref linkend="configuring-transports">connectors</xref>.</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
@@ -613,7 +611,7 @@
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 the chapter [LINK].</para>
+ address settings please see <xref linkend="queue-attributes">here</xref>.</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>
@@ -644,7 +642,7 @@
<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>
+ <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
@@ -654,8 +652,8 @@
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 [LINK] in order to know
- what other servers in the cluster it should connect to, although it is possible to
+ 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
@@ -673,10 +671,9 @@
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 order 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>
+ 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
Modified: trunk/docs/user-manual/en/command-buffering.xml
===================================================================
--- trunk/docs/user-manual/en/command-buffering.xml 2009-05-22 12:04:34 UTC (rev 7003)
+++ trunk/docs/user-manual/en/command-buffering.xml 2009-05-22 17:59:11 UTC (rev 7004)
@@ -14,19 +14,19 @@
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>send-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>
+ connection factory instances into JNDI then this parameter can be configured in <literal
+ >jbm-jms.xml</literal> using the element <literal>send-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>
Modified: trunk/docs/user-manual/en/configuring-transports.xml
===================================================================
--- trunk/docs/user-manual/en/configuring-transports.xml 2009-05-22 12:04:34 UTC (rev 7003)
+++ trunk/docs/user-manual/en/configuring-transports.xml 2009-05-22 17:59:11 UTC (rev 7004)
@@ -275,7 +275,7 @@
</listitem>
<listitem>
<para><literal>jbm.remoting.netty.httpclientidlescanperiod</literal>. How often,
- in milliseconds, to scan for idle clients</para>
+ in milliseconds, to scan for idle clients</para>
</listitem>
<listitem>
<para><literal>jbm.remoting.netty.httpresponsetime</literal>. How long the
@@ -417,8 +417,4 @@
this using the application context of the web app if there is one.</para>
</section>
</section>
- <section>
- <title>Writing your own transport</title>
- <para>TODO</para>
- </section>
</chapter>
Modified: trunk/docs/user-manual/en/connection-ttl.xml
===================================================================
--- trunk/docs/user-manual/en/connection-ttl.xml 2009-05-22 12:04:34 UTC (rev 7003)
+++ trunk/docs/user-manual/en/connection-ttl.xml 2009-05-22 17:59:11 UTC (rev 7004)
@@ -1,14 +1,15 @@
<?xml version="1.0" encoding="UTF-8"?>
<chapter id="connection-ttl">
- <title>Dead Connections, Time To Live and Session Multiplexing</title>
+ <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 explain how to configure all the related parameters.</para>
+ 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 and
- part of its contract that it should close its resources in a controlled manner, using a
- <literal>finally</literal> block.</para>
+ <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>
@@ -58,31 +59,32 @@
</programlisting>
<para>Unfortunately users don't always write well behaved applications, and sometimes
clients 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, e.g. representing the session
- objects, hanging on the server. If these were not removed somehow then over time this
- would cause a resource leak on the server.</para>
- <para>We have to balance this 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
+ <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>. Each connection also sends a periodic "ping" to the server, when the
- server receives the "ping" it sends back "pong". Every time the server receives a ping,
- it marks the time it received that last ping against the connection. If the server
- hasn't received a ping for the time given by the TTL, then it will be automatically
- cleaned up and its server side resources removed. Basically, the TTL determines how long
- the server will keep a connection alive in the absence of a ping. Normally we configure
- the TTL to be much larger than the connection ping period so we can allow for session
- reconnections at significant times later.</para>
+ <para>JBoss Messaging makes all of this configurable. For each <literal
+ >ClientSessionFactory</literal> we define a <emphasis>connection TTL</emphasis>.
+ Each connection also sends a periodic "ping" to the server, when the server receives the
+ "ping" it sends back "pong". Every time the server receives a ping, it marks the time it
+ received that last ping against the connection. If the server hasn't received a ping for
+ the time given by the TTL, then it will be automatically cleaned up and its server side
+ resources removed. Basically, the TTL determines how long the server will keep a
+ connection alive in the absence of a ping. Normally we configure the TTL to be much
+ larger than the connection ping period so we can allow for session reconnections at
+ significant times later.</para>
<para>The ping period is defined by the <literal>PingPeriod</literal> attribute on the
<literal>ClientSessionFactory</literal> instance.</para>
<para>If you're using JMS it's defined by the <literal>PingPeriod</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>ping-period</literal>.</para>
+ the <literal>jbm-jms.xml </literal> configuration file, using the parameter <literal
+ >ping-period</literal>.</para>
<para>The default value for ping period is <literal>5000</literal>ms, i.e. 5 seconds.</para>
<para>The connection TTL is defined by the <literal>ConnectionTTL</literal> attribute on the
<literal>ClientSessionFactory</literal> instance.</para>
@@ -101,41 +103,41 @@
<para>There's a thread on the server that periodically checks all the connections to see if
they haven't been pinged for time TTL or over. The period between checking connection is
determined by the parameter<literal>connection-scan-period</literal> in the file
- <literal>jbm-configuration.xml</literal>. The default value is
- <literal>1000</literal>ms.</para>
+ <literal>jbm-configuration.xml</literal>. The default value is <literal
+ >1000</literal>ms.</para>
</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 client to be able to detect that the server has
- failed.</para>
+ for pinging, and that's for the <emphasis>client</emphasis> to be able to detect that
+ the server has failed.</para>
<para>Every <literal>ping period</literal> milliseconds a ping is sent to the server, if, by
the time the client is ready to send the next ping to the server, the previous pong
hasn't arrived then the client will consider the connection failed and will either
- initiate failover, or call any FailureListener instances (or ExceptionListeners if you
- are using JMS) depending on how it has been configured.</para>
+ 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>
</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>
+ 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 client's 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>
+ 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
Modified: trunk/docs/user-manual/en/core-bridges.xml
===================================================================
--- trunk/docs/user-manual/en/core-bridges.xml 2009-05-22 12:04:34 UTC (rev 7003)
+++ trunk/docs/user-manual/en/core-bridges.xml 2009-05-22 17:59:11 UTC (rev 7004)
@@ -14,18 +14,17 @@
servers.</para>
<para>Bridges can be configured provide <emphasis>once and only once</emphasis> delivery
guarantees even in the event of the failure of the source or the target server. They do this
- by using duplicate detection. [LINK]</para>
+ by using <xref linkend="duplicate-detection">duplicate detection</xref>.</para>
<note>
<para>Although they have similar function, don't confuse core bridges with JMS
bridges!</para>
<para>Core bridges are for linking a JBoss Messaging node with another JBoss Messaging node
and do not use the JMS API. A JMS Bridge is used for linking any two JMS 1.1 compliant
- JMS providers. So,a JMS Bridge could be used for bridging to or from a different JMS
+ JMS providers. So, a JMS Bridge could be used for bridging to or from different JMS
compliant messaging system. It's always preferable to use a core bridge if you can. Core
- bridges use duplicate detection [LINK] to provide <emphasis>once and only
- once</emphasis> guarantees. To provide the same guarantee using a JMS bridge you
- would have to use XA which has a higher overhead and is more complex to
- configure.</para>
+ bridges use duplicate detection to provide <emphasis>once and only once</emphasis>
+ guarantees. To provide the same guarantee using a JMS bridge you would have to use XA
+ which has a higher overhead and is more complex to configure.</para>
</note>
<section>
<title>Configuring Bridges</title>
@@ -48,8 +47,8 @@
backup-connector-name="backup-remote-connector"/>
</bridge>
</programlisting>
- <para>Please also note that in order for bridges to be deployed on a server, the
- <literal>clustered</literal> attribute needs to be set to <literal>true</literal> in
+ <para>Please also note that in order for bridges to be deployed on a server, the <literal
+ >clustered</literal> attribute needs to be set to <literal>true</literal> in
<literal>jbm-configuration.xml</literal>.</para>
<para>In the above example we have shown all the parameters its possible to configure for a
bridge. In practice you might use many of the defaults so it won't be necessary to
@@ -66,9 +65,9 @@
<para>The queue must already exist by the time the bridge is instantiated at
start-up.</para>
<note>
- <para>If you're using JMS then normally the JMS configuration
- <literal>jbm-jms.xml</literal>is loaded after the core configuration
- file <literal>jbm-configuration.xml</literal> is loaded. If you're bridge is
+ <para>If you're using JMS then normally the JMS configuration <literal
+ >jbm-jms.xml</literal> is loaded after the core configuration file
+ <literal>jbm-configuration.xml</literal> is loaded. If your bridge is
consuming from a JMS queue then you'll need to make sure the JMS queue is
also deployed as a core queue in the core config. Take a look at the bridge
example for an example of how this is done.</para>
@@ -82,8 +81,9 @@
<listitem>
<para><literal>filter-string</literal>. An optional filter string can be supplied.
If specified then only messages which match the filter expression specified in
- the filter string will be forwarded. The filter string follows the filter
- expression syntax as described in chapter [LINK].</para>
+ the filter string will be forwarded. The filter string follows the JBoss
+ Messaging <xref linkend="filter-expressions">filter expression
+ syntax</xref>.</para>
</listitem>
<listitem>
<para><literal>transformer-class-name</literal>. An optional transformer-class-name
@@ -98,8 +98,8 @@
<listitem>
<para><literal>retry-interval</literal>. This optional parameter determines the
period in milliseconds between subsequent reconnection attempts, if the
- connection to the target server has failed. The default value is
- <literal>2000</literal>milliseconds.</para>
+ connection to the target server has failed. The default value is <literal
+ >2000</literal>milliseconds.</para>
</listitem>
<listitem>
<para><literal>retry-interval-multiplier</literal>. This optional parameter
@@ -150,7 +150,8 @@
ignored.</para>
<para>This allows the bridge to provide a <emphasis>once and only once</emphasis>
delivery guarantee without using heavyweight methods such as XA.</para>
- <para>For more information on duplicate detection see the chapter [LINK]</para>
+ <para>For more information on duplicate detection see <xref
+ linkend="duplicate-detection">here</xref>.</para>
<para>The default value for this parameter is <literal>true</literal>.</para>
</listitem>
<listitem>
@@ -160,15 +161,15 @@
<para>A <emphasis>connector</emphasis> encapsulates knowledge of what transport to
use (TCP, SSL, HTTP etc) as well as the server connection parameters (host, port
etc). For more information about what connectors are and how to configure them
- please see the chapter [LINK].</para>
+ please see <xref linkend="configuring-transports">here</xref>.</para>
<para>The <literal>connector-ref</literal> element can be configured with two
attributes:</para>
<itemizedlist>
<listitem>
<para><literal>connector-name</literal>. This references the name of a
- connector defined in the core configuration file
- <literal>jbm-configuration.xml</literal>. The bridge will use this
- connector to make its connection to the target server. This attribute is
+ connector defined in the core configuration file <literal
+ >jbm-configuration.xml</literal>. The bridge will use this connector
+ to make its connection to the target server. This attribute is
mandatory.</para>
</listitem>
<listitem>
@@ -176,9 +177,9 @@
references the name of a connector defined in the core configuration
file <literal>jbm-configuration.xml</literal>. It represents the
connector that the bridge will fail-over onto if it detects the live
- server connection has failed. If this is specified and
- <literal>failover-on-server-shutdown</literal> is set to
- <literal>true</literal> then it will also attempt failover onto this
+ server connection has failed. If this is specified and <literal
+ >failover-on-server-shutdown</literal> is set to <literal
+ >true</literal> then it will also attempt failover onto this
connector if the live target server is cleanly shut-down.</para>
</listitem>
</itemizedlist>
Modified: trunk/docs/user-manual/en/diverts.xml
===================================================================
--- trunk/docs/user-manual/en/diverts.xml 2009-05-22 12:04:34 UTC (rev 7003)
+++ trunk/docs/user-manual/en/diverts.xml 2009-05-22 17:59:11 UTC (rev 7004)
@@ -1,6 +1,6 @@
<?xml version="1.0" encoding="UTF-8"?>
<chapter id="diverts">
- <title>Diverting and Duplicating Message Flows</title>
+ <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
@@ -9,12 +9,13 @@
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 duplicating message flows, e.g. there may be
- a requirement to monitor every order sent to an order queue.</para>
+ 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 Transformer. If specified, all diverted messages
- will have the opportunity of being transformed by the Transformer.</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
@@ -26,8 +27,8 @@
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 the divert example [LINK] for a full working example showing you how to
- configure and use diverts.</para>
+ <para>Please see the <xref linkend="divert-example">divert example</xref> 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>
@@ -49,17 +50,17 @@
</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>
+ 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 message's body or properties before it is diverted. In this example the
+ 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
@@ -69,8 +70,8 @@
<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 the old address</para>
- <para>You can therefore think of non-exclusive diverts as <emphasis>duplicating</emphasis> a
+ 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
@@ -82,10 +83,10 @@
<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>
+ <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>
Modified: trunk/docs/user-manual/en/duplicate-detection.xml
===================================================================
--- trunk/docs/user-manual/en/duplicate-detection.xml 2009-05-22 12:04:34 UTC (rev 7003)
+++ trunk/docs/user-manual/en/duplicate-detection.xml 2009-05-22 17:59:11 UTC (rev 7004)
@@ -29,11 +29,11 @@
<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 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>
+ 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
@@ -109,8 +109,8 @@
>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 see section
- [LINK]</para>
+ <para>For more information on core bridges and how to configure them see the chapter on
+ <xref linkend="core-bridges">core bridges</xref>.</para>
</section>
<section>
<title>Duplicate Detection and Cluster Connections</title>
@@ -121,14 +121,15 @@
<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 see section
- [LINK]</para>
+ <para>For more information on cluster connections and how to configure them see <xref
+ linkend="clusters">here</xref>.</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 see section [LINK]</para>
+ <para>For more information on paging and how to configure it please see <xref
+ linkend="paging">here</xref>.</para>
</section>
</chapter>
Modified: trunk/docs/user-manual/en/embedding-jbm.xml
===================================================================
--- trunk/docs/user-manual/en/embedding-jbm.xml 2009-05-22 12:04:34 UTC (rev 7003)
+++ trunk/docs/user-manual/en/embedding-jbm.xml 2009-05-22 17:59:11 UTC (rev 7004)
@@ -1,16 +1,25 @@
<?xml version="1.0" encoding="UTF-8"?>
<chapter id="embedding-jbm">
<title>Embedding JBoss Messaging</title>
- <para>JBoss Messaging was designed as a simple set of POJOs, and it was designed to be
- embeddable.</para>
+ <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. Easy and simple like that.</para>
+ 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. If you need a configuration file, use
- <literal>FileConfigurationImpl</literal></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;
@@ -20,9 +29,9 @@
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>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>
@@ -38,9 +47,9 @@
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>
+ <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;
@@ -52,9 +61,7 @@
<para>You also have the option of instantiating <literal>MessagingServerImpl</literal>
directly:</para>
<programlisting>MessagingServer server =
- new MessagingServerImpl(config,
- ManagementFactory.getPlatformMBeanServer(),
- new JBMSecurityManagerImpl());
+ new MessagingServerImpl(config);
server.start();</programlisting>
</section>
<section>
@@ -65,59 +72,26 @@
<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 with the four objects
- required to instantiate a Server:</para>
- <itemizedlist>
- <listitem>
- <para>The configuration</para>
- </listitem>
- <listitem>
- <para>A <literal>MBeanServer</literal> required by management.</para>
- </listitem>
- <listitem>
- <para>The security manager</para>
- </listitem>
- <listitem>
- <para>And the messaging server itself.</para>
- </listitem>
- </itemizedlist>
+ <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">
-
- <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 -->
+ <!-- The core server -->
<bean name="MessagingServer"
- class="org.jboss.messaging.core.server.impl.MessagingServerImpl">
- <start ignored="true"/>
- <stop ignored="true"/>
+ class="org.jboss.messaging.core.server.impl.MessagingServerImpl">
<constructor>
<parameter>
<inject bean="Configuration"/>
- </parameter>
- <parameter>
- <inject bean="MBeanServer"/>
- </parameter>
- <parameter>
- <inject bean="JBMSecurityManager"/>
- </parameter>
+ </parameter>
</constructor>
</bean>
</deployment></programlisting>
@@ -129,20 +103,21 @@
</section>
<section>
<title>Connecting to the Embedded JBoss Messaging</title>
- <para>There is no special requirement on connecting to an Embedded JBoss Messaging. As you
- are managing POJOs directly you just instantiate the factories.</para>
+ <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()), null);
+ new TransportConfiguration(
+ InVMConnectorFactory.class.getName()));
-ClientSession session = factory.createSession(false, true, true);
+ClientSession session = factory.createSession();
+
session.createQueue("example", "example", true);
ClientProducer producer = session.createProducer("example");
+
ClientMessage message = session.createClientMessage(true);
message.getBody().writeString("Hello");
@@ -154,6 +129,7 @@
ClientConsumer consumer = session.createConsumer("example");
ClientMessage msgReceived = consumer.receive();
+
System.out.println("message = " + msgReceived.getBody().readString());
session.close();</programlisting>
@@ -165,7 +141,7 @@
example illustrates that.</para>
<programlisting>JBossConnectionFactory cf =
new JBossConnectionFactory(
- new TransportConfiguration(InVMConnectorFactory.class.getName()));
+ new TransportConfiguration(InVMConnectorFactory.class.getName()));
Connection conn = cf.createConnection();
Modified: trunk/docs/user-manual/en/examples.xml
===================================================================
--- trunk/docs/user-manual/en/examples.xml 2009-05-22 12:04:34 UTC (rev 7003)
+++ trunk/docs/user-manual/en/examples.xml 2009-05-22 17:59:11 UTC (rev 7004)
@@ -1,10 +1,10 @@
<?xml version="1.0" encoding="UTF-8"?>
<chapter id="examples">
<title>Examples</title>
- <para>The JBoss Messaging distribution comes with a wide variety of examples demonstrating many
- of the features in an easy to use, fully functional examples.</para>
+ <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
+ 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
@@ -12,9 +12,11 @@
<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>
+ 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>
+ <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
@@ -23,18 +25,18 @@
<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
- ExceptionListener with JBoss Messaging which will be called by JBoss Messaging in
- the event that connection failure is detected.</para>
- <para>The code in the ExceptionListener 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
+ <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>
+ <section id="automatic-failover">
<title>Automatic (Transparent) Failover</title>
<para>This example demonstrates two servers coupled as a live-backup pair for high
availability (HA), and a client connection transparently failing over from live to
@@ -46,24 +48,25 @@
sending and consuming messages.</para>
</section>
<section>
- <title>Automatic Reconnect Same Server</title>
+ <title>Automatic Reconnect</title>
<para>This example demonstrates how JBoss Messaging connections can be configured to be
- resilient to temporary network failures. 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
- ExceptionListener 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>
+ 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>
<title>Browser</title>
- <para>This example shows you how to use a JMS QueueBrowser with JBoss Messaging.</para>
+ <para>This 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 QueueBrowser 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>
+ <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>
<title>Core Bridge Example</title>
@@ -77,19 +80,19 @@
</section>
<section>
<title>Client Kickoff</title>
- <para>This example shows how to kick off a client connected to JBoss Messaging using
- JMX.</para>
+ <para>This 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>This example demonstrates how subsequent connections created from a JMS Connection
- Factory 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>
+ <para>This 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 Topic</title>
- <para>This example demonstrates a JMS Topic deployed on two different nodes. The two
+ <para>This 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
@@ -115,10 +118,10 @@
<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 ad infinitum in quick succession, using up valuable CPU and network
+ re-attempted in quick succession, using up valuable CPU and network
resources.</para>
</section>
- <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
@@ -129,7 +132,7 @@
<para>This 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
+ <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
@@ -143,17 +146,19 @@
</section>
<section>
<title>HTTP Transport</title>
- <para>This example shows you how to configure JBoss Messaging to use HTTP protocol as
- its transport layer.</para>
+ <para>This 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 ConnectionFactory, Queue and Topic instances are
- looked up from JNDI before being used by the client code. This objects are called
- "administered objects" in JMS specification terminology.</para>
+ <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.</para>
+ administered objects on the client side so you don't have to use JNDI for
+ JMS.</para>
</section>
<section>
<title>Interceptor</title>
@@ -185,9 +190,9 @@
<title>Last-Value Queue</title>
<para>This 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
+ 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>
@@ -208,11 +213,11 @@
<section>
<title>Management Notification</title>
<para>This example shows how to receive management notifications from JBoss Messaging
- using JMS Messages. JBoss Messaging servers emit management notifications when
+ 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>
+ <section id="consumer-rate-limiting-example">
<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
@@ -240,7 +245,8 @@
<section>
<title>Message Group</title>
<para>This example shows you how to configure and use message groups with JBoss
- Messaging. Message groups are sets of messages that has the following
+ 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>
@@ -255,57 +261,65 @@
</itemizedlist>
</para>
</section>
- <section>
+ <section id="producer-rate-limiting-example">
<title>Message Producer Rate Limiting</title>
<para>This 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>
<title>Message Priority</title>
- <para>Message Priority carries the delivery preference of messages. It can be retrieved
- by the message's standard header field 'JMSPriority' as defined in JMS specification
- version 1.1. 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. 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>
+ <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>This example demonstrates message redistribution between queues with the same name
deployed in different nodes of a cluster.</para>
</section>
- <section>
+ <section id="no-consumer-buffering-example">
<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. 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>
+ 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>
<title>Paging</title>
- <para>This example shows how JBoss Messaging would avoid running out of resources by
- paging messages.</para>
+ <para>This 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>
<title>Pre-Acknowledge</title>
- <para>Standard JMS supports three acknowledgement modes: AUTO_ACKNOWLEDGE,
- CLIENT_ACKNOWLEDGE, and DUPS_OK_ACKNOWLEDGE. For a full description on these modes
- please consult the JMS specification, or any JMS tutorial.</para>
+ <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 soes
- this.</para>
+ 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>
+ <para>A simple example demonstrating a JMS queue.</para>
</section>
<section>
<title>Queue Requestor</title>
@@ -317,21 +331,29 @@
with queue consumers.</para>
</section>
<section>
- <title>Request-Reply</title>
- <para>A simple example showing the JMS request-reply pattern.</para>
+ <title>Request-Response</title>
+ <para>A simple example showing the JMS request-response pattern.</para>
</section>
<section>
<title>Scheduled Message</title>
<para>This example shows you how to send a scheduled message to a JMS Queue with JBoss
- Messaging.</para>
+ Messaging. Scheduled messages won't get delivered until a specified time in the
+ future.</para>
</section>
<section>
<title>Security</title>
- <para>This example shows you how configure and use security with JBoss Messaging.</para>
+ <para>This 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>This 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>This example shows you how to configure a JBoss Messaging queue with static
+ <para>This example shows you how to configure a JBoss Messaging core queue with static
message selectors (filters).</para>
</section>
<section>
@@ -361,9 +383,9 @@
</section>
<section>
<title>Topic</title>
- <para>A simple example demonstrating a JMS Topic.</para>
+ <para>A simple example demonstrating a JMS topic.</para>
</section>
- <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
@@ -408,11 +430,11 @@
</section>
<section>
<title>Core API Examples</title>
- <para>To run a Core API example, simply <literal>cd</literal> into the appropriate example
+ <para>To run a core example, simply <literal>cd</literal> into the appropriate example
directory and type <literal>ant</literal></para>
<section>
<title>Embedded</title>
- <para>This example shows how to embed the JBoss Messaging Server within your own
+ <para>This example shows how to embed the JBoss Messaging server within your own
code.</para>
</section>
</section>
@@ -434,9 +456,9 @@
<section>
<title>Resource Adapter Configuration</title>
<para>This example demonstrates how to configure several properties on the JBoss
- Messaging Resource Adapter.</para>
+ Messaging JCA resource adaptor.</para>
</section>
- <section>
+ <section id="jms-bridge-example">
<title>JMS Bridge</title>
<para>An example demonstrating the use of the JBoss Messaging JMS bridge.</para>
</section>
@@ -448,7 +470,7 @@
<title>Servlet Transport</title>
<para>An example of how to use the JBoss Messaging servlet transport.</para>
</section>
- <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>
Modified: trunk/docs/user-manual/en/filter-expressions.xml
===================================================================
--- trunk/docs/user-manual/en/filter-expressions.xml 2009-05-22 12:04:34 UTC (rev 7003)
+++ trunk/docs/user-manual/en/filter-expressions.xml 2009-05-22 17:59:11 UTC (rev 7004)
@@ -3,8 +3,8 @@
<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 very similar to the syntax used for JMS selectors. For documentation on JMS selector
- syntax please the JMS javadoc for <ulink
+ <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>
@@ -16,14 +16,18 @@
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 the section [LINK]</para>
+ <para>Core bridges can be defined with an optional filter expression, only matching
+ messages will be bridged. See the chapter on <xref linkend="core-bridges"
+ >bridges</xref>.</para>
</listitem>
<listitem>
<para>Diverts can be defined with an optional filter expression, only matching messages
- will be diverted. See the section [LINK]</para>
+ will be diverted. See the chapter on <xref linkend="diverts">diverts</xref>.</para>
</listitem>
- <listitem><para>Filter are also used programmatically when creating consumers, queues and in several places in the management API.</para></listitem>
+ <listitem>
+ <para>Filter are also used programmatically when creating consumers, queues and in
+ several places in the <xref linkend="management">management</xref> API.</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
@@ -38,18 +42,23 @@
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>
+ <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>
+ <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>
+ <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>
+ <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>
+ <para>Any other identifiers used in core filter expressions will be assumed to be properties of
+ the message.</para>
</chapter>
Modified: trunk/docs/user-manual/en/flow-control.xml
===================================================================
--- trunk/docs/user-manual/en/flow-control.xml 2009-05-22 12:04:34 UTC (rev 7003)
+++ trunk/docs/user-manual/en/flow-control.xml 2009-05-22 17:59:11 UTC (rev 7004)
@@ -1,16 +1,16 @@
<?xml version="1.0" encoding="UTF-8"?>
<chapter id="flow-control">
<title>Flow Control</title>
- <para>JBoss Messaging allows the user to restrict how fast messages are delivered between both
- client and server and also between server and client.</para>
+ <para>Flow control is used to limit the flow of data between a client and server, or a server and
+ a server in order to prevent the client or server being overwhelmed with data.</para>
<section>
<title>Consumer Flow Control</title>
- <para>This controls the flow of messages between the server and the client. For performance
- reasons clients buffer messages before delivering to the consumer via the
- <literal>receive()</literal> method or asynchronously via a message listener. If the
- consumer cannot process messages as fast as they are being delivered and stored in the
- internal buffer, then you could end up with a situation where messages just keep building
- up and are not processed for a long time. </para>
+ <para>This controls the flow of data between the server and the client as the client consumes
+ messages. For performance reasons clients normally buffer messages before delivering to the
+ consumer via the <literal>receive()</literal> method or asynchronously via a message
+ listener. If the consumer cannot process messages as fast as they are being delivered and
+ stored in the internal buffer, then you could end up with a situation where messages just
+ keep building up and are not processed for a long time. </para>
<section id="flow-control.consumer.window">
<title>Window-Based Flow Control</title>
<para>By default, JBoss Messaging consumers buffer messages from the server in a client
@@ -31,7 +31,9 @@
<para><literal>-1</literal> for an <emphasis>unbounded</emphasis> buffer</para>
</listitem>
<listitem>
- <para><literal>0</literal> to not buffer any messages.</para>
+ <para><literal>0</literal> to not buffer any messages. See the <xref
+ linkend="no-consumer-buffering-example">no consumer buffering example</xref>
+ for working example of this.</para>
</listitem>
<listitem>
<para><literal>>0</literal> for a buffer with the given maximum size in
@@ -65,16 +67,16 @@
At this point there are still messages awaiting to be processed by the slow
consumer which could be being consumed by the other consumer.</para>
<para>To allow slow consumers, set the <literal>consumer-window-size</literal> to
- 0 (for no buffer at all) or 1 (to buffer only 1 message). This will prevent the
- slow consumer from buffering any messages on the client side. Messages will
- remain on the server side ready to be consumed by other consumers.</para>
+ 0 (for no buffer at all). This will prevent the slow consumer from buffering
+ any messages on the client side. Messages will remain on the server side ready
+ to be consumed by other consumers.</para>
</listitem>
</varlistentry>
</variablelist>
<para>Most of the consumers cannot be clearly identified as fast or slow consumers but are
in-between. In that case, setting the value of <literal>consumer-window-size</literal>
to optimize performance depends on the messaging use case and requires benchmarks to
- find the optimal value. </para>
+ find the optimal value, but a value of 1MiB is fine in most cases.</para>
<section id="flow-control.core.api">
<title>Using Core API</title>
<para>If JBoss Messaging Core API is used, the consumer window size is specified by
@@ -114,15 +116,17 @@
This is a form of throttling and can be used to make sure that a consumer never consumes
messages at a rate faster than the rate specified. </para>
<para>The rate must be a positive integer to enable and is the maximum desired message
- consumption rate specified in units of messages per second. Setting this to
- <literal>-1</literal> disables rate limited flow control. The default value is
- <literal>-1</literal>.</para>
+ consumption rate specified in units of messages per second. Setting this to <literal
+ >-1</literal> disables rate limited flow control. The default value is <literal
+ >-1</literal>.</para>
+ <para>Please see the <xref linkend="consumer-rate-limiting-example">consumer rate limiting
+ example</xref> for a working example of this.</para>
<section id="flow-control.rate.core.api">
<title>Using Core API</title>
- <para>If the JBoss Messaging core API is being used the rate can be set via the
- <literal>ClientSessionFactory.setConsumerMaxRate(int consumerMaxRate)</literal>
- method or alternatively via some of the
- <literal>ClientSession.createConsumer()</literal> methods. </para>
+ <para>If the JBoss Messaging core API is being used the rate can be set via the <literal
+ >ClientSessionFactory.setConsumerMaxRate(int consumerMaxRate)</literal> method or
+ alternatively via some of the <literal>ClientSession.createConsumer()</literal>
+ methods. </para>
</section>
<section>
<title>Using JMS</title>
@@ -160,7 +164,8 @@
</section>
<section>
<title>Producer flow control</title>
- <para>JBoss Messaging allows producers to be created which limit</para>
+ <para>JBoss Messaging also can limit the amount of data sent from a client to a server to
+ prevent the server being overwhelmed.</para>
<section>
<title>Window based flow control</title>
<para>JBoss Messaging clients maintain a buffer of commands that have been sent to the
@@ -174,15 +179,17 @@
units of messages per second. By specifying such a rate, JBoss Messaging will ensure
that producer never produces messages at a rate higher than that specified.</para>
<para>The rate must be a positive integer to enable and is the maximum desired message
- consumption rate specified in units of messages per second. Setting this to
- <literal>-1</literal> disables rate limited flow control. The default value is
- <literal>-1</literal>.</para>
+ consumption rate specified in units of messages per second. Setting this to <literal
+ >-1</literal> disables rate limited flow control. The default value is <literal
+ >-1</literal>.</para>
+ <para>Please see the <xref linkend="producer-rate-limiting-example">producer rate limiting
+ example</xref> for a working example of this.</para>
<section id="flow-control.producer.rate.core.api">
<title>Using Core API</title>
- <para>If the JBoss Messaging core API is being used the rate can be set via the
- <literal>ClientSessionFactory.setProducerMaxRate(int consumerMaxRate)</literal>
- method or alternatively via some of the
- <literal>ClientSession.createProducer()</literal> methods. </para>
+ <para>If the JBoss Messaging core API is being used the rate can be set via the <literal
+ >ClientSessionFactory.setProducerMaxRate(int consumerMaxRate)</literal> method or
+ alternatively via some of the <literal>ClientSession.createProducer()</literal>
+ methods. </para>
</section>
<section>
<title>Using JMS</title>
@@ -202,10 +209,6 @@
via the <literal>JBossConnectionFactory.setProducerMaxRate(int
consumerMaxRate)</literal> method.</para>
</section>
- <section>
- <title>Example</title>
- <para>[LINK] to producer rate limit example</para>
- </section>
</section>
</section>
</chapter>
Modified: trunk/docs/user-manual/en/ha.xml
===================================================================
--- trunk/docs/user-manual/en/ha.xml 2009-05-22 12:04:34 UTC (rev 7003)
+++ trunk/docs/user-manual/en/ha.xml 2009-05-22 17:59:11 UTC (rev 7004)
@@ -34,9 +34,9 @@
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>
+ 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 -->
@@ -73,12 +73,12 @@
<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>
- tmay 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>
+ tmay 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
@@ -95,8 +95,8 @@
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>. It's default value is
- <literal>30000</literal> milliseconds.</para>
+ setting <literal>queue-activation-timeout</literal>. It's default value is <literal
+ >30000</literal> milliseconds.</para>
</section>
</section>
<section id="ha.client.automatic">
@@ -127,12 +127,13 @@
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 [LINK].</para>
+ 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">here</xref>.</para>
</section>
<section>
<title>Application-level client failover</title>
@@ -146,17 +147,17 @@
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> wil 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
- HA-JNDI [link] to ensure that the new connection factory is looked up from a different
+ <literal>ExceptionListener</literal> class on the JMS connection. The <literal
+ >ExceptionListener</literal> wil 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 HA-JNDI
+ [link] 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 example [LINK].</para>
+ <para>For a working example of application-level failover please see <xref
+ linkend="application-level-failover">this</xref> example.</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>
- <para>For a fully functional example of application-level failover please see [LINK].</para>
</section>
</chapter>
Modified: trunk/docs/user-manual/en/intercepting-operations.xml
===================================================================
--- trunk/docs/user-manual/en/intercepting-operations.xml 2009-05-22 12:04:34 UTC (rev 7003)
+++ trunk/docs/user-manual/en/intercepting-operations.xml 2009-05-22 17:59:11 UTC (rev 7004)
@@ -1,8 +1,10 @@
<?xml version="1.0" encoding="UTF-8"?>
<chapter id="intercepting-operations">
<title>Intercepting Operations</title>
- <para>JBoss Messaging supports <emphasis>interceptors</emphasis> to add behavior into the
- messaging server.</para>
+ <para>JBoss Messaging supports <emphasis>interceptors</emphasis> to intercept packets entering
+ and leaving the server. Any supplied interceptors would be called for any packet entering or
+ leaving the server, this allows custom code to be executed, e.g. for auditing packets,
+ filtering or other reasons. Interceptors can change the packets they intercept.</para>
<section>
<title>Implementing The Interceptors</title>
<para>A interceptor must implement the <literal>Interceptor interface</literal>:</para>
Modified: trunk/docs/user-manual/en/interoperability.xml
===================================================================
--- trunk/docs/user-manual/en/interoperability.xml 2009-05-22 12:04:34 UTC (rev 7003)
+++ trunk/docs/user-manual/en/interoperability.xml 2009-05-22 17:59:11 UTC (rev 7004)
@@ -3,13 +3,15 @@
<title>Interoperability</title>
<section>
<title>Stomp and StompConnect</title>
- <para>Stomp is a wire protocol that allows stomp clients from to communicate with Stomp
- Brokers. 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. For more information on Stomp and StompConnect go to <ulink
- url="http://stomp.codehaus.org/Home"/></para>
- <para>To run Stomp first start the JBoss Messaging server and make sure that it is using
- JNDI.</para>
+ <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.
+ Consequenly, 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
@@ -18,5 +20,16 @@
<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>
Modified: trunk/docs/user-manual/en/jms-core-mapping.xml
===================================================================
--- trunk/docs/user-manual/en/jms-core-mapping.xml 2009-05-22 12:04:34 UTC (rev 7003)
+++ trunk/docs/user-manual/en/jms-core-mapping.xml 2009-05-22 17:59:11 UTC (rev 7004)
@@ -1,32 +1,32 @@
<?xml version="1.0" encoding="UTF-8"?>
<chapter id="jms-core-mapping">
- <title>Mapping JMS to Core API</title>
- <para>This chapter describes how JMS destinations are mapped to JBoss Messaging Core
- resources</para>
- <para>JBoss Messaging Core is JMS agnostic. It does not have any concept of a JMS Topic. A JMS
- Topic is implemented in Core as an address (the topic name) with zero or more queues bound
+ <title>Mapping JMS Concepts to the Core API</title>
+ <para>This chapter describes how JMS destinations are mapped to JBoss Messaging core
+ queues.</para>
+ <para>JBoss Messaging core is JMS-agnostic. It does not have any concept of a JMS topic. A JMS
+ topic is implemented in core as an address (the topic name) with zero or more queues bound
to it. Each queue bound to that address represents a topic subscription. Likewise, a JMS
- Queue is implemented as an address (the JMS Queue name) with one single queue bound to it
- which represents the JMS Queue.</para>
- <para>By convention, all JMS Queues map to core queues where the core queue name has the string
- <literal>jms.queue.</literal> prepended to it. E.g. the JMS Queue with the name
+ queue is implemented as an address (the JMS queue name) with one single queue bound to it
+ which represents the JMS queue.</para>
+ <para>By convention, all JMS queues map to core queues where the core queue name has the string
+ <literal>jms.queue.</literal> prepended to it. E.g. the JMS queue with the name
"orders.europe" would map to the core queue with the name "jms.queue.orders.europe". The
address at which the core queue is bound is also given by the core queue name.</para>
- <para>For JMS Topics the address at which the queues that represent the subscriptions are bound
- is given by prepending the string "jms.topic." to the name of the JMS Topic. E.g. the JMS
- Topic with name "news.europe" would map to the core address "jms.topic.news.europe"</para>
- <para>In other words if you send a JMS Message to a JMS Queue with name "orders.europe" it will
+ <para>For JMS topics the address at which the queues that represent the subscriptions are bound
+ is given by prepending the string "jms.topic." to the name of the JMS topic. E.g. the JMS
+ topic with name "news.europe" would map to the core address "jms.topic.news.europe"</para>
+ <para>In other words if you send a JMS message to a JMS queue with name "orders.europe" it will
get routed on the server to any core queues bound to the address "jms.queue.orders.europe".
- If you send a JMS Message to a JMS Topic with name "news.europe" it will get routed on the
+ If you send a JMS message to a JMS topic with name "news.europe" it will get routed on the
server to any core queues bound to the address "jms.topic.news.europe".</para>
<para>If you want to configure settings for a JMS Queue with the name "orders.europe", you need
to configure the corresponding core queue "jms.queue.orders.europe":</para>
<programlisting>
- <!-- expired messages in JMS Queue "orders.europe"
- will be sent to the JMS Queue "expiry.europe" -->
- <address-setting match="jms.queue.orders.europe">
- <expiry-address>jms.queue.expiry.europe</expiry-address>
- ...
- </address-setting>
+<!-- expired messages in JMS Queue "orders.europe"
+ will be sent to the JMS Queue "expiry.europe" -->
+<address-setting match="jms.queue.orders.europe">
+ <expiry-address>jms.queue.expiry.europe</expiry-address>
+ ...
+</address-setting>
</programlisting>
</chapter>
Modified: trunk/docs/user-manual/en/large-messages.xml
===================================================================
--- trunk/docs/user-manual/en/large-messages.xml 2009-05-22 12:04:34 UTC (rev 7003)
+++ trunk/docs/user-manual/en/large-messages.xml 2009-05-22 17:59:11 UTC (rev 7004)
@@ -1,20 +1,25 @@
<?xml version="1.0" encoding="UTF-8"?>
<chapter id="large-messages">
<title>Large Messages</title>
- <para>JBoss Messaging supports sending and receiving of arbitrarily large messages even when
- larger than would fit in the client's or server's memory. The only limit is the disk
- space.</para>
- <para>Large messages are fragmented into smaller pieces and sent to the server individually. The
- server persists these parts to disk and delivers them to a consumer in the same fashion. The
- consumer then reconstructs the original message before final delivery. Flow control (<xref
- linkend="flow-control"/>) is used on the transmission to prevent overusing the channel
- or running out of memory during the transmission process, so it is possible to send and
- receive very large messages without effecting any other messages being delivered. </para>
- <para>For example, it is possible to send an 8GiB message even if you only had 50MiB of RAM on
- either client and server. </para>
+ <para>JBoss Messaging supports sending and receiving of huge messages, even when the client and
+ server are running with limited memory. The only limit to the size of a message that can be
+ sent or consumed is the amount of disk space you have available. We have tested sending and
+ consuming messages up to 8 GiB in size with a client and server running in just 50MiB of
+ RAM!</para>
+ <para>To send a large message, the user can set an <literal>InputStream</literal> on a message
+ body, and when that message is sent, JBoss Messaging will read the <literal
+ >InputStream</literal>. A <literal>FileInputStream</literal> could be used for example
+ to send a huge message from a huge file on disk.</para>
+ <para>As the <literal>InputStream</literal> is read the data is sent to the server as a stream
+ of fragments. The server persists these fragments to disk as it receives them and when the
+ time comes to deliver them to a consumer they are read back of the disk, also in fragments
+ and sent down the wire. When the consumer receives a large message it initially receives
+ just the message with an empty body, it can then set an <literal>OutputStream</literal> on
+ the message to stream the huge message body to a file on disk or elsewhere. At no time is
+ the entire message body stored fully in memory, either on the client or the server.</para>
<section id="large.message.configuring">
<title>Configuring the server</title>
- <para>Large messages are stored on a disk folder on the server side, as configured on the
+ <para>Large messages are stored on a disk directory on the server side, as configured on the
main configuration file.</para>
<para>The configuration property <literal>large-messages-directory</literal> specifies where
large messages are stored.</para>
@@ -30,14 +35,15 @@
</configuration</programlisting>
<para>By default the large message directory is <literal>data/largemessages</literal></para>
+ <para>For the best performance we recommend large messages directory is stored on a
+ different physical volume to the message journal or paging directory.</para>
</section>
<section>
<title>Setting the limits</title>
- <para>The definition of what is a large message is done on the session factory. For example,
- you may configure a factory on the http transport considering a message as large when
- its size is greater than 10KiB and another one on the socket transport considering
- messages greater than 200KiB.</para>
- <para>By default the min large message size is 100KiB.</para>
+ <para>Any message large than a certain size is considered a large message. Large messages
+ will be split up and sent in fragments. This is determined by the parameter <literal
+ >min-large-message-size</literal></para>
+ <para>The default value is 100KiB.</para>
<section id="large-messages.core.config">
<title>Using Core API</title>
<para>If the JBoss Messaging Core API is used, the minimal large message size is
@@ -51,7 +57,7 @@
</section>
<section>
<title>Using JMS</title>
- <para>If JNDI is used to look up the connection factory, the minimal large message size
+ <para>If JNDI is used to look up the connection factory, the minimum large message size
is specified in <literal>jbm-jms.xml</literal></para>
<programlisting>...
<connection-factory name="ConnectionFactory">
@@ -64,9 +70,9 @@
<min-large-message-size>250000</min-large-message-size>
</connection-factory>
...</programlisting>
- <para>If the connection factory is being instantiate directly, the minimal large message
- size is specified by
- <literal>JBossConnectionFactory.setMinLargeMessageSize</literal>.</para>
+ <para>If the connection factory is being instantiated directly, the minimum large
+ message size is specified by <literal
+ >JBossConnectionFactory.setMinLargeMessageSize</literal>.</para>
</section>
</section>
<section>
@@ -76,22 +82,22 @@
<para>These streams are then used directly for sending (input streams) and receiving (output
streams) messages.</para>
<para>When receiving messages there are 2 ways to deal with the output stream you may choose
- to block while the output stream is recovered using the method
- <literal>ClientMessage.saveOutputStream</literal> or alternatively using the method
- <literal>ClientMessage.setOutputstream</literal> which will asynchronously write the
- message to the stream. If you choose the latter the consumer must be kept alive until
- the message has been fully received.</para>
+ to block while the output stream is recovered using the method <literal
+ >ClientMessage.saveOutputStream</literal> or alternatively using the method <literal
+ >ClientMessage.setOutputstream</literal> which will asynchronously write the message
+ to the stream. If you choose the latter the consumer must be kept alive until the
+ message has been fully received.</para>
<para>You can use any kind of stream you like. The most common use case is to send files
- stored in your disk, but you could also send things like JDBC Blobs,
- <literal>SocketInputStream</literal>, things you recovered from
- <literal>HTTPRequests</literal> etc. Anything as long as it implements
- <literal>java.io.InputStream</literal> for sending messages or
- <literal>java.io.OutputStream</literal> for receiving them.</para>
+ stored in your disk, but you could also send things like JDBC Blobs, <literal
+ >SocketInputStream</literal>, things you recovered from <literal
+ >HTTPRequests</literal> etc. Anything as long as it implements <literal
+ >java.io.InputStream</literal> for sending messages or <literal
+ >java.io.OutputStream</literal> for receiving them.</para>
<section>
<title>Streaming over Core API</title>
- <para>The following table shows a list of methods available at
- <literal>ClientMessage</literal> which are also available through JMS by the use
- of object properties.</para>
+ <para>The following table shows a list of methods available at <literal
+ >ClientMessage</literal> which are also available through JMS by the use of
+ object properties.</para>
<table frame="topbot" id="large-messages.ClientMessageAPI">
<title>org.jboss.messaging.core.client.ClientMessage API</title>
<tgroup cols="3">
@@ -108,28 +114,27 @@
<tbody>
<row>
<entry>setBodyInputStream(InputStream)</entry>
- <entry>Set the InputStream used on a message that will be sent over a
- producer</entry>
+ <entry>Set the InputStream used to read a message body when sending
+ it.</entry>
<entry>JMS_JBM_InputStream</entry>
</row>
<row>
<entry>setOutputStream(OutputStream)</entry>
- <entry>Set the OutputStream that will receive the content of a message
- received in a non blocking way</entry>
+ <entry>Set the OutputStream that will receive the body of a message.
+ This method does not block.</entry>
<entry>JMS_JBM_OutputStream</entry>
</row>
<row>
<entry>saveOutputStream(OutputStream)</entry>
- <entry>Save the content of the message to the
- <literal>OutputStream</literal>. It will block until the entire
- content is transferred to the
- <literal>OutputStream</literal>.</entry>
+ <entry>Save the body of the message to the <literal
+ >OutputStream</literal>. It will block until the entire content
+ is transferred to the <literal>OutputStream</literal>.</entry>
<entry>JMS_JBM_SaveStream</entry>
</row>
</tbody>
</tgroup>
</table>
- <para> Set the output stream when receiving a core message: </para>
+ <para>To set the output stream when receiving a core message: </para>
<programlisting>
...
ClientMessage msg = consumer.receive(...);
@@ -191,17 +196,17 @@
// This won't wait the stream to finish. You need to keep the consumer active.
messageReceived.setObjectProperty("JMS_JBM_InputStream", bufferedOutput);
</programlisting>
- <warning>
- <para>When using JMS, Streaming Large Messages is only supported on
- <literal>StreamMessage</literal> and <literal>BytesMessage</literal>.</para>
- </warning>
+ <note>
+ <para>When using JMS, Streaming large messages are only supported on <literal
+ >StreamMessage</literal> and <literal>BytesMessage</literal>.</para>
+ </note>
</section>
</section>
<section>
<title>Streaming Alternative</title>
- <para>If you choose not to use the <literal>InputStream</literal> or
- <literal>OutputStream</literal> capability of JBoss Messaging You could still access
- the data directly in an alternative fashion.</para>
+ <para>If you choose not to use the <literal>InputStream</literal> or <literal
+ >OutputStream</literal> capability of JBoss Messaging You could still access the
+ data directly in an alternative fashion.</para>
<para>On the Core API just get the bytes of the body as you normally would.</para>
<programlisting>ClientMessage msg = consumer.receive();
@@ -251,8 +256,8 @@
</section>
<section id="large-messages.example">
<title>Large message example</title>
- <para>The <ulink url="../../../../examples/jms/large-message/readme.html"
- ><literal>large-message</literal> Example</ulink> shows how large message is
- configured and used with JMS.</para>
+ <para>The <ulink url="../../../../examples/jms/large-message/readme.html"><literal
+ >large-message</literal> Example</ulink> shows how large message is configured
+ and used with JMS.</para>
</section>
</chapter>
Modified: trunk/docs/user-manual/en/last-value-queues.xml
===================================================================
--- trunk/docs/user-manual/en/last-value-queues.xml 2009-05-22 12:04:34 UTC (rev 7003)
+++ trunk/docs/user-manual/en/last-value-queues.xml 2009-05-22 17:59:11 UTC (rev 7004)
@@ -10,9 +10,9 @@
<title>Configuring Last-Value Queues</title>
<para>Last-value queues are defined in the address-setting configuration:</para>
<programlisting>
- <address-setting match="jms.queue.lastValueQueue">
- <last-value-queue>true</last-value-queue>
- </address-setting>
+<address-setting match="jms.queue.lastValueQueue">
+ <last-value-queue>true</last-value-queue>
+</address-setting>
</programlisting>
<para>By default, <literal>last-value-queue</literal> is false. Address wildcards can be used
to configure Last-Value queues for a set of addresses (see <xref linkend="wildcard-syntax"
@@ -26,24 +26,24 @@
<para>For example, if two messages with the same value for the Last-Value property are sent to
a Last-Value queue, only the latest message will be kept in the queue:</para>
<programlisting>
- // send 1st message with Last-Value property set to STOCK_NAME
- TextMessage message =
- session.createTextMessage("1st message with Last-Value property set");
- message.setStringProperty("_JBM_LVQ_NAME", "STOCK_NAME");
- producer.send(message);
+// send 1st message with Last-Value property set to STOCK_NAME
+TextMessage message =
+ session.createTextMessage("1st message with Last-Value property set");
+message.setStringProperty("_JBM_LVQ_NAME", "STOCK_NAME");
+producer.send(message);
- // send 2nd message with Last-Value property set to STOCK_NAME
- message =
- session.createTextMessage("2nd message with Last-Value property set");
- message.setStringProperty("_JBM_LVQ_NAME", "STOCK_NAME");
- producer.send(message);
-
- ...
-
- // only the 2nd message will be received: it is the latest with
-the Last-Value property set
- TextMessage messageReceived = (TextMessage)messageConsumer.receive(5000);
- System.out.format("Received message: %s\n", messageReceived.getText());
+// send 2nd message with Last-Value property set to STOCK_NAME
+message =
+ session.createTextMessage("2nd message with Last-Value property set");
+message.setStringProperty("_JBM_LVQ_NAME", "STOCK_NAME");
+producer.send(message);
+
+...
+
+// only the 2nd message will be received: it is the latest with
+// the Last-Value property set
+TextMessage messageReceived = (TextMessage)messageConsumer.receive(5000);
+System.out.format("Received message: %s\n", messageReceived.getText());
</programlisting>
</section>
<section>
Modified: trunk/docs/user-manual/en/logging.xml
===================================================================
--- trunk/docs/user-manual/en/logging.xml 2009-05-22 12:04:34 UTC (rev 7003)
+++ trunk/docs/user-manual/en/logging.xml 2009-05-22 17:59:11 UTC (rev 7004)
@@ -1,15 +1,15 @@
<?xml version="1.0" encoding="UTF-8"?>
<chapter id="logging">
<title>Logging</title>
- <para>JBM leverages the Java Logging framework, JUL, for all its logging meaning we have no
- dependencies on any logging framework. Users can provide their own logging handler to use or
- alternatively use one of the handlers provided by JBM. There are 2 of these a Log4j handler
- and a JBoss logging handler.</para>
+ <para>JBM uses standard JDK loggin, i.e. JUL, for all its logging. This means we have no
+ dependencies on any third party logging framework. Users can provide their own logging
+ handler to use or alternatively use one of the handlers provided by JBM. There are 2 of
+ these a Log4j handler and a JBoss logging handler.</para>
<para>The handlers are configured via the JUL logging.properties file. This default location for
this file is under the <literal>lib</literal> directory found in the Java home directory
- however can be overriden. The standalone JBM server does this and the
- <literal>logging.properties</literal> file can be found under the config directory of
- the JBM installation. </para>
+ however can be overriden. The standalone JBM server does this and the <literal
+ >logging.properties</literal> file can be found under the config directory of the JBM
+ installation. </para>
<para>To use the Log4j handler edit the <literal>logging.properties</literal> file and change
the <literal>handlers</literal> property to:</para>
<programlisting>handlers=org.jboss.messaging.integration.logging.Log4jLoggerHandler</programlisting>
@@ -17,9 +17,9 @@
<para>To use the JBoss handler edit the <literal>logging.properties</literal> file and change
the <literal>handlers</literal> property to:</para>
<programlisting>handlers=org.jboss.messaging.integration.logging.JBossLoggerHandler</programlisting>
- <para>If using the JBoss handler the property
- <literal>org.jboss.logging.Logger.pluginClass</literal> must be set. By default this is
- set to <literal>org.jboss.messaging.integration.logging.JBMLoggerPlugin</literal> in the
+ <para>If using the JBoss handler the property <literal
+ >org.jboss.logging.Logger.pluginClass</literal> must be set. By default this is set to
+ <literal>org.jboss.messaging.integration.logging.JBMLoggerPlugin</literal> in the
standalone server. Only change this property if you want to use your own plugin
class.</para>
<note>
Modified: trunk/docs/user-manual/en/management.xml
===================================================================
--- trunk/docs/user-manual/en/management.xml 2009-05-22 12:04:34 UTC (rev 7003)
+++ trunk/docs/user-manual/en/management.xml 2009-05-22 17:59:11 UTC (rev 7004)
@@ -1,22 +1,22 @@
<?xml version="1.0" encoding="UTF-8"?>
<chapter id="management">
<title>Management</title>
- <para>JBoss Messaging has a management API that allows a user to modify a server configuration,
- create new resources (e.g. JMS queues and topics), inspect these resources (e.g. how many
- messages are currently held in a queue) and interact with it (e.g. to remove messages from a
- queue). All the operations allows a client to <emphasis>manage</emphasis> JBoss
- Messaging.</para>
+ <para>JBoss Messaging has an extensive management API that allows a user to modify a server
+ configuration, create new resources (e.g. JMS queues and topics), inspect these resources
+ (e.g. how many messages are currently held in a queue) and interact with it (e.g. to remove
+ messages from a queue). All the operations allows a client to <emphasis>manage</emphasis>
+ JBoss Messaging. It also allows clients to subscribe to management notifications.</para>
<para>There are 3 ways to manage JBoss Messaging:</para>
<itemizedlist>
<listitem>
<para>Using JMX -- JMX is the standard way to manage Java applications</para>
</listitem>
<listitem>
- <para>Using Core API -- management operations are sent to JBoss Messaging server using
- <emphasis>Core messages</emphasis></para>
+ <para>Using the core API -- management operations are sent to JBoss Messaging server using
+ <emphasis>core messages</emphasis></para>
</listitem>
<listitem>
- <para>Using JMS API -- management operations are sent to JBoss Messaging server using
+ <para>Using the JMS API -- management operations are sent to JBoss Messaging server using
<emphasis>JMS messages</emphasis></para>
</listitem>
</itemizedlist>
@@ -42,24 +42,25 @@
>org.jboss.messaging.jms.server.management</literal> package</para>
</listitem>
</itemizedlist>
- <para>The way to invoke a <emphasis>management operations</emphasis> depends whether JMX, Core
- messages, or JMS Messages are used.</para>
+ <para>The way to invoke a <emphasis>management operations</emphasis> depends whether JMX, core
+ messages, or JMS messages are used.</para>
<section>
<title>Core Management API</title>
- <para>JBoss Messaging defines a Core Management API to manage Core resources.</para>
+ <para>JBoss Messaging defines a core management API to manage core resources. For full
+ details of the API please consult the javadoc. In summary:</para>
<section>
<title>Core Server Management</title>
<itemizedlist>
<listitem>
- <para>Creating and destroying queues</para>
- <para>Core queues can be created (resp. destroyed) using the management operations
- <literal>createQueue()</literal> or <literal>deployQueue()</literal> (resp.
- <literal>destroyQueue()</literal>) on the <literal
+ <para>Creating, deploying and destroying queues</para>
+ <para>Core queues can be created or destroyed using the management operations
+ <literal>createQueue()</literal> or <literal>deployQueue()</literal> or
+ <literal>destroyQueue()</literal>)on the <literal
>MessagingServerControlMBean</literal> (with the ObjectName <literal
>org.jboss.messaging:module=Core,type=Server</literal> or the resource name
<literal>core.server</literal>)</para>
- <para><literal>deployQueue</literal> will fail if the queue already exists while
- <literal>createQueue</literal> will do nothing.</para>
+ <para><literal>createQueue</literal> will fail if the queue already exists while
+ <literal>deployQueue</literal> will do nothing.</para>
</listitem>
<listitem>
<para>Listing and closing remote connections</para>
@@ -74,20 +75,20 @@
<listitem>
<para>Transaction heuristic operations</para>
<para>In case of a server crash, when the server restarts, it it possible that
- some transaction requires an manual intervention. The <literal
+ some transaction requires manual intervention. The <literal
>listPreparedTransactions()</literal> method lists the transactions which
are in the prepared states (the transactions are represented as opaque Base64
- Strings.) To commit (resp. rollback) a given prepared transaction, the <literal
- >commitPreparedTransaction</literal>() (resp. <literal
- >rollbackPreparedTransaction()</literal>) method can be used to resolve
+ Strings.) To commit or rollback a given prepared transaction, the <literal
+ >commitPreparedTransaction</literal>() or <literal
+ >rollbackPreparedTransaction()</literal> method can be used to resolve
heuristic transactions.</para>
</listitem>
<listitem>
<para>Enabling and resetting Message counters</para>
- <para>Message counters can be enabled (resp. disabled) using the <literal
- >enableMessageCounters()</literal> (resp. <literal
- >disableMessageCounters()</literal>) method. To reset message counters, it
- is possible to invoke <literal>resetAllMessageCounters()</literal> and <literal
+ <para>Message counters can be enabled or disabled using the <literal
+ >enableMessageCounters()</literal> or <literal
+ >disableMessageCounters()</literal> method. To reset message counters, it is
+ possible to invoke <literal>resetAllMessageCounters()</literal> and <literal
>resetAllMessageCounterHistories()</literal> methods.</para>
</listitem>
<listitem>
@@ -109,8 +110,8 @@
<itemizedlist>
<listitem>
<para>Modifying roles and permissions for an address</para>
- <para>You can add (resp. remove) roles associated to a queue using the <literal
- >addRole()</literal> (resp. <literal>removeRole()</literal>) method. You can
+ <para>You can add or remove roles associated to a queue using the <literal
+ >addRole()</literal> or. <literal>removeRole()</literal> methods. You can
list all the roles associated to the queue with the <literal
>getRoles()</literal> method</para>
</listitem>
@@ -118,15 +119,15 @@
</section>
<section>
<title>Core Queue Management</title>
- <para>The bulk of the Core management API deals with Core queues. The <literal
+ <para>The bulk of the core management API deals with core queues. The <literal
>QueueControlMBean</literal> class defines the Core queue management operations
(with the ObjectName <literal
>org.jboss.messaging:module=Core,type=Queue,address="<the bound
address>",name="<the queue name>"</literal> or the resource name <literal
>core.queue.<the queue name></literal>).</para>
- <para>Most of the management operations on the queues takes either a single message ID
- (e.g. to remove a single message) or a filter (e.g. to expire all messages with a
- given property.)</para>
+ <para>Most of the management operations on queues take either a single message ID (e.g.
+ to remove a single message) or a filter (e.g. to expire all messages with a given
+ property.)</para>
<itemizedlist>
<listitem>
<para>Expiring, sending to a dead letter address and moving messages</para>
@@ -188,77 +189,77 @@
</section>
<section>
<title>Other Core Resources Management</title>
- <para>JBoss Messaging allow to start and stop its remote resources (acceptors, diverts,
- bridges, etc.) so that a server can be made off line for a given period of time
+ <para>JBoss Messaging allows to start and stop its remote resources (acceptors, diverts,
+ bridges, etc.) so that a server can be taken off line for a given period of time
without stopping it completely (e.g. if other management operations must be performed
such as resolving heuristic transactions). These resources are:</para>
<itemizedlist>
<listitem>
<para>Acceptors</para>
- <para>They can be started (resp. stopped) using the <literal>start()</literal>
- (resp. <literal>stop()</literal>) method on the <literal
+ <para>They can be started or stopped using the <literal>start()</literal> or.
+ <literal>stop()</literal> method on the <literal
>AcceptorControlMBean</literal> class (with the ObjectName <literal
>org.jboss.messaging:module=Core,type=Acceptor,name="<the acceptor
name>"</literal> or the resource name <literal>core.acceptor.<the
- address name></literal>). Acceptor's parameters can be retrieved using
+ address name></literal>). The acceptors parameters can be retrieved using
the <literal>AcceptorControlMBean</literal> attributes (see <xref
linkend="configuring-transports.acceptors"/>)</para>
</listitem>
<listitem>
<para>Diverts</para>
- <para>They can be started (resp. stopped) using the <literal>start()</literal>
- (resp. <literal>stop()</literal>) method on the <literal
+ <para>They can be started or stopped using the <literal>start()</literal> or
+ <literal>stop()</literal> method on the <literal
>DivertControlMBean</literal> class (with the ObjectName <literal
>org.jboss.messaging:module=Core,type=Divert,name=<the divert
name></literal> or the resource name <literal>core.divert.<the divert
- name></literal>). Divert's parameters can be retrieved using the <literal
+ name></literal>). Diverts parameters can be retrieved using the <literal
>DivertControlMBean</literal> attributes (see <xref linkend="diverts"
/>)</para>
</listitem>
<listitem>
<para>Bridges</para>
- <para>They can be started (resp. stopped) using the <literal>start()</literal>
- (resp. <literal>stop()</literal>) method on the <literal
+ <para>They can be started or stopped using the <literal>start()</literal> (resp.
+ <literal>stop()</literal>) method on the <literal
>BridgeControlMBean</literal> class (with the ObjectName <literal
>org.jboss.messaging:module=Core,type=Bridge,name="<the bridge
name>"</literal> or the resource name <literal>core.bridge.<the bridge
- name></literal>). Bridge's parameters can be retrieved using the <literal
+ name></literal>). Bridges parameters can be retrieved using the <literal
>BridgeControlMBean</literal> attributes (see <xref linkend="core-bridges"
/>)</para>
</listitem>
<listitem>
<para>Broadcast groups</para>
- <para>They can be started (resp. stopped) using the <literal>start()</literal>
- (resp. <literal>stop()</literal>) method on the <literal
+ <para>They can be started or stopped using the <literal>start()</literal> or
+ <literal>stop()</literal> method on the <literal
>BroadcastGroupControlMBean</literal> class (with the ObjectName <literal
>org.jboss.messaging:module=Core,type=BroadcastGroup,name="<the broadcast
group name>"</literal> or the resource name <literal
>core.broadcastgroup.<the broadcast group name></literal>). Broadcast
- group's parameters can be retrieved using the <literal
+ groups parameters can be retrieved using the <literal
>BroadcastGroupControlMBean</literal> attributes (see <xref
linkend="clusters.broadcast-groups"/>)</para>
</listitem>
<listitem>
<para>Discovery groups</para>
- <para>They can be started (resp. stopped) using the <literal>start()</literal>
- (resp. <literal>stop()</literal>) method on the <literal
+ <para>They can be started or stopped using the <literal>start()</literal> or
+ <literal>stop()</literal> method on the <literal
>DiscoveryGroupControlMBean</literal> class (with the ObjectName <literal
>org.jboss.messaging:module=Core,type=DiscoveryGroup,name="<the discovery
group name>"</literal> or the resource name <literal
>core.discovery.<the discovery group name></literal>). Discovery
- group's parameters can be retrieved using the <literal
+ groups parameters can be retrieved using the <literal
>DiscoveryGroupControlMBean</literal> attributes (see <xref
linkend="clusters.discovery-groups"/>)</para>
</listitem>
<listitem>
<para>Cluster connections</para>
- <para>They can be started (resp. stopped) using the <literal>start()</literal>
- (resp. <literal>stop()</literal>) method on the <literal
+ <para>They can be started or stopped using the <literal>start()</literal> or
+ <literal>stop()</literal> method on the <literal
>ClusterConnectionControlMBean</literal> class (with the ObjectName <literal
>org.jboss.messaging:module=Core,type=ClusterConnection,name="<the
cluster connection name>"</literal> or the resource name <literal
>core.clusterconnection.<the cluster connection name></literal>).
- Cluster connection's parameters can be retrieved using the <literal
+ Cluster connections parameters can be retrieved using the <literal
>ClusterConnectionControlMBean</literal> attributes (see <xref
linkend="clusters.cluster-connections"/>)</para>
</listitem>
@@ -268,7 +269,7 @@
<section>
<title>JMS Management API</title>
<para>JBoss Messaging defines a JMS Management API to manage JMS <emphasis>administrated
- objects</emphasis>.</para>
+ objects</emphasis> (i.e. JMS queues, topics and connection factories).</para>
<section>
<title>JMS Server Management</title>
<para>JMS Resources (connection factories and destinations) can be created using the
@@ -278,28 +279,27 @@
<itemizedlist>
<listitem>
<para>Creating/destroying connection factories</para>
- <para>JMS connection factories can be created (resp. destroyed) using the <literal
- >createConnectionFactory()</literal> methods (resp. <literal
- >destroyConnectionFactory()</literal>) methods. These connection factories
+ <para>JMS connection factories can be created or destroyed using the <literal
+ >createConnectionFactory()</literal> methods or <literal
+ >destroyConnectionFactory()</literal> methods. These connection factories
are bound to JNDI so that JMS clients can look them up</para>
</listitem>
<listitem>
<para>Creating/destroying queues</para>
- <para>JMS queues can be created (resp. destroyed) using the <literal
- >createQueue()</literal> methods (resp. <literal>destroyQueue()</literal>)
+ <para>JMS queues can be created or destroyed using the <literal
+ >createQueue()</literal> methods or <literal>destroyQueue()</literal>
methods. These queues are bound to JNDI so that JMS clients can look them
up</para>
</listitem>
<listitem>
<para>Creating/destroying topics</para>
- <para>JMS topics can be created (resp. destroyed) using the <literal
- >createTopic()</literal> methods (resp. <literal>destroyTopic()</literal>)
- methods. These topics are bound to JNDI so that JMS clients can look them
- up</para>
+ <para>JMS topics can be created or destroyed using the <literal
+ >createTopic()</literal> or <literal>destroyTopic()</literal> methods. These
+ topics are bound to JNDI so that JMS clients can look them up</para>
</listitem>
<listitem>
<para>Listing and closing remote connections</para>
- <para>JMS Client's remote addresses can be retrieved using <literal
+ <para>JMS Clients remote addresses can be retrieved using <literal
>listRemoteAddresses()</literal>. It is also possible to close the
connections associated with a remote address using the <literal
>closeConnectionsForAddress()</literal> method.</para>
@@ -330,14 +330,12 @@
</section>
<section>
<title>JMS Queue Management</title>
- <para>JMS Queues can be managed using the <literal>JMSQueueControlMBean</literal> class
+ <para>JMS queues can be managed using the <literal>JMSQueueControlMBean</literal> class
(with the ObjectName <literal>org.jboss.messaging:module=JMS,type=Queue,name="<the
queue name>"</literal> or the resource name <literal>jms.queue.<the queue
name></literal>). </para>
- <para>
- <literal>The management operations on a JMS queue are very similar to the operations
- on a Core queue.</literal>
- </para>
+ <para><emphasis>The management operations on a JMS queue are very similar to the
+ operations on a core queue. </emphasis></para>
<itemizedlist>
<listitem>
<para>Expiring, sending to a dead letter address and moving messages</para>
@@ -404,7 +402,7 @@
<itemizedlist>
<listitem>
<para>Listing subscriptions and messages</para>
- <para>JMS topic's subscriptions can be listed using the <literal
+ <para>JMS topics subscriptions can be listed using the <literal
>listAllSubscriptions()</literal>, <literal
>listDurableSubscriptions()</literal>, <literal
>listNonDurableSubscriptions()</literal> methods. These methods return
@@ -419,7 +417,7 @@
>dropDurableSubscription()</literal> method.</para>
</listitem>
<listitem>
- <para>Counting subscription's messages</para>
+ <para>Counting subscriptions messages</para>
<para>The <literal>countMessagesForSubscription()</literal> method can be used to
know the number of messages held for a given subscription (with an optional
message selector to know the number of messages matching the selector)</para>
@@ -457,8 +455,8 @@
<literal>jmx-management-enabled</literal> to <literal>false</literal> in <literal
>jbm-configuration.xml</literal>:</para>
<programlisting>
- <!-- false to disable JMX management for JBoss Messaging -->
- <jmx-management-enabled>false</jmx-management-enabled>
+<!-- false to disable JMX management for JBoss Messaging -->
+<jmx-management-enabled>false</jmx-management-enabled>
</programlisting>
<para>If JMX is enabled, JBoss Messaging can be managed locally using <literal
>jconsole</literal>. Remote connections to JMX are not enabled by default for
@@ -471,12 +469,11 @@
MBeanServer</literal> to register its MBeans. This is configured in JBoss
Microcontainer Beans file (see <xref linkend="server.microcontainer.configuration"
/>):</para>
- <programlisting>
- <!-- MBeanServer -->
- <bean name="MBeanServer" class="javax.management.MBeanServer">
- <constructor factoryClass="java.lang.management.ManagementFactory"
+ <programlisting><!-- MBeanServer -->
+<bean name="MBeanServer" class="javax.management.MBeanServer">
+ <constructor factoryClass="java.lang.management.ManagementFactory"
factoryMethod="getPlatformMBeanServer" />
- </bean>
+</bean>
</programlisting>
</section>
<section>
@@ -507,7 +504,7 @@
will handle it, extract the information, invoke the operation on the managed resources and
send a <emphasis>management reply</emphasis> to the management message's reply-to address
(specified by <literal>ClientMessageImpl.REPLYTO_HEADER_NAME</literal>). </para>
- <para>A <literal>ClientConsumer</literal> can be used to consumed the management reply and
+ <para>A <literal>ClientConsumer</literal> can be used to consume the management reply and
retrieve the result of the operation (if any) stored in the reply's body. For portability,
results are returned as a <ulink url="http://json.org">JSON</ulink> String rather than Java
Serialization (the <literal
@@ -517,27 +514,27 @@
Core messages:</para>
<orderedlist>
<listitem>
- <para>create a <literal>ClientRequestor</literal> to send messages to the management
+ <para>Create a <literal>ClientRequestor</literal> to send messages to the management
address and receive replies</para>
</listitem>
<listitem>
- <para>create a <literal>ClientMessage</literal></para>
+ <para>Create a <literal>ClientMessage</literal></para>
</listitem>
<listitem>
- <para>use the helper class <literal
+ <para>Use the helper class <literal
>org.jboss.messaging.core.client.management.impl.ManagementHelper</literal> to
fill the message with the management properties</para>
</listitem>
<listitem>
- <para>send the message using the <literal>ClientRequestor</literal></para>
+ <para>Send the message using the <literal>ClientRequestor</literal></para>
</listitem>
<listitem>
- <para>use the helper class <literal
+ <para>Use the helper class <literal
>org.jboss.messaging.core.client.management.impl.ManagementHelper</literal> to
retrieve the operation result from the management reply</para>
</listitem>
</orderedlist>
- <para>For example, to know the number of messages in the Core queue <literal
+ <para>For example, to find out the number of messages in the core queue <literal
>exampleQueue</literal>:</para>
<programlisting>
ClientSession session = ...
@@ -550,14 +547,14 @@
</programlisting>
<para>Management operation name and parameters must conform to the Java interfaces defined in
the <literal>management</literal> packages.</para>
- <para>Name of the resources are built using the helper class <literal
+ <para>Names of the resources are built using the helper class <literal
>org.jboss.messaging.core.management.ResourceNames</literal> and are straightforward
(<literal>core.queue.exampleQueue</literal> for the Core Queue <literal
>exampleQueue</literal>, <literal>jms.topic.exampleTopic</literal> for the JMS Topic
<literal>exampleTopic</literal>, etc.).</para>
<section id="management.core.configuration">
<title>Configuring Core Management</title>
- <para>the management address to send management messages is configured in <literal
+ <para>The management address to send management messages is configured in <literal
>jbm-configuration.xml</literal>:</para>
<programlisting>
<management-address>jbm.management</management-address>
@@ -577,9 +574,9 @@
</section>
<section id="management.jms">
<title>Using Management Via JMS</title>
- <para>Using JMS messages to manage JBoss Messaging is very similar to using Core API.</para>
- <para>An important difference is that JMS requires a JMS Queue to send the messages to(instead
- of an address for the Core API).</para>
+ <para>Using JMS messages to manage JBoss Messaging is very similar to using core API.</para>
+ <para>An important difference is that JMS requires a JMS queue to send the messages to
+ (instead of an address for the core API).</para>
<para>The <emphasis>management queue</emphasis> is a special queue and needs to be
instantiated directly by the client:</para>
<programlisting>
@@ -625,8 +622,8 @@
</programlisting>
<section>
<title>Configuring JMS Management</title>
- <para>Whether JMS or Core API is used for management, the configuration steps are the same
- (see <xref linkend="management.core.configuration"/>).</para>
+ <para>Whether JMS or the core API is used for management, the configuration steps are the
+ same (see <xref linkend="management.core.configuration"/>).</para>
</section>
<section>
<title>Example</title>
@@ -636,7 +633,7 @@
</section>
</section>
<section id="management.replication">
- <title>Management Replication</title>
+ <title>Management Cluster Password</title>
<para>JBoss Messaging allows <emphasis>replication</emphasis> of a live server to a backup
server. This impacts management as resources created on the live server (e.g. a core
address) must also be created on the backup server. Otherwise, when failover occurs, the
@@ -648,8 +645,8 @@
resources and state. For example, you only need to manage the live server: if a queue is
created on the live server, JBoss Messaging will ensure that the same resource will also be
created on the backup server.</para>
- <para>If Core messages or JMS messages are used to invoke management operations, replication
- is handled automatically by JBoss Messaging.</para>
+ <para>If core or JMS messages are used to invoke management operations, replication is handled
+ automatically by JBoss Messaging.</para>
<para>To allow this management replication with JMX, JBoss Messaging defines a
<emphasis>management cluster password</emphasis>: this special password <emphasis>must
be shared by all nodes</emphasis>. To configure it, change the value in <literal
@@ -658,7 +655,8 @@
<management-cluster-password>CHANGE ME!!</management-cluster-password>
</programlisting>
<para>By default, its value is <literal>CHANGE ME!!</literal>. It is strongly suggested to
- change it to a safer value (this password is never sent on the network).</para>
+ change it to a safer value. If you don't change it from the default JBoss Messaging will
+ detect this and pester you with a warning on every start-up.</para>
<para>JBoss Messaging internally uses Core messages to replicate management operations between
the live and backup server when JMX is used. By default, there is a timeout of 5s (5000ms)
to send a management request from the live server to the backup server and wait for a
@@ -706,13 +704,13 @@
<para>JBoss Messaging defines a special <emphasis>management notification
address</emphasis>. Core queues can be bound to this address so that clients will
receive management notifications as Core messages</para>
- <para>A Core client which wants to receive management notifications must create a Core
+ <para>A Core client which wants to receive management notifications must create a core
queue bound to the management notification address. It can then receive the
notifications from its queue.</para>
- <para>Notifications messages are regular Core messages with additional properties
+ <para>Notifications messages are regular core messages with additional properties
corresponding to the notification (its type, when it occurred, the resources which were
concerned, etc.).</para>
- <para>Since notifications are regular Core messages, it is possible to use message
+ <para>Since notifications are regular core messages, it is possible to use message
selectors to filter out notifications and receives only a subset of all the
notifications emitted by the server.</para>
<section id="management.notifications.core.configuration">
@@ -774,7 +772,7 @@
</section>
<section id="management.message-counters">
<title>Message Counters</title>
- <para>Message counters can be used to have informations on queue <emphasis>over
+ <para>Message counters can be used to obtain information on queues <emphasis>over
time</emphasis> as JBoss Messaging keeps a history on queue metrics.</para>
<para>They can be used to show <emphasis>trends</emphasis> on queues. For example, using the
management API, it would be possible to query the number of messages in a queue at regular
@@ -806,7 +804,6 @@
<literal>depthDelta</literal> is equal to <literal>-10</literal> this means that
overall 10 messages have been removed from the queue (e.g. 2 messages were added and
12 were removed)</para>
- <para/>
</listitem>
<listitem>
<para><literal>lastAddTimestamp</literal></para>
@@ -819,40 +816,40 @@
</itemizedlist>
<section id="configuring.message.counters">
<title>Configuring Message Counters</title>
- <para>By default, message counters are disabled as it has a negative effect on performance,
+ <para>By default, message counters are disabled as it might have a small negative effect on
memory (the metrics are kept in memory) and CPU (the queues are sampled at regular
interval).</para>
<para>To enable message counters, you can set it to <literal>true</literal> in <literal
>jbm-configuration.xml</literal>:</para>
<programlisting>
- <message-counter-enabled>true</message-counter-enabled>
+<message-counter-enabled>true</message-counter-enabled>
</programlisting>
<para>Message counters keeps a history of the queue metrics (10 days by default) and
samples all the queues at regular interval (10 seconds by default). If message counters
are enabled, these values should be configured to suit your messaging use case in
<literal>jbm-configuration.xml</literal>:</para>
<programlisting>
- <!-- keep history for a week -->
- <message-counter-max-day-history>7</message-counter-max-day-history>
- <!-- sample the queues every minute (60000ms) -->
- <message-counter-sample-period>60000</message-counter-sample-period>
+<!-- keep history for a week -->
+<message-counter-max-day-history>7</message-counter-max-day-history>
+<!-- sample the queues every minute (60000ms) -->
+<message-counter-sample-period>60000</message-counter-sample-period>
</programlisting>
<para>Message counters can be retrieved using the Management API. For example, to retrieve
message counters on a JMS Queue using JMX:</para>
<programlisting>
- // retrieve a connection to JBoss Messaging's MBeanServer
- MBeanServerConnection mbsc = ...
- JMSQueueControlMBean queueControl = (JMSQueueControlMBean)MBeanServerInvocationHandler.newProxyInstance(mbsc,
- on,
- JMSQueueControlMBean.class,
- false);
- // message counters are retrieved as a JSON String
- String counters = queueControl.listMessageCounter();
- // use the MessageCounterInfo helper class to manipulate message counters more easily
- MessageCounterInfo messageCounter = MessageCounterInfo.fromJSON(counters);
- System.out.format("%s message(s) in the queue (since last sample: %s)\n",
- counter.getDepth(),
- counter.getDepthDelta());
+// retrieve a connection to JBoss Messaging's MBeanServer
+MBeanServerConnection mbsc = ...
+JMSQueueControlMBean queueControl = (JMSQueueControlMBean)MBeanServerInvocationHandler.newProxyInstance(mbsc,
+on,
+JMSQueueControlMBean.class,
+false);
+// message counters are retrieved as a JSON String
+String counters = queueControl.listMessageCounter();
+// use the MessageCounterInfo helper class to manipulate message counters more easily
+MessageCounterInfo messageCounter = MessageCounterInfo.fromJSON(counters);
+System.out.format("%s message(s) in the queue (since last sample: %s)\n",
+counter.getDepth(),
+counter.getDepthDelta());
</programlisting>
</section>
<section>
Modified: trunk/docs/user-manual/en/message-expiry.xml
===================================================================
--- trunk/docs/user-manual/en/message-expiry.xml 2009-05-22 12:04:34 UTC (rev 7003)
+++ trunk/docs/user-manual/en/message-expiry.xml 2009-05-22 17:59:11 UTC (rev 7004)
@@ -1,38 +1,40 @@
<?xml version="1.0" encoding="UTF-8"?>
<chapter id="message-expiry">
<title>Message Expiry</title>
- <para>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>Messages can be set with an optional <emphasis>time to live</emphasis> when sending them.
+ Such messages will be retained in the messaging system until their <emphasis>time to
+ live</emphasis> is reached.</para>
<para>JBoss Messaging's addresses can be assigned a expiry address so that, when messages are
- expired, they are removed from the queue and sent to the expiry address. These
- <emphasis>expired</emphasis> messages can later be consumed for further inspection.</para>
+ expired, they are removed from the queue and sent to the expiry address. Many different queues
+ cna be bound to an expiry address. These <emphasis>expired</emphasis> messages can later be
+ consumed for further inspection.</para>
<section>
<title>Message Expiry</title>
- <para>Using JBoss Messaging Core API, you can set an expiration time directly on the
- message:</para>
- <programlisting>
- // message will expire in 5000ms from now
- message.setExpiration(System.currentTimeMillis() + 5000);
+ <para>Using JBoss Messaging Core API, you can set an expiration time directly on the
+ message:</para>
+ <programlisting>
+// message will expire in 5000ms from now
+message.setExpiration(System.currentTimeMillis() + 5000);
</programlisting>
<para>JMS MessageProducer allows to set a TimeToLive for the messages it sent:</para>
<programlisting>
// messages sent by this producer will be retained for 5s (5000ms) before expiration
producer.setTimeToLive(5000);
</programlisting>
- <para>Expired messages which are consumed from an expiry address have the following properties:</para>
- <itemizedlist>
+ <para>Expired messages which are consumed from an expiry address have the following
+ properties:</para>
+ <itemizedlist>
<listitem>
<para><literal>_JBM_ORIG_DESTINATION</literal></para>
<para>a String property containing the <emphasis>original destination</emphasis> of the
- expired message </para>
+ expired message </para>
</listitem>
- <listitem>
- <para><literal>_JBM_ACTUAL_EXPIRY</literal></para>
- <para>a Long property containing the <emphasis>actual expiration time</emphasis> of the expired message</para>
- </listitem>
- </itemizedlist>
-
+ <listitem>
+ <para><literal>_JBM_ACTUAL_EXPIRY</literal></para>
+ <para>a Long property containing the <emphasis>actual expiration time</emphasis> of the
+ expired message</para>
+ </listitem>
+ </itemizedlist>
</section>
<section>
<title>Configuring Expiry Addresses</title>
@@ -44,8 +46,8 @@
</address-setting>
</programlisting>
<para>If messages are expired and no expiry address is specified, messages are simply removed
- from the queue. Address wildcards can be used
- to configure expiry address for a set of addresses (see <xref linkend="wildcard-syntax" />).</para>
+ from the queue. Address wildcards can be used to configure expiry address for a set of
+ addresses (see <xref linkend="wildcard-syntax"/>).</para>
</section>
<section id="configuring.expiry.reaper">
<title>Configuring The Expiry Reaper Thread</title>
@@ -68,7 +70,7 @@
</section>
<section>
<title>Example</title>
- <para>The <ulink url="../../../../examples/jms/expiry/readme.html"><literal>expiry</literal> example</ulink> shows
- how message expiry is configured and used with JMS.</para>
+ <para>The <ulink url="../../../../examples/jms/expiry/readme.html"><literal>expiry</literal>
+ example</ulink> shows how message expiry is configured and used with JMS.</para>
</section>
</chapter>
Modified: trunk/docs/user-manual/en/message-grouping.xml
===================================================================
--- trunk/docs/user-manual/en/message-grouping.xml 2009-05-22 12:04:34 UTC (rev 7003)
+++ trunk/docs/user-manual/en/message-grouping.xml 2009-05-22 17:59:11 UTC (rev 7004)
@@ -9,21 +9,22 @@
>_JBM_GROUP_ID</literal> for JBoss Messaging Core API).</para>
</listitem>
<listitem>
- <para>Messages in a message group will be all delivered to no more than one of the queue's
- consumers. The consumer that receives the first message of a group will receive all the
- messages that belong to this group.</para>
+ <para>Messages in a message group are always consumed by the same consumer, even if there
+ are many consumers on a queue. They pin all messages with the same group id to the same
+ consumer. If that consumer closes another consumer is chosen and will receive all
+ messages with the same group id.</para>
</listitem>
- </itemizedlist>
+ </itemizedlist>
<section>
<title>Configuring Message Grouping</title>
<para>Message grouping must be enabled in the address-setting configuration by using a
specific <literal>distribution-policy-class</literal>:</para>
<programlisting>
- <address-setting match="jms.queue.exampleQueue">
- <distribution-policy-class>
- org.jboss.messaging.core.server.impl.GroupingRoundRobinDistributor
- </distribution-policy-class>
- </address-setting>
+ <address-setting match="jms.queue.exampleQueue">
+ <distribution-policy-class>
+ org.jboss.messaging.core.server.impl.GroupingRoundRobinDistributor
+ </distribution-policy-class>
+ </address-setting>
</programlisting>
<para>By default, <literal>distribution-policy-class</literal> is set to <literal
>org.jboss.messaging.core.server.impl.RoundRobinDistributor</literal> and message groups
@@ -43,17 +44,17 @@
<para>Within the same group, messages can also set a <literal>JMSXGroupSeq</literal>
<literal>int</literal> property (starting at 1).</para>
<programlisting>
- // send 2 messages in the same group to ensure the same
- // consumer will receive both
- Message message = ...
- message.setStringProperty("JMSXGroupID", "Group-0");
- message.setIntProperty("JMSXGroupSeq", 1);
- producer.send(message);
+ // send 2 messages in the same group to ensure the same
+ // consumer will receive both
+ Message message = ...
+ message.setStringProperty("JMSXGroupID", "Group-0");
+ message.setIntProperty("JMSXGroupSeq", 1);
+ producer.send(message);
- message = ...
- message.setStringProperty("JMSXGroupID", "Group-0");
- message.setIntProperty("JMSXGroupSeq", 2);
- producer.send(message);
+ message = ...
+ message.setStringProperty("JMSXGroupID", "Group-0");
+ message.setIntProperty("JMSXGroupSeq", 2);
+ producer.send(message);
</programlisting>
</section>
<section>
Modified: trunk/docs/user-manual/en/paging.xml
===================================================================
--- trunk/docs/user-manual/en/paging.xml 2009-05-22 12:04:34 UTC (rev 7003)
+++ trunk/docs/user-manual/en/paging.xml 2009-05-22 17:59:11 UTC (rev 7004)
@@ -1,15 +1,17 @@
<?xml version="1.0" encoding="UTF-8"?>
<chapter id="paging">
<title>Paging</title>
- <para>JBoss Messaging supports the paging of messages to disk when memory begins to fill up.
- This stops the potential of the server running out of memory when receiving lots of
- messages.</para>
- <para>Once the amount of memory used by messages held by the server reaches a certain
- configurable size, JBoss Messaging starts storing messages on disk. These messages are paged
- back into memory as other messages are delivered and acknowledged by a consumer.</para>
- <para>There are two page modes supported by JBoss Messaging. <link linkend="paging.global.mode"
- >Global Paging Mode </link> and <link linkend="paging.address.mode">Address Paging Mode
- </link></para>
+ <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 a) the size of the queue
+ reaches a total configured maximum size or b) The total size of all queues reaches a
+ configured maximum size.</para>
+ <para>These two modes of operation are called <link linkend="paging.address.mode">Address Paging
+ Mode </link>
+ <link linkend="paging.global.mode">Global Paging Mode </link>.</para>
<section>
<title>Page Files</title>
<para>Messages are stored per address on the file system. Each address has an individual
@@ -20,11 +22,11 @@
</section>
<section id="paging.global.mode">
<title>Global Paging Mode</title>
- <para>JBoss Messaging enters into Global Paging Mode when the total memory used by all
- queues reaches a configured maximum value, determined by <literal><link
+ <para>JBoss Messaging goes into global paging mode when the total memory used by all queues
+ reaches a configured maximum value, determined by <literal><link
linkend="paging.main.config">paging-max-global-size-bytes</link></literal>. </para>
- <para>These messages are depaged back into memory once enough memory
- (<literal>global-page-size</literal>) has been freed up.</para>
+ <para>These messages are depaged back into memory once enough memory (<literal
+ >global-page-size</literal>) has been freed up.</para>
<section id="paging.main.config">
<title>Configuration</title>
<para>Global paging parameters are specified on the main configuration file.</para>
@@ -124,9 +126,9 @@
</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>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>
@@ -137,7 +139,7 @@
</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, i.e. a
+ <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
@@ -145,14 +147,14 @@
<para>For example:</para>
<itemizedlist>
<listitem>
- <para>An Address has 10 queues </para>
+ <para>An address has 10 queues </para>
</listitem>
<listitem>
- <para>one of the queues does not deliver its messages (maybe because of a slow
+ <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>
+ <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>
@@ -165,6 +167,6 @@
<section>
<title>Paging Example</title>
<para>The <ulink url="../../../../examples/jms/paging/readme.html"><literal>Paging</literal>
- Example</ulink> shows how to JBoss Messaging avoids running out of memory.</para>
+ Example</ulink> shows how to use paging with JBoss Messaging.</para>
</section>
</chapter>
Modified: trunk/docs/user-manual/en/perf-tuning.xml
===================================================================
--- trunk/docs/user-manual/en/perf-tuning.xml 2009-05-22 12:04:34 UTC (rev 7003)
+++ trunk/docs/user-manual/en/perf-tuning.xml 2009-05-22 17:59:11 UTC (rev 7004)
@@ -6,16 +6,16 @@
<title>Tuning the journal</title>
<itemizedlist>
<listitem>
- <para>Tune minimum number of journal files.</para>
+ <para>Tune minimum number of journal files. TODO</para>
</listitem>
<listitem>
- <para>Tune journal file size.</para>
+ <para>Tune journal file size. TODO</para>
</listitem>
<listitem>
- <para>Use AIO journal.</para>
+ <para>Use AIO journal. TODO</para>
</listitem>
<listitem>
- <para>Tune AIO re-use cache.</para>
+ <para>Tune AIO re-use cache. TODO</para>
</listitem>
</itemizedlist>
</section>
@@ -39,13 +39,13 @@
</listitem>
<listitem>
<para>Avoid <literal>ObjectMessage</literal>. <literal>ObjectMessage</literal> is
- convenient but it comes at a cost. The body of a ObjectMessage 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>
+ 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>
@@ -73,13 +73,13 @@
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 the chapter on <xref
- linkend="send-guarantees"/>send guarantees</para> for more information on
- this.</listitem>
+ linkend="send-guarantees">send guarantees</xref> 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
- section on <xref linkend="pre-acknolwedge">pre acknowledge</xref>.</para>
+ section on <xref linkend="pre-acknowledge">pre acknowledge</xref>.</para>
</listitem>
<listitem>
<para>Disabled security. You may get a small performance boost by disabling security
Modified: trunk/docs/user-manual/en/persistence.xml
===================================================================
--- trunk/docs/user-manual/en/persistence.xml 2009-05-22 12:04:34 UTC (rev 7003)
+++ trunk/docs/user-manual/en/persistence.xml 2009-05-22 17:59:11 UTC (rev 7004)
@@ -9,16 +9,16 @@
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
+ 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 since we're not doing random access operations.</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. By
- minimising the number of disk cylinders the file is using, we can minimise the amount of
+ 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
@@ -27,19 +27,22 @@
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 is also fully local and XA transaction capable.</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 NIO.</para>
+ <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.</para>
+ This provides very good performance and runs on any platform where there's a
+ JDK.</para>
</listitem>
<listitem>
- <para>Linux Asynchronous IO (AIO).</para>
- <para>The second implementation uses a thin native wrapper to talk to the Linux
+ <para>Linux Asynchronous IO (<ulink url="http://lse.sourceforge.net/io/aio.html"
+ >AIO</ulink>).</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
@@ -50,7 +53,7 @@
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 [LINK]</para>
+ install libaio please see <xref linkend="installing-aio">here</xref>.</para>
</listitem>
</itemizedlist>
<para>The standard JBoss Messaging core server uses two instances of the journal:</para>
@@ -74,15 +77,16 @@
</listitem>
</itemizedlist>
<para>For large messages, JBoss Messaging persists them outside the message journal. This is
- discussed in the chapter on large messages [LINK]</para>
+ discussed in the chapter on <xref linkend="large-messages">large messages</xref>.</para>
<para>JBoss Messaging also pages messages to disk in low memory situations. This is discussed in
- the chapter on paging [LINK]</para>
+ the chapter on <xref linkend="paging">paging</xref>.</para>
<para>If no persistence is required at all, JBoss Messaging can also be configured not to
- persist any data at all to storage.</para>
+ persist any data at all to storage as discussed <xref linkend="persistence.disabled"
+ >here</xref>.</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>
+ <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>
@@ -92,26 +96,26 @@
<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>
+ 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>
+ <para>The message journal is configured using the following attributes in <literal
+ >jbm-configuration.xml</literal></para>
<itemizedlist>
<listitem>
<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
- 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
+ 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>
@@ -119,9 +123,9 @@
<listitem>
<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>
+ 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>
<para><literal>journal-type</literal></para>
@@ -142,13 +146,13 @@
<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>
+ back to the client. The default value for this is <literal
+ >false</literal>.</para>
</listitem>
<listitem>
<para><literal>journal-file-size</literal></para>
- <para>The size of each journal file in bytes. The default value for this is 10485760
- bytes (10MiB).</para>
+ <para>The size of each journal file in bytes. The default value for this is <literal
+ >10485760</literal> bytes (10MiB).</para>
</listitem>
<listitem>
<para><literal>journal-min-files</literal></para>
@@ -173,36 +177,36 @@
</listitem>
<listitem>
<para><literal>journal-buffer-reuse-size</literal></para>
- <para>Creaking direct byte buffers is an expensive operation, so the journal will
+ <para>Creating direct byte buffers is an expensive operation, so the journal will
attempt to re-use any buffers with a size less than this setting, in bytes. If
this value is set to <literal>-1</literal> then the journal will not attempt to
- re-use any buffers. This setting only takes effect if the journal is
- <literal>AIO</literal>. The default value for this setting is
- <literal>1024</literal> bytes.</para>
+ re-use any buffers. This setting only takes effect if the journal is <literal
+ >AIO</literal>. The default value for this setting is <literal
+ >1024</literal> bytes.</para>
</listitem>
</itemizedlist>
</section>
- <section>
+ <section id="installing-aio">
<title>Installing AIO</title>
- <para>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>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
+ <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 libaio1</programlisting></para>
+ <programlisting>sudo yum install libaio</programlisting></para>
<para>Using aptitude, (e.g. on Ubuntu or Debian system):
- <programlisting>sudo apt-get install libaio1</programlisting></para>
+ <programlisting>sudo apt-get install libaio</programlisting></para>
</section>
- <section id="persistence.enabled">
- <title>Configuring JBoss Messaging for zero persistence</title>
+ <section id="persistence.disabled">
+ <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>
+ 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>
Modified: trunk/docs/user-manual/en/pre-acknowledge.xml
===================================================================
--- trunk/docs/user-manual/en/pre-acknowledge.xml 2009-05-22 12:04:34 UTC (rev 7003)
+++ trunk/docs/user-manual/en/pre-acknowledge.xml 2009-05-22 17:59:11 UTC (rev 7004)
@@ -28,17 +28,21 @@
price update message will arrive soon, overriding the previous price. </para>
<section>
<title>Using PRE_ACKNOWLEDGE</title>
- <para>To use pre-acknowledgement mode, create a JMS Session with the
+ <para>To 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>
+ </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>The <ulink url="../../../../examples/jms/pre-acknowledge/readme.html"
- ><literal>pre-acknowledge</literal> example</ulink> shows how to use
- pre-acknowledgement mode with with JMS.</para>
+ <para>The <ulink url="../../../../examples/jms/pre-acknowledge/readme.html"><literal
+ >pre-acknowledge</literal> example</ulink> shows how to use pre-acknowledgement mode
+ with with JMS.</para>
</section>
</chapter>
Modified: trunk/docs/user-manual/en/queue-attributes.xml
===================================================================
--- trunk/docs/user-manual/en/queue-attributes.xml 2009-05-22 12:04:34 UTC (rev 7003)
+++ trunk/docs/user-manual/en/queue-attributes.xml 2009-05-22 17:59:11 UTC (rev 7004)
@@ -1,9 +1,9 @@
<?xml version="1.0" encoding="UTF-8"?>
<chapter id="queue-attributes">
<title>Queue Attributes</title>
- <para>Queue attributes can be set in one of 2 ways. Either by configuring them via the
- configuration file or when using the core API. This chapter will explain how to configure
- each attribute and what effect the attribute has.</para>
+ <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
@@ -12,21 +12,22 @@
configuration file.</para>
<programlisting><queue name="selectorQueue">
<entry name="/queue/selectorQueue"/>
- <filter string="color='red'"/>
+ <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 queue will be
+ 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 filter element defines what filter or message selector the predefined queue will
- have. This is an optional element with a default of null when ommitted.</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 ommitted.</para>
<para>The durable element specifies whether the queue will be persisted. This again is
optional and defaults to true if ommited.</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>
+ <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>
@@ -47,17 +48,21 @@
<listitem>
<para>There is no entry element.</para>
</listitem>
+ <listitem>
+ <para>The filter uses the <xref linkend="filter-expressions">core filter
+ syntax</xref>, <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 JMS 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
- afore 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>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 the <xref linkend="management">management section</xref> for the API
for creating queues.</para>
</section>
Modified: trunk/docs/user-manual/en/scheduled-messages.xml
===================================================================
--- trunk/docs/user-manual/en/scheduled-messages.xml 2009-05-22 12:04:34 UTC (rev 7003)
+++ trunk/docs/user-manual/en/scheduled-messages.xml 2009-05-22 17:59:11 UTC (rev 7004)
@@ -1,17 +1,17 @@
<?xml version="1.0" encoding="UTF-8"?>
<chapter id="scheduled-messages">
<title>Scheduled Messages</title>
- <para>Scheduled messages are delivered at a time specified by the sender rather than when request
- by the receiver.</para>
- <para>Messages are scheduled for later delivery if they have a well-known scheduled delivery
- property set.</para>
+ <para>Scheduled messages differ from normal messages in that they won't be delivered until a
+ specified time in the future, at the earliest.</para>
+ <para>To do this, a special property is set on the message before sending it.</para>
<section>
<title>Scheduled Delivery Property</title>
<para>The property name used to identify a scheduled message is <literal
>"_JBM_SCHED_DELIVERY"</literal> (or the constant <literal
>MessageImpl.HDR_SCHEDULED_DELIVERY_TIME</literal>).</para>
<para>The specified value must be a <literal>long</literal> corresponding to the time the
- message must be delivered (in milliseconds).</para>
+ message must be delivered (in milliseconds). An example of sending a scheduled message
+ using the JMS API is as follows.</para>
<programlisting>
TextMessage message =
session.createTextMessage("This is a scheduled message message which will be delivered
@@ -23,7 +23,8 @@
// message will not be received immediately but 5 seconds later
TextMessage messageReceived = (TextMessage) consumer.receive();
- </programlisting>
+ </programlisting>
+ <para>Scheduled messages can also be sent using the core API, by setting the same property on the core message before sending.</para>
</section>
<section>
<title>Example</title>
Modified: trunk/docs/user-manual/en/security.xml
===================================================================
--- trunk/docs/user-manual/en/security.xml 2009-05-22 12:04:34 UTC (rev 7003)
+++ trunk/docs/user-manual/en/security.xml 2009-05-22 17:59:11 UTC (rev 7004)
@@ -6,15 +6,15 @@
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 10000.</para>
+ 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 section [LINK] 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>As explained <xref linkend="using-core">here</xref> 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>
@@ -68,8 +68,9 @@
</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 the chapter [LINK]. The above security block applies to any
- address that starts with the string "globalqueues.europe.":</para>
+ wildcard syntax please see the chapter on <xref linkend="wildcard-syntax">wildcard
+ syntax</xref>.. 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
@@ -83,8 +84,8 @@
<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 section
- [LINK]</para>
+ <para>For more information on configuring the security manager please see <xref
+ linkend="change-security-manager">this</xref> section.</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>
@@ -103,10 +104,12 @@
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 send and
- consume for the role europe-users. The permissions createDurableQueue,
- deleteDurableQueue, createTempQueue, deleteTempQueue are not inherited from the other
- security-setting block.</para>
+ '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>
@@ -116,14 +119,15 @@
<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 the section
- [LINK]</para>
+ <para>For more information on configuring the SSL transport please see the chapter on <xref
+ linkend="configuring-transports">configuring transports</xref>.</para>
</section>
<section>
<title>Basic user credentials</title>
<para> JBoss Messaging ships with a security manager implementation that reads user
- credentials, i.e. usernames, passwords and role information from an xml file on the
- classpath <literal>jbm-users.xml</literal>. This is the default security manager.</para>
+ 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>
@@ -162,7 +166,7 @@
>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>
+ <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
@@ -178,8 +182,8 @@
<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
+ <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
@@ -192,8 +196,8 @@
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 JAASSecurityManager in the beans file.
- Here's an example:</para>
+ 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">
@@ -242,12 +246,13 @@
is configured.</para>
</section>
<section>
- <title>Changing the Management password for Clustering</title>
+ <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
- the management chapter for instructions on how to do this.</para>
+ the <xref linkend="management">management chapter</xref> for instructions on how to do
+ this.</para>
</section>
</chapter>
Modified: trunk/docs/user-manual/en/send-guarantees.xml
===================================================================
--- trunk/docs/user-manual/en/send-guarantees.xml 2009-05-22 12:04:34 UTC (rev 7003)
+++ trunk/docs/user-manual/en/send-guarantees.xml 2009-05-22 17:59:11 UTC (rev 7004)
@@ -51,14 +51,14 @@
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</emphasis>
- feature.</para>
+ Messaging's advanced <xref linkend="asynchronous-send-acknowledgements">asynchronous
+ send acknowledgements</xref> feature.</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>
+ >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
@@ -79,10 +79,12 @@
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. The default value is <literal
- >false</literal></para>
+ 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>
+ <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 section <xref
@@ -93,8 +95,8 @@
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 with a network round trip between the server and the client of 0.25
- ms.</para>
+ 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
@@ -104,13 +106,13 @@
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 on one direction and
+ 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 much 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>
+ 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
@@ -122,8 +124,8 @@
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 the send acknowledgements example for a full working example
- [LINK]</para>
+ <para>Please see the <xref linkend="asynchronous-send-acknowledgements-example">send
+ acknowledgements exampl</xref>e for a full working example.</para>
</section>
</section>
</chapter>
Modified: trunk/docs/user-manual/en/thread-pooling.xml
===================================================================
--- trunk/docs/user-manual/en/thread-pooling.xml 2009-05-22 12:04:34 UTC (rev 7003)
+++ trunk/docs/user-manual/en/thread-pooling.xml 2009-05-22 17:59:11 UTC (rev 7004)
@@ -16,23 +16,22 @@
<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>
+ 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>
+ 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
@@ -43,8 +42,8 @@
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>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
@@ -55,12 +54,12 @@
<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 the section on message
- expiry [LINK].</para>
+ <para>For more information on configuring the reaper, please see the section on <xref
+ linkend="message-expiry">message expiry</xref>.</para>
</section>
<section>
<title>Asychronous IO</title>
- <para>Two threads are used on Asynchronous IO files. One for polling events, and one for
+ <para>Two threads are used on asynchronous IO files. One for polling events, and one for
writing data. </para>
<para>The thread poller is used by the native layer to receive and dispatch events. You
will find it on a thread dump with the prefix JBM-AIO-poller-pool. JBoss Messaging
@@ -78,10 +77,10 @@
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>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>
@@ -91,8 +90,8 @@
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>
+ <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);
Modified: trunk/docs/user-manual/en/undelivered-messages.xml
===================================================================
--- trunk/docs/user-manual/en/undelivered-messages.xml 2009-05-22 12:04:34 UTC (rev 7003)
+++ trunk/docs/user-manual/en/undelivered-messages.xml 2009-05-22 17:59:11 UTC (rev 7004)
@@ -8,12 +8,12 @@
<para>There are 2 ways to deal with these undelivered messages:</para>
<itemizedlist>
<listitem>
- <para><literal>delayed redelivery</literal></para>
+ <para>Delayed redelivery.</para>
<para>It is possible to delay messages redelivery to let the client some time to recover
from transient failures and not overload its network or CPU resources</para>
</listitem>
<listitem>
- <para><literal>dead letter address</literal></para>
+ <para>Dead Letter Address.</para>
<para>It is also possible to configure a dead letter address so that after a specified
number of unsuccessful deliveries, messages are removed from the queue and will not be
delivered again</para>
@@ -44,9 +44,9 @@
</section>
<section>
<title>Example</title>
- <para>The <ulink url="../../../../examples/jms/delayed-redelivery/readme.html"
- ><literal>delayed-redelivery</literal> example</ulink> shows how delayed
- redelivery is configured and used with JMS.</para>
+ <para>The <ulink url="../../../../examples/jms/delayed-redelivery/readme.html"><literal
+ >delayed-redelivery</literal> example</ulink> shows how delayed redelivery is
+ configured and used with JMS.</para>
</section>
</section>
<section>
@@ -55,6 +55,8 @@
what is causing the unsuccessful deliveries), messaging systems define dead letter
messages: after a specified unsuccessful delivery attempts, the message is removed from the
queue and send instead to a dead letter address. </para>
+ <para>Any dead letter messages can then be diverted to queue(s) where they can later be
+ perused by the system administrator for action to be taken.</para>
<para>JBoss Messaging's addresses can be assigned a dead letter address. Once the messages
have be unsuccessfully delivered for a given number of attempts, they are removed from the
queue and sent to the dead letter address. These <emphasis>dead letter</emphasis> messages
@@ -73,8 +75,8 @@
</programlisting>
<para>If a <literal>dead-letter-address</literal> is not specified, messages will removed
after <literal>max-delivery-attempts</literal> unsuccessful attempts.</para>
- <para>By default, messages are redelivered 10 times at the maximum. Set
- <literal>max-delivery-attempts</literal> to -1 for infinite redeliveries.</para>
+ <para>By default, messages are redelivered 10 times at the maximum. Set <literal
+ >max-delivery-attempts</literal> to -1 for infinite redeliveries.</para>
<para>For example, a dead letter can be set globally for a set of matching addresses and
you can set <literal>max-delivery-attempts</literal> to -1 for a specific address
setting to allow infinite redeliveries only for this address.</para>
@@ -95,9 +97,9 @@
</section>
<section>
<title>Example</title>
- <para>The <ulink url="../../../../examples/jms/dead-letter/readme.html"
- ><literal>dead-letter</literal> example</ulink> shows how dead letter is
- configured and used with JMS.</para>
+ <para>The <ulink url="../../../../examples/jms/dead-letter/readme.html"><literal
+ >dead-letter</literal> example</ulink> shows how dead letter is configured and
+ used with JMS.</para>
</section>
</section>
<section id="configuring.delivery.count.persistence">
@@ -117,10 +119,10 @@
<para>As this behavior breaks strict JMS semantics, JBoss Messaging allows to persist delivery
count before message delivery but disabled it by default for performance
implications.</para>
- <para>To enable it, set <literal>persist-delivery-count-before-delivery</literal> to
- <literal>true</literal> in <literal>jbm-configuration.xml</literal>:</para>
+ <para>To enable it, set <literal>persist-delivery-count-before-delivery</literal> to <literal
+ >true</literal> in <literal>jbm-configuration.xml</literal>:</para>
<programlisting>
- <persist-delivery-count-before-delivery>true</persist-delivery-count-before-delivery>
+<persist-delivery-count-before-delivery>true</persist-delivery-count-before-delivery>
</programlisting>
</section>
</chapter>
Modified: trunk/docs/user-manual/en/using-core.xml
===================================================================
--- trunk/docs/user-manual/en/using-core.xml 2009-05-22 12:04:34 UTC (rev 7003)
+++ trunk/docs/user-manual/en/using-core.xml 2009-05-22 17:59:11 UTC (rev 7004)
@@ -1,17 +1,18 @@
<?xml version="1.0" encoding="UTF-8"?>
<chapter id="using-core">
<title>Using Core</title>
- <para>JBoss Messaging core is a completely JMS agnostic messaging system with its own core
+ <para>JBoss Messaging core is a completely JMS-agnostic messaging system with its own core
API.</para>
<para>If you don't want to use JMS you can use the core API directly. The core API provides all
- the functionality of JMS but without much of the complications. It also provides features
- that are not normally available using JMS.</para>
+ the functionality of JMS but without much of the complexity. It also provides features that
+ are not normally available using JMS.</para>
<section>
<title>Core Messaging Concepts</title>
<para>Some of the core messaging concepts are similar to JMS concepts, but core messaging
concepts differ in some ways. In general the core messaging API is simpler than the JMS
API, since we remove distinctions between queues, topics and subscriptions. We'll
- discuss each of the major core messaging concepts in turn:</para>
+ discuss each of the major core messaging concepts in turn, but for to see the API in
+ detail please consult the javadoc.</para>
<section>
<title>Message</title>
<para>A message is the unit of data which is sent between clients and servers.</para>
@@ -23,7 +24,7 @@
is being sent to. When the message arrives on the server it is routed to any queues
that are bound to the address. An address may have many queues bound to it or even
none.</para>
- <para>Messages can either be durable or non durable. Durable messages in a durable queue
+ <para>Messages can be either durable or non durable. Durable messages in a durable queue
will survive a server crash or restart. Non durable messages will never survive a
server crash or restart.</para>
<para>Messages can be specified with a priority value betwen 0 and 9. 0 represents the
@@ -61,25 +62,26 @@
<para>Queues can also be temporary, meaning they are automatically deleted when the
client connection is closed, if they are not explicitly deleted before that.</para>
<para>Queues can be bound with an optional filter expression. If a filter expression is
- supplied then the server will only route messages who match that filter expression
+ supplied then the server will only route messages that match that filter expression
to any queues bound to the address.</para>
<para>Many queues can be bound to a single address. A particular queue is only bound to
a maximum of one address.</para>
</section>
<section>
<title>ClientSessionFactory</title>
- <para>Clients use <literal>ClientSessionFactory</literal> instances to create
- <literal>ClientSession</literal> instances.
- <literal>ClientSessionFactory</literal> instances know how to connect to the
- server to create sessions.</para>
+ <para>Clients use <literal>ClientSessionFactory</literal> instances to create <literal
+ >ClientSession</literal> instances. <literal>ClientSessionFactory</literal>
+ instances know how to connect to the server to create sessions, and are configurable
+ with many settings.</para>
</section>
<section>
<title>ClientSession</title>
<para>A client uses a ClientSession for consuming and producing messages and for
grouping them in transactions. ClientSession instances can support both
- transactional and non transactional semantics and also provide an
- <literal>XAResource</literal> interface so messaging operations can be performed
- as part of a JTA transaction.</para>
+ transactional and non transactional semantics and also provide an <literal
+ >XAResource</literal> interface so messaging operations can be performed as part
+ of a <ulink url="http://java.sun.com/javaee/technologies/jta/index.jsp">JTA</ulink>
+ transaction.</para>
<para>ClientSession instances group ClientConsumers and ClientProducers.</para>
</section>
<section>
@@ -92,25 +94,28 @@
</section>
<section>
<title>ClientProducer</title>
- <para>Clients create <literal>ClientProducer</literal> instances on
- <literal>ClientSession</literal> instances so they can send messages.
- ClientProducer instances can specify an address to which all sent messages are
- routed, or they can have no specified address, and the address is specified at send
- time for the message.</para>
+ <para>Clients create <literal>ClientProducer</literal> instances on <literal
+ >ClientSession</literal> instances so they can send messages. ClientProducer
+ instances can specify an address to which all sent messages are routed, or they can
+ have no specified address, and the address is specified at send time for the
+ message.</para>
</section>
</section>
<section>
<title>A simple example of using Core</title>
<para>Here's a very simple program using the core messaging API to send and receive a
message:</para>
- <programlisting>ClientSessionFactory nettyFactory = new ClientSessionFactoryImpl(
- new TransportConfiguration(
- InVMConnectorFactory.class.getName()), null);
+ <programlisting>
+ClientSessionFactory nettyFactory = new ClientSessionFactoryImpl(
+ new TransportConfiguration(
+ InVMConnectorFactory.class.getName()));
ClientSession session = nettyFactory.createSession();
+
session.createQueue("example", "example", true);
ClientProducer producer = session.createProducer("example");
+
ClientMessage message = session.createClientMessage(true);
message.getBody().writeString("Hello");
@@ -122,6 +127,7 @@
ClientConsumer consumer = session.createConsumer("example");
ClientMessage msgReceived = consumer.receive();
+
System.out.println("message = " + msgReceived.getBody().readString());
session.close();</programlisting>
Modified: trunk/docs/user-manual/en/using-server.xml
===================================================================
--- trunk/docs/user-manual/en/using-server.xml 2009-05-22 12:04:34 UTC (rev 7003)
+++ trunk/docs/user-manual/en/using-server.xml 2009-05-22 17:59:11 UTC (rev 7004)
@@ -140,7 +140,7 @@
>jbm-configuration.xml</literal> configuration when set to false mans that the
other configuration files are not loaded. This is true by default.</para>
</note>
- <para>It is also possible to use system property substitution in all the config files. by
+ <para>It is also possible to use system property substitution in all the config files. by
replacing a value with the name of a system property. Here is an example of this with a
connector config:</para>
<programlisting><connector name="netty">
@@ -243,7 +243,7 @@
<para>MBeanServer</para>
<para>In order to provide a JMX management interface a JMS MBean server is necessary
in which to register the management objects. Normally this is just the default
- platform MBean Server available in the JVM instance. If you don't want to
+ platform MBean server available in the JVM instance. If you don't want to
provide a JMX management interface this can be commented out or removed.</para>
</listitem>
<listitem>
@@ -264,8 +264,7 @@
</listitem>
<listitem>
<para>MessagingServer</para>
- <para>This is the JMS agnostic core server. It's where 99% of the magic
- happens</para>
+ <para>This is the core server. It's where 99% of the magic happens</para>
</listitem>
<listitem>
<para>JMSServerManager</para>
Modified: trunk/docs/user-manual/en/wildcard-routing.xml
===================================================================
--- trunk/docs/user-manual/en/wildcard-routing.xml 2009-05-22 12:04:34 UTC (rev 7003)
+++ trunk/docs/user-manual/en/wildcard-routing.xml 2009-05-22 17:59:11 UTC (rev 7004)
@@ -1,13 +1,20 @@
<?xml version="1.0" encoding="UTF-8"?>
<chapter id="wildcard-routing">
<title>Routing Messages With Wild Cards</title>
- <para>JBoss Messaging allows the routing of messages via wildcard addresses. If a consumer is
- created with an address of say <literal>queue.*</literal> then it will receive any messages
- sent to addresses that match this, for instance <literal>queue.newsQueue</literal> or
- <literal>queue.mailQueue</literal>. </para>
+ <para>JBoss Messaging allows the routing of messages via wildcard addresses.</para>
+ <para>If a consumer is created with an address of say <literal>queue.news.#</literal> then it
+ will receive any messages sent to addresses that match this, for instance <literal
+ >queue.news.europe</literal> or <literal>queue.news.usa</literal> or <literal
+ >queue.news.usa.sport</literal>. This allows a consumer to consume messages which are
+ sent to a <emphasis>hierarchy</emphasis> of addresses, rather than the consumer having to
+ specify a specific address.</para>
+ <note>
+ <para>In JMS terminoligy this allows "topic hierarchies" to be created.</para>
+ </note>
<para>To enable this functionality set the property <literal>wild-card-routing-enabled</literal>
- in the <literal>jbm-configuration.xml</literal> file to true. This is true by
- default.</para>
- <para>For more information on wild cards take a look at the <link linkend="wildcard-syntax"
- >wildcard syntax</link> chapter.</para>
+ in the <literal>jbm-configuration.xml</literal> file to <literal>true</literal>. This is
+ <literal>true</literal> by default.</para>
+ <para>For more information on the wild card syntax take a look at the <link
+ linkend="wildcard-syntax">wildcard syntax</link> chapter, also see the <xref
+ linkend="topic-hierarchy-example">topic hierarchy example</xref>.</para>
</chapter>
Modified: trunk/docs/user-manual/en/wildcard-syntax.xml
===================================================================
--- trunk/docs/user-manual/en/wildcard-syntax.xml 2009-05-22 12:04:34 UTC (rev 7003)
+++ trunk/docs/user-manual/en/wildcard-syntax.xml 2009-05-22 17:59:11 UTC (rev 7004)
@@ -1,18 +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 AMQP [LINK]</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>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>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>
-
-
-
+ <para>The wildcard 'news.*.sport' would match 'news.europe.sport' and also 'news.usa.sport', but
+ not 'news.europe.politics'.</para>
</chapter>
-
More information about the jboss-cvs-commits
mailing list