Repository: qpid-broker-j
Updated Branches:
  refs/heads/master 876bcb7af -> 63c315f07


QPID-8091: [Broker-J] Update transaction timeout chapter in docbook

* Remove note regarding AMQP 1.0
* Generalise from 'producer transaction timeout' to 'transaction timeout'.  The 
former was only true when using the Qpid JMS AMQP 0-x client
  (which delayed acking the messages until the application called commit).
* Update the operational log messages


Project: http://git-wip-us.apache.org/repos/asf/qpid-broker-j/repo
Commit: http://git-wip-us.apache.org/repos/asf/qpid-broker-j/commit/63c315f0
Tree: http://git-wip-us.apache.org/repos/asf/qpid-broker-j/tree/63c315f0
Diff: http://git-wip-us.apache.org/repos/asf/qpid-broker-j/diff/63c315f0

Branch: refs/heads/master
Commit: 63c315f07553dcdf32e2de1888f1cb9749e15d5c
Parents: 876bcb7
Author: Keith Wall <kw...@apache.org>
Authored: Fri Feb 9 13:56:37 2018 +0000
Committer: Keith Wall <kw...@apache.org>
Committed: Fri Feb 9 13:56:37 2018 +0000

----------------------------------------------------------------------
 ...er-Appendix-Operational-Logging-Messages.xml |  45 +++---
 .../src/docbkx/Java-Broker-Runtime.xml          |   2 +-
 ...-Broker-Management-Managing-Virtualhosts.xml |   2 +-
 ...ker-Runtime-Producer-Transaction-Timeout.xml | 136 -------------------
 .../Java-Broker-Runtime-Transaction-Timeout.xml | 111 +++++++++++++++
 5 files changed, 136 insertions(+), 160 deletions(-)
----------------------------------------------------------------------


http://git-wip-us.apache.org/repos/asf/qpid-broker-j/blob/63c315f0/doc/java-broker/src/docbkx/Java-Broker-Appendix-Operational-Logging-Messages.xml
----------------------------------------------------------------------
diff --git 
a/doc/java-broker/src/docbkx/Java-Broker-Appendix-Operational-Logging-Messages.xml
 
b/doc/java-broker/src/docbkx/Java-Broker-Appendix-Operational-Logging-Messages.xml
index bf4460b..5cb314b 100644
--- 
a/doc/java-broker/src/docbkx/Java-Broker-Appendix-Operational-Logging-Messages.xml
+++ 
b/doc/java-broker/src/docbkx/Java-Broker-Appendix-Operational-Logging-Messages.xml
@@ -820,6 +820,29 @@
             </para>
           </entry>
         </row>
+        <row xml:id="Java-Broker-Appendix-Operation-Logging-Message-CHN-1010">
+          <entry morerows="1">CON-1010</entry>
+          <entry>Open Transaction : <replaceable>time</replaceable> ms</entry>
+        </row>
+        <row>
+          <entry>
+            <para>Indicates that a messaging transaction has been open for 
longer than that
+              permitted. See <xref 
linkend="Java-Broker-Runtime-Transaction-Timeout"/> for
+              more details.</para>
+          </entry>
+        </row>
+        <row xml:id="Java-Broker-Appendix-Operation-Logging-Message-CON-1011">
+          <entry morerows="1">CON-1011</entry>
+          <entry>Idle Transaction : <replaceable>time</replaceable> ms</entry>
+        </row>
+        <row>
+          <entry>
+            <para>Indicates that a messaging transaction has been idle for 
longer than that
+              permitted. See <xref 
linkend="Java-Broker-Runtime-Transaction-Timeout"/> for
+              more details.</para>
+          </entry>
+        </row>
+
 
       </tbody>
     </tgroup>
@@ -896,28 +919,6 @@
               See <xref linkend="Java-Broker-Concepts-Queue-OverflowPolicy"/> 
for more details.</para>
           </entry>
         </row>
