1 files changed, 52 insertions, 0 deletions
diff --git a/qpid/doc/book/src/java-broker/Java-Broker-Runtime-Message-Compression.xml b/qpid/doc/book/src/java-broker/Java-Broker-Runtime-Message-Compression.xml
new file mode 100644
index 0000000000..f4d42b051d
--- /dev/null
+++ b/qpid/doc/book/src/java-broker/Java-Broker-Runtime-Message-Compression.xml
@@ -0,0 +1,52 @@
+<?xml version="1.0" encoding="utf-8"?>
+<!--
+
+ 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-Message-Compression">
+ <title>Message Compression</title>
+ <para>The Java Broker supports message compression. This feature works in co-operation with
+  Qpid Clients implementing the same feature.</para>
+ <para>Once the feature is enabled (using Broker context variable
+   <emphasis>broker.messageCompressionEnabled</emphasis>), the Broker will advertise support for the
+  message compression feature to the client at connection time. This allows clients to opt to turn
+  on message compression, allowing message payload sizes to be reduced.</para>
+ <para>If the Broker has connections from client who have message compression enabled and other who
+  do not, it will internally, on-tyhe-fly, decompress compressed messages when sending to clients
+  without support and conversely, compress uncomressed messages when sending to clients who support
+  it.</para>
+ <para>The Broker has a threshold below which it will not consider compressing a message, this is
+  controlled by Broker content variable
+   (<literal>connection.messageCompressionThresholdSize</literal>).</para>
+ <para>This feature <emphasis>may</emphasis> have a beneficial effect on performance by:</para>
+ <itemizedlist>
+  <listitem>
+   <para>Reducing the number of bytes transmitted over the wire, both between Client and Broker, and
+    in the HA case, Broker to Broker, for replication purposes.</para>
+  </listitem>
+  <listitem>
+   <para>Reducing storage space when data is at rest within the Broker,  both on disk and in memory.</para>
+  </listitem>
+ </itemizedlist>
+ <para>Of course, compression and decompression is computationally expensive. Turning on the feature
+  may have a negative impact on CPU utilization on Broker and/or Client. Also for small messages
+  payloads, message compression may increase the message size. It is recommended to test the feature
+  with representative data.</para>
+</section>