[jboss-cvs] JBoss Messaging SVN: r6788 - in trunk/docs/user-manual/en: modules and 1 other directory.
jboss-cvs-commits at lists.jboss.org
jboss-cvs-commits at lists.jboss.org
Thu May 14 07:01:19 EDT 2009
Author: timfox
Date: 2009-05-14 07:01:19 -0400 (Thu, 14 May 2009)
New Revision: 6788
Added:
trunk/docs/user-manual/en/modules/duplicate-detection.xml
Modified:
trunk/docs/user-manual/en/master.xml
trunk/docs/user-manual/en/modules/connection-ttl.xml
Log:
duplicate detection
Modified: trunk/docs/user-manual/en/master.xml
===================================================================
--- trunk/docs/user-manual/en/master.xml 2009-05-14 10:53:17 UTC (rev 6787)
+++ trunk/docs/user-manual/en/master.xml 2009-05-14 11:01:19 UTC (rev 6788)
@@ -36,11 +36,12 @@
<!ENTITY jms-bridge SYSTEM "modules/jms-bridge.xml">
<!ENTITY ha-jndi SYSTEM "modules/ha-jndi.xml">
<!ENTITY xa-recovery SYSTEM "modules/xa-recovery.xml">
+ <!ENTITY duplicate-detection SYSTEM "modules/duplicate-detection.xml">
<!ENTITY core-bridges SYSTEM "modules/core-bridges.xml">
<!ENTITY clusters SYSTEM "modules/clusters.xml">
<!ENTITY ha SYSTEM "modules/ha.xml">
<!ENTITY interoperability SYSTEM "modules/interoperability.xml">
- <!ENTITY perf-tuning SYSTEM "modules/perf-tuning.xml">
+ <!ENTITY perf-tuning SYSTEM "modules/perf-tuning.xml">
]>
<book lang="en">
<bookinfo>
@@ -85,6 +86,7 @@
&jms-bridge;
&ha-jndi;
&core-bridges;
+ &duplicate-detection;
&clusters;
&ha;
&interoperability;
Modified: trunk/docs/user-manual/en/modules/connection-ttl.xml
===================================================================
--- trunk/docs/user-manual/en/modules/connection-ttl.xml 2009-05-14 10:53:17 UTC (rev 6787)
+++ trunk/docs/user-manual/en/modules/connection-ttl.xml 2009-05-14 11:01:19 UTC (rev 6788)
@@ -1,6 +1,6 @@
<?xml version="1.0" encoding="UTF-8"?>
<chapter id="clusters">
- <title>Connection Clean-up, Time To Live (TTL), and number of client connections</title>
+ <title>Dead Connections, Time To Live 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>
@@ -56,62 +56,90 @@
}
}
</programlisting>
- <para>Unfortunately users don't always write well behaved applications, and sometimes clients crash so don't have a chance to cleanup 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 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>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>
+ <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
+ 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>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>
<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>
- <para>If you're using JMS it's defined by the <literal>ConnectionTTL</literal> attribute on a <literal>JBossConnectionFactory</literal> instance,
- or if you're deploying JMS connection factory instances direct into JNDI on the server side, you can specify it in the xml config, using
- the parameter <literal>connection-ttl</literal>.</para>
- <para>The default value for connection ttl is <literal>300000</literal>ms, i.e. 5 minutes.</para>
- <para>If you do not wish clients to be able to specify their own connection TTL, you can override all values used by a global value set
- on the server side. This can be done by specifying the <literal>connection-ttl-override</literal> attribute in the server side configuration. The default
- value for <literal>connection-ttl-override</literal> is <literal>-1</literal> which means "do not override" (i.e. let clients use their own values).</para>
- <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>
-
+ <para>The connection TTL is defined by the <literal>ConnectionTTL</literal> attribute on the
+ <literal>ClientSessionFactory</literal> instance.</para>
+ <para>If you're using JMS it's defined by the <literal>ConnectionTTL</literal> attribute on
+ a <literal>JBossConnectionFactory</literal> instance, or if you're deploying JMS
+ connection factory instances direct into JNDI on the server side, you can specify it in
+ the xml config, using the parameter <literal>connection-ttl</literal>.</para>
+ <para>The default value for connection ttl is <literal>300000</literal>ms, i.e. 5
+ minutes.</para>
+ <para>If you do not wish clients to be able to specify their own connection TTL, you can
+ override all values used by a global value set on the server side. This can be done by
+ specifying the <literal>connection-ttl-override</literal> attribute in the server side
+ configuration. The default value for <literal>connection-ttl-override</literal> is
+ <literal>-1</literal> which means "do not override" (i.e. let clients use their own
+ values).</para>
+ <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>
</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>
- <para>Every <literal>pingPeriod</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>
- <para></para>
+ <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>
+ <para>Every <literal>pingPeriod</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>
+ <para/>
</section>
-
<section>
- <title>Number of client connections per factory</title>
- <para>Each <literal>ClientSessionFactory</literal> creates connections on demand to the same server as you create sessions. Each instance will
- create up to a maximum of <literal>maxConnections</literal> connections to the same server. Subsequent sessions will use one of the already created connections
- in a round-robin fashion.</para>
- <para>To illustrate this, let's say <literal>maxConnections</literal> is set to <literal>8</literal>. The first eight sessions that you create
- will have a new underlying connection created for them, the next eight you create will use one of the previously created connections.</para>
- <para>The default value for <literal>maxConnections</literal> is <literal>8</literal>, if you prefer you can set it to a lower value so each factory
- maintains only one underlying connection. We choose a default value of <literal>8</literal> because on the server side each packet read from a particular
- connection is read serially by the same thread, so if all traffic from the 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>
+ <title>Session Multiplexing</title>
+ <para>Each <literal>ClientSessionFactory</literal> creates connections on demand to the same
+ server as you create sessions. Each instance will create up to a maximum of <literal
+ >maxConnections</literal> connections to the same server. Subsequent sessions will
+ use one of the already created connections in a round-robin fashion.</para>
+ <para>To illustrate this, let's say <literal>maxConnections</literal> is set to <literal
+ >8</literal>. The first eight sessions that you create will have a new underlying
+ connection created for them, the next eight you create will use one of the previously
+ created connections.</para>
+ <para>The default value for <literal>maxConnections</literal> is <literal>8</literal>, if
+ you prefer you can set it to a lower value so each factory maintains only one underlying
+ connection. We choose a default value of <literal>8</literal> because on the server side
+ each packet read from a particular connection is read serially by the same thread, so if
+ all traffic from the 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>
+ <para>To change the value of <literal>maxConnections</literal> simply use the setter method
+ on the <literal>ClientSessionFactory</literal> immediately after constructing it, or if
+ you are using JMS use the setter on the <literal>JBossConnectionFactory</literal> or
+ specify the <literal>max-connections</literal> parameter in the connection factory xml
+ configuration in <literal>jbm-jms.xml</literal>.</para>
</section>
-
-
</chapter>
Added: trunk/docs/user-manual/en/modules/duplicate-detection.xml
===================================================================
--- trunk/docs/user-manual/en/modules/duplicate-detection.xml (rev 0)
+++ trunk/docs/user-manual/en/modules/duplicate-detection.xml 2009-05-14 11:01:19 UTC (rev 6788)
@@ -0,0 +1,127 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<chapter id="duplicate-detection">
+ <title>Duplicate Message Detection</title>
+ <para>JBoss Messaging includes powerful automatic duplicate message detection, filtering out
+ duplicate messages without you having to code your own fiddly duplicate detection logic at
+ the application level. This chapter will explain what duplicate detection is, how JBoss
+ Messaging uses it and how and where to configure it.</para>
+ <para>When sending messages from a client to a server, or indeed from a server to another
+ server, if the target server or connection fails sometime after sending the message, but
+ before the sender receives a response that the send (or commit) was processed successfully
+ then the sender cannot know for sure if the message was sent successfully to the
+ address.</para>
+ <para>If the target server or connection failed after the send was received and processed but
+ before the response was sent back then the message will have been sent to the address
+ successfully, but if the target server or connection failed before the send was received and
+ finished processing then it will not have been sent to the address successfully. From the
+ senders point of view it's not possible to distinguish these two cases.</para>
+ <para>When the server recovers this leaves the client in a difficult situation. It knows the
+ target server failed, but it does not know if the last message reached its destination ok.
+ If it decides to resend the last message, then that could result in a duplicate message
+ being sent to the address. If each message was an order or a trade then this could result in
+ the order being fulfilled twice or the trade being double booked. This is clearly not a
+ desirable situation.</para>
+ <para>Sending the message(s) in a transaction does not help out either. If the server or
+ connection fails while the transaction commit is being processed it is also indeterminate
+ whether the transaction was successfully committed or not!</para>
+ <para>To solve these issues JBoss Messaging provides automatic duplicate messages detection for
+ messages sent to addresses.</para>
+ <section>
+ <title>Using Duplicate Detection for Message Sending</title>
+ <para>Enabling duplicate message detection for sent messages is simple: you just need to set
+ a 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 receieved a message
+ with the same value before then it will ignore the message.</para>
+ <para>If you're sending messages in a transaction then you don't have to set the property
+ for <emphasis>every</emphasis> message you send in that transaction, you only need to
+ set it once in the transaction. If the server detects a duplicate message for any
+ message in the transaction, then it will ignore the entire transaction.</para>
+ <para>The name of the property that you set is given by the value of <literal
+ >org.jboss.messaging.core.message.impl.HDR_DUPLICATE_DETECTION_ID</literal>, which
+ is <literal>_JBM_DUPL_ID</literal></para>
+ <para>The value of the property can be of type <literal>byte[]</literal> or <literal>SimpleString</literal> if you're using the
+ core API. If you're using JMS it must be a <literal>String</literal>, and it's valid should be unique. An easy way of generating
+ a unique id is by generating a UUID.</para>
+ <para>Here's an example of setting the property using the core API:</para>
+ <programlisting>
+...
+
+ClientMessage message = session.createClientMessage(true);
+
+SimpleString myUniqueID = "This is my unique id"; // Could use a UUID for this
+
+message.setStringProperty(HDR_DUPLICATE_DETECTION_ID, myUniqueID);
+
+...
+ </programlisting>
+ <para>And here's an example using the JMS API:</para>
+ <programlisting>
+...
+
+Message jmsMessage = session.createMessage();
+
+String myUniqueID = "This is my unique id"; // Could use a UUID for this
+
+message.setStringProperty(HDR_DUPLICATE_DETECTION_ID.toString(), myUniqueID);
+
+...
+ </programlisting>
+ </section>
+ <section>
+ <title>Configuring the Duplicate ID Cache</title>
+ <para>The server maintains caches of received values of the <literal
+ >org.jboss.messaging.core.message.impl.HDR_DUPLICATE_DETECTION_ID</literal> property
+ sent to each address. Each address has its own distinct cache.</para>
+ <para>The cache is a circular fixed size cache. If the cache has a maximum size of <literal
+ >n</literal> elements, then the <literal>n + 1</literal>th id stored will overwrite
+ the <literal>0</literal>th element in the cache.</para>
+ <para>The maximum size of the cache is configured by the parameter <literal
+ >id-cache-size</literal> in <literal>jbm-configuration.xml</literal>, the default
+ value is <literal>2000</literal> elements.</para>
+ <para>The caches can also be configured to persist to disk or not. This is configured by the
+ parameter <literal>persist-id-cache</literal>, also in <literal
+ >jbm-configuration.xml</literal>. If this is set to <literal>true</literal> then
+ each id will be persisted to permanent storage as they are received. The default value
+ for this parameter is <literal>true</literal>.</para>
+ <note>
+ <para>When choosing a size of the duplicate id cache be sure to set it to a larger
+ enough size so if you resend messages all the previously sent ones are in the cache
+ not having been overwritten.</para>
+ </note>
+ </section>
+ <section>
+ <title>Duplicate Detection and Bridges</title>
+ <para>Core bridges can configured to automatically add a unique duplicate id value (if there
+ isn't already one in the message) before forwarding the message to it's target. This
+ ensures that if the target server crashes or the connection is interrupted and the
+ bridge resends the message, then if it has already been received by the target server,
+ it will be ignored.</para>
+ <para>To configure a core bridge to add the duplicate id header, simply set the <parameter
+ >use-duplicate-detection</parameter> to <literal>true</literal> when configuring a
+ bridge in <literal>jbm-configuration.xml</literal>.</para>
+ <para>The default value for this parameter is <literal>true</literal>.</para>
+ <para>For more information on core bridges and how to configure them see section
+ [LINK]</para>
+ </section>
+ <section>
+ <title>Duplicate Detection and Cluster Connections</title>
+ <para>Cluster connections internally use core bridges to move messages reliable between
+ nodes of the cluster. Consequently they can also be configured to insert the duplicate
+ id header for each message they move using their internal bridges.</para>
+ <para>To configure a cluster connection to add the duplicate id header, simply set the
+ <parameter>use-duplicate-detection</parameter> to <literal>true</literal> when
+ configuring a cluster connection in <literal>jbm-configuration.xml</literal>.</para>
+ <para>The default value for this parameter is <literal>true</literal>.</para>
+ <para>For more information on cluster connections and how to configure them see section
+ [LINK]</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>
+ </section>
+</chapter>
More information about the jboss-cvs-commits
mailing list