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

-->

<appendix xmlns="http://docbook.org/ns/docbook" version="5.0" xml:id="JMS-Client-0-8-Appendix-ProducerFlowControl-Impact">
    <title>Impact of Broker enforced Producer Flow Control on Client</title>
    <para>
        Producing sessions can be blocked by the Qpid Broker when <emphasis>Producer Flow Control</emphasis> is enforced
        either on
        <link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="${qpidJavaBrokerBook}Java-Broker-Runtime-Disk-Space-Management.html#Java-Broker-Runtime-Disk-Space-Management-Producer-Flow-Control">exceeding of disk quota</link>
        or breaching of queue capacity when
        <link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="${qpidJavaBrokerBook}Java-Broker-Concepts-Queues.html#Java-Broker-Concepts-Queue-OverflowPolicy">Producer Flow Control Overflow Policy</link>
        is configured on queue.
    </para>
    <para>
        If a producer sends to a queue which is overfull, the broker will respond by
        instructing the client not to send any more messages. The impact of this is
        that any future attempts to send will block until the broker rescinds the flow control order.
    </para>
    <para>
        While blocking the client will periodically log the fact that it is blocked waiting on flow control.
    </para>
    <programlisting>
        WARN   Message send delayed by 5s due to broker enforced flow control
        WARN   Message send delayed by 10s due to broker enforced flow control
    </programlisting>
    <para>
        After a set period the send will timeout and throw a JMSException to the calling code.
    </para>
    <para>
        If such a JMSException is thrown, the message will not be sent to the broker,
        however the underlying Session may still be active - in particular if the
        Session is transactional then the current transaction will not be automatically
        rolled back. Users may choose to either attempt to resend the message, or to
        roll back any transactional work and close the Session.
    </para>
    <para>
        Both the timeout delay and the periodicity of the warning messages can be set
        using Java system properties.
    </para>
    <para>
        The amount of time (in milliseconds) to wait before timing out
        is controlled by the property qpid.flow_control_wait_failure.
    </para>
    <para>
        The frequency at which the log message informing that the producer is flow
        controlled is sent is controlled by the system property qpid.flow_control_wait_notify_period.
    </para>
    <para>
        Adding the following to the command line to start the client would result in a timeout of one minute,
        with warning messages every ten seconds:
    </para>
    <programlisting>
        -Dqpid.flow_control_wait_failure=60000
        -Dqpid.flow_control_wait_notify_period=10000
    </programlisting>
</appendix>