-        <row xml:id="Java-Broker-Appendix-Operation-Logging-Message-CHN-1007">
-          <entry morerows="1">CHN-1007</entry>
-          <entry>Open Transaction : <replaceable>time</replaceable> ms</entry>
-        </row>
-        <row>
-          <entry>
-            <para>Indicates that a producer transaction has been open for 
longer than that
-              permitted. See <xref 
linkend="Java-Broker-Runtime-Producer-Transaction-Timeout"/> for
-              more details.</para>
-          </entry>
-        </row>
-        <row xml:id="Java-Broker-Appendix-Operation-Logging-Message-CHN-1008">
-          <entry morerows="1">CHN-1008</entry>
-          <entry>Idle Transaction : <replaceable>time</replaceable> ms</entry>
-        </row>
-        <row>
-          <entry>
-            <para>Indicates that a producer transaction has been idle for 
longer than that
-              permitted. See <xref 
linkend="Java-Broker-Runtime-Producer-Transaction-Timeout"/> for
-              more details.</para>
-          </entry>
-        </row>
         <row xml:id="Java-Broker-Appendix-Operation-Logging-Message-CHN-1009">
           <entry morerows="1">CHN-1009</entry>
           <entry>Discarded message : <replaceable>message number</replaceable> 
as no alternate

http://git-wip-us.apache.org/repos/asf/qpid-broker-j/blob/63c315f0/doc/java-broker/src/docbkx/Java-Broker-Runtime.xml
----------------------------------------------------------------------
diff --git a/doc/java-broker/src/docbkx/Java-Broker-Runtime.xml 
b/doc/java-broker/src/docbkx/Java-Broker-Runtime.xml
index 08e4250..1f56d61 100644
--- a/doc/java-broker/src/docbkx/Java-Broker-Runtime.xml
+++ b/doc/java-broker/src/docbkx/Java-Broker-Runtime.xml
@@ -24,7 +24,7 @@
   <title>Runtime</title>
   <xi:include xmlns:xi="http://www.w3.org/2001/XInclude"; 
href="runtime/Java-Broker-Runtime-Log-Files.xml"/>
   <xi:include xmlns:xi="http://www.w3.org/2001/XInclude"; 
href="runtime/Java-Broker-Runtime-Disk-Space-Management.xml"/>
-  <xi:include xmlns:xi="http://www.w3.org/2001/XInclude"; 
href="runtime/Java-Broker-Runtime-Producer-Transaction-Timeout.xml"/>
+  <xi:include xmlns:xi="http://www.w3.org/2001/XInclude"; 
href="runtime/Java-Broker-Runtime-Transaction-Timeout.xml"/>
   <xi:include xmlns:xi="http://www.w3.org/2001/XInclude"; 
href="runtime/Java-Broker-Runtime-Handling-Undeliverable-Messages.xml"/>
   <xi:include xmlns:xi="http://www.w3.org/2001/XInclude"; 
href="runtime/Java-Broker-Runtime-Close-On-No-Route.xml"/>
   <xi:include xmlns:xi="http://www.w3.org/2001/XInclude"; 
href="runtime/Java-Broker-Runtime-Flow-To-Disk.xml"/>

http://git-wip-us.apache.org/repos/asf/qpid-broker-j/blob/63c315f0/doc/java-broker/src/docbkx/management/managing/Java-Broker-Management-Managing-Virtualhosts.xml
----------------------------------------------------------------------
diff --git 
a/doc/java-broker/src/docbkx/management/managing/Java-Broker-Management-Managing-Virtualhosts.xml
 
b/doc/java-broker/src/docbkx/management/managing/Java-Broker-Management-Managing-Virtualhosts.xml
index 7b25425..ba8178c 100644
--- 
a/doc/java-broker/src/docbkx/management/managing/Java-Broker-Management-Managing-Virtualhosts.xml
+++ 
b/doc/java-broker/src/docbkx/management/managing/Java-Broker-Management-Managing-Virtualhosts.xml
@@ -95,7 +95,7 @@
         </listitem>
         <listitem>
           <para><emphasis>Store transaction timeouts</emphasis>. Warns of long 
running producer
-            transactions. See <xref 
linkend="Java-Broker-Runtime-Producer-Transaction-Timeout"/></para>
+            transactions. See <xref 
linkend="Java-Broker-Runtime-Transaction-Timeout"/></para>
         </listitem>
         <listitem>
           <para><emphasis>Synchronization policy</emphasis>. HA only. See 
<xref 
linkend="Java-Broker-High-Availability-Behaviour-SynchronizationPolicy"/></para>

