QPID-6481: Move java broker docbook into java source tree

git-svn-id: https://svn.apache.org/repos/asf/qpid/trunk@1673703 13f79535-47bb-0310-9956-ffa450edef68

1 files changed, 0 insertions, 137 deletions

diff --git a/qpid/doc/book/src/java-broker/Java-Broker-Runtime-Producer-Transaction-Timeout.xml b/qpid/doc/book/src/java-broker/Java-Broker-Runtime-Producer-Transaction-Timeout.xml
deleted file mode 100644
index 2813274c61..0000000000
--- a/qpid/doc/book/src/java-broker/Java-Broker-Runtime-Producer-Transaction-Timeout.xml
+++ /dev/null
@@ -1,137 +0,0 @@
-<?xml version="1.0" encoding="utf-8"?>
-<!DOCTYPE entities [
-<!ENTITY %  entities SYSTEM  "commonEntities.xml">
-%entities;
-]>
-<!--
-
- 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 id="Java-Broker-Runtime-Producer-Transaction-Timeout">
- <title>Producer Transaction Timeout</title>
- <section role="h2" 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 <ulink
-    url="&oracleJeeDocUrl;javax/jms/Session.html#commit">Session#commit()</ulink>.</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" 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" id="Java-Broker-Runtime-Producer-Transaction-Timeout-Scope">
-  <title>Scope</title>
-  <para>Note that only <ulink url="&oracleJeeDocUrl;javax/jms/MessageProducer.html"
-    >MessageProducer</ulink> 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" 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" 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 <ulink
-     url="&oracleJeeDocUrl;javax/jms/ExceptionListener.html">ExceptionListener</ulink>, 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><![CDATA[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><![CDATA[
-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" 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 <ulink url="&oracleJeeDocUrl;javax/jms/ExceptionListener.html">exception
-    listener</ulink>, 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><![CDATA[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" id="Java-Broker-Runtime-Producer-Transaction-Timeout-Configuration">
-  <title>Configuration</title>
-  <section role="h3" 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>