<?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-Disk-Space-Management-Producer-Flow-Control">
    <title>Disk quota-based flow control</title>
    <para>
        The Apache Qpid Broker for Java supports a flow control mechanism which is triggered when a configured
        disk quota is exceeded. This is supported by the BDB and Derby virtualhosts.
    </para>
    <para>
        This functionality blocks all producers on reaching the disk overflow limit. When consumers consume the
        messages, causing disk space usage to falls below the underflow limit, the producers are unblocked and continue
        working as normal.
    </para>
    <para>
        Two limits can be configured:
    </para>
    <para>
        overfull limit - the maximum space on disk (in bytes).
    </para>
    <para>
        underfull limit - when the space on disk drops below this limit, producers are allowed to resume publishing.
    </para>
    <para>
        The overfull and underful limit can be specified when a new virtualhost is created or an exiting virtualhost is
        edited. This can be done using the Store Overflow and Store Underfull settings within the virtual host creation
        and edit dialogue. If editing an existing virtualhost, the virtualhost must be restarted for the new values to
        take effect.
    </para>
    <para>
        The disk quota functionality is based on "best effort" principle. This means the broker cannot guarantee that
        the disk space limit will not be exceeded. If several concurrent transactions are started before the limit is
        reached, which collectively cause the limit to be exceeded, the broker may allow all of them to be committed.
    </para>
    <para>
        The Broker will also impose flow control if the filesystem hosting a virtualhost exceeds a <link
            linkend="Java-Broker-Management-Managing-Broker-Context-StoreFilesystemMaxUsagePercent">configured
        percentage.</link>.
    </para>
    <note>
        <para>
            The <emphasis>Producer Flow Control</emphasis> can be configured on individual queue using
            <emphasis>Producer Flow Control</emphasis> overflow policy.
            For more details, please read<xref linkend="Java-Broker-Concepts-Queue-OverflowPolicy"/>.
        </para>
    </note>
    <section role="h4">
        <title>Broker Log Messages for quota flow control</title>
        <para>
            There are two broker log messages that may occur if flow control through disk quota limits is enabled. When
            the virtual host is blocked due to exceeding of the disk quota limit the following message appears in the
            broker log
            <programlisting>
                [vh(/test)/ms(BDBMessageStore)] MST-1008 : Store overfull, flow control will be enforced
            </programlisting>
            When virtual host is unblocked after cleaning the disk space the following message appears in the broker log
            <programlisting>
                [vh(/test)/ms(BDBMessageStore)] MST-1009 : Store overfull condition cleared
            </programlisting>
        </para>
    </section>
</section>