http://git-wip-us.apache.org/repos/asf/qpid-broker-j/blob/63c315f0/doc/java-broker/src/docbkx/runtime/Java-Broker-Runtime-Producer-Transaction-Timeout.xml
----------------------------------------------------------------------
diff --git 
a/doc/java-broker/src/docbkx/runtime/Java-Broker-Runtime-Producer-Transaction-Timeout.xml
 
b/doc/java-broker/src/docbkx/runtime/Java-Broker-Runtime-Producer-Transaction-Timeout.xml
deleted file mode 100644
index 2931f67..0000000
--- 
a/doc/java-broker/src/docbkx/runtime/Java-Broker-Runtime-Producer-Transaction-Timeout.xml
+++ /dev/null
@@ -1,136 +0,0 @@
-<?xml version="1.0"?>
-<!--
-
- Licensed to the Apache Software Foundation (ASF) under one
- or more contributor license agreements.  See the NOTICE file
- distributed with this work for additional information
- regarding copyright ownership.  The ASF licenses this file
- to you under the Apache License, Version 2.0 (the
- "License"); you may not use this file except in compliance
- with the License.  You may obtain a copy of the License at
-
-   http://www.apache.org/licenses/LICENSE-2.0
-
- Unless required by applicable law or agreed to in writing,
- software distributed under the License is distributed on an
- "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
- KIND, either express or implied.  See the License for the
- specific language governing permissions and limitations
- under the License.
-
--->
-
-<section xmlns="http://docbook.org/ns/docbook"; version="5.0" 
xml:id="Java-Broker-Runtime-Producer-Transaction-Timeout">
- <title>Producer Transaction Timeout</title>
- <section role="h2" 
xml:id="Java-Broker-Runtime-Producer-Transaction-Timeout-GeneralInformation">
-  <title>General Information</title>
-  <note>
-   <para>
-    This feature is not implemented for producing applications using AMQP 1.0. 
 If a long running transaction is suspected
-    examine the connection statistic 
<literal>oldestTransactionStartTime</literal> to confirm if this is the case.
-   </para>
-  </note>
-  <para> The transaction timeout mechanism is used to control broker resources 
when clients
-   producing messages using transactional sessions hang or otherwise become 
unresponsive, or simply
-   begin a transaction and keep using it without ever calling <link 
xmlns:xlink="http://www.w3.org/1999/xlink"; 
xlink:href="${oracleJeeDocUrl}javax/jms/Session.html#commit">Session#commit()</link>.</para>
-  <para>Users can choose to configure an idleWarn or openWarn threshold, after 
which the identified
-   transaction should be logged as a WARN level alert as well as (more 
importantly) an idleClose or
-   openClose threshold after which the transaction and the connection it 
applies to will be
-   closed.</para>
-  <para>This feature is particularly useful in environments where the owner of 
the broker does not
-   have full control over the implementation of clients, such as in a shared 
services
-   deployment.</para>
-  <para>The following section provide more details on this feature and its 
use.</para>
- </section>
- <section role="h2" 
xml:id="Java-Broker-Runtime-Producer-Transaction-Timeout-Purpose">
-  <title>Purpose</title>
-  <para> This feature has been introduced to address the scenario where an 
open transaction on the
-   broker holds an open transaction on the persistent store. This can have 
undesirable consequences
-   if the store does not time out or close long-running transactions, such as 
with BDB. This can can
-   result in a rapid increase in disk usage size, bounded only by available 
space, due to growth of
-   the transaction log. </para>
- </section>
- <section role="h2" 
xml:id="Java-Broker-Runtime-Producer-Transaction-Timeout-Scope">
-  <title>Scope</title>
-  <para>Note that only <link xmlns:xlink="http://www.w3.org/1999/xlink"; 
xlink:href="${oracleJeeDocUrl}javax/jms/MessageProducer.html">MessageProducer</link>
 clients will be affected by a transaction timeout, since store
