<?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>
  <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>