-   transaction lifespan on a consumer only spans the execution of the call to 
Session#commit() and
-   there is no scope for a long-lived transaction to arise.</para>
-  <para>It is also important to note that the transaction timeout mechanism is 
purely a JMS
-   transaction timeout, and unrelated to any other timeouts in the Qpid client 
library and will have
-   no impact on any RDBMS your application may utilise.</para>
- </section>
- <section role="h2" 
xml:id="Java-Broker-Runtime-Producer-Transaction-Timeout-Effect">
-  <title>Effect</title>
-  <para>Full details of configuration options are provided in the sections 
that follow. This section
-   gives a brief overview of what the Transaction Timeout feature can 
do.</para>
-  <section role="h3" 
xml:id="Java-Broker-Runtime-Producer-Transaction-Timeout-Effect-Broker-Side">
-   <title>Broker Logging and Connection Close</title>
-   <para>When the openWarn or idleWarn specified threshold is exceeded, the 
broker will log a WARN
-    level alert with details of the connection and channel on which the 
threshold has been exceeded,
-    along with the age of the transaction.</para>
-   <para>When the openClose or idleClose specified threshold value is 
exceeded, the broker will
-    throw an exception back to the client connection via the <link 
xmlns:xlink="http://www.w3.org/1999/xlink"; 
xlink:href="${oracleJeeDocUrl}javax/jms/ExceptionListener.html">ExceptionListener</link>,
 log the
-    action and then close the connection.</para>
-   <para>The example broker log output shown below is where the idleWarn 
threshold specified is
-    lower than the idleClose threshold and the broker therefore logs the idle 
transaction 3 times
-    before the close threshold is triggered and the connection closed 
out.</para>
-   <screen>CHN-1008 : Idle Transaction : 13,116 ms
-CHN-1008 : Idle Transaction : 14,116 ms
-CHN-1008 : Idle Transaction : 15,118 ms
-CHN-1003 : Close
-   </screen>
-   <para>The second example broker log output shown below illustrates the same 
mechanism operating
-    on an open transaction.</para>
-   <screen>
-CHN-1007 : Open Transaction : 12,406 ms
-CHN-1007 : Open Transaction : 13,406 ms
-CHN-1007 : Open Transaction : 14,406 ms
-CHN-1003 : Close
-   </screen>
-  </section>
-  <section role="h3" 
xml:id="Java-Broker-Runtime-Producer-Transaction-Timeout-Effect-Client-Side">
-   <title>Client Side Effect</title>
-   <para>After a Close threshold has been exceeded, the trigger client will 
receive this exception
-    on its <link xmlns:xlink="http://www.w3.org/1999/xlink"; 
xlink:href="${oracleJeeDocUrl}javax/jms/ExceptionListener.html">exception
-    listener</link>, prior to being disconnected:</para>
-   <computeroutput>org.apache.qpid.AMQConnectionClosedException: Error: Idle 
transaction timed out
-    [error code 506: resource error]</computeroutput>
-   <para>Any later attempt to use the connection will result in this exception 
being thrown:</para>
-   <screen>Producer: Caught an Exception: javax.jms.IllegalStateException: 
Object org.apache.qpid.client.AMQSession_0_8@129b0e1 has been closed
-    javax.jms.IllegalStateException: Object 
org.apache.qpid.client.AMQSession_0_8@129b0e1 has been closed
-    at org.apache.qpid.client.Closeable.checkNotClosed(Closeable.java:70)
-    at org.apache.qpid.client.AMQSession.checkNotClosed(AMQSession.java:555)
-    at 
org.apache.qpid.client.AMQSession.createBytesMessage(AMQSession.java:573)
-   </screen>
-   <para>Thus clients must be able to handle this case successfully, 
reconnecting where required and
-    registering an exception listener on all connections. This is critical, 
and must be communicated
-    to client applications by any broker owner switching on transaction 
timeouts.</para>
-  </section>
-
- </section>
- <section role="h2" 
xml:id="Java-Broker-Runtime-Producer-Transaction-Timeout-Configuration">
-  <title>Configuration</title>
-  <section role="h3" 
xml:id="Java-Broker-Runtime-Producer-Transaction-Timeout-Configuration-Overview">
-   <title>Configuration</title>
-   <para>The transaction timeouts can be specified when a new virtualhost is 
created or an exiting
-    virtualhost is edited.</para>
-   <para>We would recommend that only warnings are configured at first, which 
should allow broker
-    administrators to obtain an idea of the distribution of transaction 
lengths on their systems,
-    and configure production settings appropriately for both warning and 
closure. Ideally
-    establishing thresholds should be achieved in a representative UAT 
environment, with clients and
-    broker running, prior to any production deployment.</para>
-   <para>It is impossible to give suggested values, due to the large variation 
in usage depending on
-    the applications using a broker. However, clearly transactions should not 
span the expected
-    lifetime of any client application as this would indicate a hung 
client.</para>
-   <para>When configuring warning and closure timeouts, it should be noted 
that these only apply to
-    message producers that are connected to the broker, but that a timeout 
will cause the connection
-    to be closed - this disconnecting all producers and consumers created on 
that connection.</para>
-   <para>This should not be an issue for environments using Mule or Spring, 
where connection
-    factories can be configured appropriately to manage a single 
MessageProducer object per JMS
-    Session and Connection. Clients that use the JMS API directly should be 
aware that sessions
-    managing both consumers and producers, or multiple producers, will be 
affected by a single
-    producer hanging or leaving a transaction idle or open, and closed, and 
must take appropriate
-    action to handle that scenario.</para>
-  </section>
- </section>
-</section>

http://git-wip-us.apache.org/repos/asf/qpid-broker-j/blob/63c315f0/doc/java-broker/src/docbkx/runtime/Java-Broker-Runtime-Transaction-Timeout.xml
----------------------------------------------------------------------
diff --git 
a/doc/java-broker/src/docbkx/runtime/Java-Broker-Runtime-Transaction-Timeout.xml
 
b/doc/java-broker/src/docbkx/runtime/Java-Broker-Runtime-Transaction-Timeout.xml
new file mode 100644
index 0000000..f250364
--- /dev/null
+++ 
b/doc/java-broker/src/docbkx/runtime/Java-Broker-Runtime-Transaction-Timeout.xml
@@ -0,0 +1,111 @@
+<?xml version="1.0"?>
+<!--
+
+ Licensed to the Apache Software Foundation (ASF) under one
+ or more contributor license agreements.  See the NOTICE file
+ distributed with this work for additional information
+ regarding copyright ownership.  The ASF licenses this file
+ to you under the Apache License, Version 2.0 (the
+ "License"); you may not use this file except in compliance
+ with the License.  You may obtain a copy of the License at
+
+   http://www.apache.org/licenses/LICENSE-2.0
+
+ Unless required by applicable law or agreed to in writing,
+ software distributed under the License is distributed on an
+ "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ KIND, either express or implied.  See the License for the
+ specific language governing permissions and limitations
+ under the License.
+
+-->
+
+<section xmlns="http://docbook.org/ns/docbook"; version="5.0" 
xml:id="Java-Broker-Runtime-Transaction-Timeout">
+ <title>Transaction Timeout</title>
+ <section role="h2" 
xml:id="Java-Broker-Runtime-Transaction-Timeout-GeneralInformation">
+  <title>General Information</title>
+  <para> The transaction timeout mechanism is used to control broker resources 
when clients
+   using transactions hang, become unresponsive, or simply (due to programming 
error)
+   begin a transaction and keep using it without ever calling committing or 
rolling back.</para>
+  <para>Users can choose to configure an idleWarn or openWarn threshold, after 
which the identified
+   transaction should be logged as a WARN level alert as well as (more 
importantly) an idleClose or
+   openClose threshold after which the transaction and the connection it 
applies to will be
+   closed.</para>
+  <para>This feature is particularly useful in environments where the owner of 
the broker does not
+   have full control over the implementation of clients, such as in a shared 
services
+   deployment.</para>
+  <para>The following section provide more details on this feature and its 
use.</para>
+ </section>
+ <section role="h2" xml:id="Java-Broker-Runtime-Transaction-Timeout-Purpose">
+  <title>Purpose</title>
+  <para> This feature has been introduced to address the scenario where an 
open transaction on the
+   broker holds an open transaction on the persistent store. This can have 
undesirable consequences
+   if the store does not time out or close long-running transactions, such as 
with BDB. This can can
+   result in a rapid increase in disk usage size, bounded only by available 
space, due to growth of
+   the transaction log. </para>
+ </section>
+ <section role="h2" xml:id="Java-Broker-Runtime-Transaction-Timeout-Effect">
+  <title>Effect</title>
+  <para>Full details of configuration options are provided in the sections 
that follow. This section
+   gives a brief overview of what the Transaction Timeout feature can 
do.</para>
+  <section role="h3" 
xml:id="Java-Broker-Runtime-Transaction-Timeout-Effect-Broker-Side">
+   <title>Broker Logging and Connection Close</title>
+   <para>When the openWarn or idleWarn specified threshold is exceeded, the 
broker will log a WARN
+    level alert with details of the connection on which the threshold has been 
exceeded,
+    along with the age of the transaction.</para>
+   <para>When the openClose or idleClose specified threshold value is 
exceeded, the broker will
+    throw an exception back to the client connection via the <link 
xmlns:xlink="http://www.w3.org/1999/xlink"; 
xlink:href="${oracleJeeDocUrl}javax/jms/ExceptionListener.html">ExceptionListener</link>,
 log the
+    action and then close the connection.</para>
+   <para>The example broker log output shown below is where the idleWarn 
threshold specified is
+    lower than the idleClose threshold and the broker therefore logs the idle 
transaction 3 times
+    before the close threshold is triggered and the connection closed 
out.</para>
+   <screen>
+CON-1011 : Idle Transaction : 13,116 ms
+CON-1011 : Idle Transaction : 14,116 ms
+CON-1011 : Idle Transaction : 15,118 ms
+CON-1002 : Close : Idle transaction timed out
+   </screen>
+   <para>The second example broker log output shown below illustrates the same 
mechanism operating
+    on an open transaction.</para>
+   <screen>
+CON-1010 : Open Transaction : 12,406 ms
+CON-1010 : Open Transaction : 13,406 ms
+CON-1010 : Open Transaction : 14,406 ms
+CON-1002 : Close : Open transaction timed out
+   </screen>
+  </section>
+  <section role="h3" 
xml:id="Java-Broker-Runtime-Transaction-Timeout-Effect-Client-Side">
+   <title>Client Side Effect</title>
+   <para>After a Close threshold has been exceeded, the Broker will close the 
client's connection.
+    The application must reconnect itself in order to continue work.  If the
+    client is a JMS client, the application will be notified by the
+    <link xmlns:xlink="http://www.w3.org/1999/xlink"; 
xlink:href="${oracleJeeDocUrl}javax/jms/ExceptionListener.html">exception
+     listener.</link></para>
+  </section>
+ </section>
+ <section role="h2" 
xml:id="Java-Broker-Runtime-Transaction-Timeout-Configuration">
+  <title>Configuration</title>
+  <section role="h3" 
xml:id="Java-Broker-Runtime-Transaction-Timeout-Configuration-Overview">
+   <title>Configuration</title>
+   <para>The transaction timeouts can be specified when a new virtualhost is 
created or an exiting
+    virtualhost is edited.</para>
+   <para>We would recommend that only warnings are configured at first, which 
should allow broker
+    administrators to obtain an idea of the distribution of transaction 
lengths on their systems,
+    and configure production settings appropriately for both warning and 
closure. Ideally
+    establishing thresholds should be achieved in a representative UAT 
environment, with clients and
+    broker running, prior to any production deployment.</para>
+   <para>It is impossible to give suggested values, due to the large variation 
in usage depending on
+    the applications using a broker. However, clearly transactions should not 
span the expected
+    lifetime of any client application as this would indicate a hung 
client.</para>
+   <para>When configuring warning and closure timeouts, it should be noted 
that these only apply to
+    message producers that are connected to the broker, but that a timeout 
will cause the connection
+    to be closed - this disconnecting all producers and consumers created on 
that connection.</para>
+   <para>This should not be an issue for environments using Mule or Spring, 
where connection
+    factories can be configured appropriately to manage a single 
MessageProducer object per JMS
+    Session and Connection. Clients that use the JMS API directly should be 
aware that sessions
+    managing both consumers and producers, or multiple producers, will be 
affected by a single
+    producer hanging or leaving a transaction idle or open, and closed, and 
must take appropriate
+    action to handle that scenario.</para>
+  </section>
+ </section>
+</section>


---------------------------------------------------------------------
To unsubscribe, e-mail: commits-unsubscr...@qpid.apache.org
For additional commands, e-mail: commits-h...@qpid.apache.org

Reply via email to