<?xml version="1.0" encoding="UTF-8"?>
<chapter>
    <chapterinfo>
        <keywordset>
            <keyword>a4j:queue</keyword>
        </keywordset>
    </chapterinfo>
    <table>
        <title>Component identification parameters </title>
        <tgroup cols="2">
            <thead>
                <row>
                    <entry>Name</entry>
                    <entry>Value</entry>
                </row>
            </thead>
            <tbody>
                <row>
                    <entry>component-family</entry>
                    <entry>org.ajax4jsf.Queue</entry>
                </row>
                <row>
                    <entry>component-class</entry>
                    <entry>org.ajax4jsf.component.html.HtmlQueue</entry>
                </row>
                <row>
                    <entry>renderer-type</entry>
                    <entry>org.ajax4jsf.QueueRenderer</entry>
                </row>
                <row>
                    <entry>tag-class</entry>
                    <entry>org.ajax4jsf.taglib.html.jsp.QueueTag</entry>
                </row>
            </tbody>
        </tgroup>
    </table>
    
    <section>
        <title>Creating on a page</title>
        <para>In order to create the named queue, see following example.</para>
        <para>
            <emphasis role="bold">Example:</emphasis>
        </para>
        <programlisting role="XML"><![CDATA[<a4j:queue name="myQueue" ... />
...
<h:inputText value="#{myQueue.text}">
    <a:support id="onblur" event="onblur" eventsQueue="myQueue"/>
</h:inputText>
...
<a4j:commandButton eventsQueue="myQueue" ... >]]></programlisting>
        <para>You can also create the queue with a default name. This queue is global for the all form. See the example below.</para>
        <para>
            <emphasis role="bold">Example:</emphasis>
        </para>
        <programlisting role="XML"><![CDATA[<h:form>
            ...
       <a4j:queue/>
       ...
</h:form>
]]></programlisting>
    </section>
    <section>
        <title>Creating the Component Dynamically Using Java</title>
        <para>
            <emphasis role="bold">
                Example:
            </emphasis>
        </para>
        <programlisting role="JAVA"><![CDATA[import org.ajax4jsf.component.html.HtmlQueue;            
...
HtmlQueue myQueue = new HtmlQueue();
]]></programlisting>     
    </section>
    
    <section>
        <title>Key attributes and ways of usage</title>
        <para>By means of the <emphasis role="bold"><property>&lt;a4j:queue&gt;</property></emphasis> component you can create several types of queues associated with it.</para>
        <itemizedlist>
            <listitem>
                <para>
                    In order to create global queue for the all Can set a queue globally in &quot;web.xml&quot;. You don&apos;t need set the queue on the page itself. The global queue can be used by all components. You can see the example below:
                </para>
                <programlisting role="XML"><![CDATA[<context-param>
   <param-name>org.richfaces.queue.global.enabled</param-name>
   <param-value>true</param-value>
   </context-param>]]></programlisting>
                <para>
                    In order to enable/disable a global queue for concrete views see the following examples:
                </para>
                <programlisting role="XML"><![CDATA[<a4j:queue name="org.richfaces.global_queue" disabled="false"... />]]></programlisting>
                <para>
                    In order to disable the queue the<emphasis><property>&quot;disabled&quot;</property></emphasis> attribute should be &quot;true&quot;.
                </para>
            </listitem>
            <listitem>
                <para>
                    You can create a separate queue for a specific form with the help of the <emphasis role="bold"><property>&lt;a4j:form&gt;</property></emphasis> or <emphasis role="bold"><property>&lt;h:form&gt;</property></emphasis> tags. 
                    It is the queue only for this form. The queue&apos;s name don&apos;t define by default if you haven&apos;t defined it.
                </para>
                <para>
                    <emphasis role="bold">
                        Example:
                    </emphasis>
                </para>
                <programlisting role="XML"><![CDATA[<h:form ... >
    ...
    <a4j:queue ... /> 
    ...
    </h:form>]]></programlisting>
                <para>
                    or:
                </para>
                <para>
                    <emphasis role="bold">
                        Example:
                    </emphasis>
                </para>
                <programlisting role="XML"><![CDATA[<a4j:form ... >
    ...
    <a4j:queue name="myQueue" ... /> 
    ...
</a4j:form>]]></programlisting>
                <para>If you use the <emphasis role="bold"><property>&lt;a4j:form&gt;</property></emphasis> tag, you can reference a named queue as the form&apos;s default.</para>
                <para>
                    <emphasis role="bold">
                        Example:
                    </emphasis>
                </para>
                <programlisting role="XML"><![CDATA[<a4j:form eventsQueue="myQueue" ...>
   ...
   </a4j:form>]]></programlisting>
            </listitem>
            <listitem>
                <para>With the help of the <emphasis><property>&quot;eventsQueue&quot;</property></emphasis> attribute you can reference a named queue from any <emphasis role="bold"><property>a4j</property></emphasis> or <emphasis role="bold"><property>rich</property></emphasis> component that supports this attribute.</para>
                <para>
                    <emphasis role="bold">
                        Example:
                    </emphasis>
                </para>
                <programlisting role="XML"><![CDATA[<a4j:queue name="myQueue" ... />
...
<h:inputText value="#{queueBean.text}">
    <a4j:support id="onblur" event="onblur" eventsQueue="myQueue"/>
</h:inputText>

<a4j:commandButton eventsQueue="myQueue" ... >]]></programlisting>
                <para>
                    As a result all requests generated after the &quot;onblur&quot; event of the <emphasis role="bold"><property>&lt;h:inputText&gt;</property></emphasis> component, and clicking of the <emphasis role="bold"><property>&lt;h:commandButton&gt;</property></emphasis> will be funneled through the <code>&quot;myQueue&quot;</code>.
                </para>
                <para>
                    If you try to refer to the nonexistent queue the new named queue will be created with all default settings.
                </para>
            </listitem>
        </itemizedlist>
        <para>
            The <emphasis><property>&quot;size&quot;</property></emphasis> attribute helps you to set the number of requests allowed in the queue at one time.
        </para>
        <para>
            The <emphasis><property>&quot;sizeExceededBehavior&quot;</property></emphasis> attribute defines four strategies of the queue&apos;s behavior if the number of the requests waiting in the queue is exceeded:
        </para>
        <itemizedlist>
            <listitem>
                <para>dropNext - drops next request that should be fired</para>
            </listitem>
            <listitem>
                <para>dropNew - drops the incoming request</para>
            </listitem>
            <listitem>
                <para>fireNext - immediately fires the next request in line to be fired</para>
            </listitem>
            <listitem>
                <para>fireNew - immediately fires the incoming request.</para>
            </listitem>
        </itemizedlist>
        <para>
            The <emphasis><property>&quot;requestDelay&quot;</property></emphasis> attribute defines delay time for all the requests which fired using this queue.
        </para>
        <para>
            <emphasis role="bold">
                Example:
            </emphasis>
        </para>
        <programlisting role="XML"><![CDATA[<a4j:queue requestDelay="2000" ... />]]></programlisting>
        <para>
            As a result all the requests are fired with to 2 sec delay.
        </para>
        <para>
            The requests collected in the queue, combining similar ones, during request delay. 
            Note, that such requests can combine, if they are raised sequentially, in order to not block the queue and not to change the requests order.
        </para>
    </section>
    
    <section>
        <title>Relevant resources links</title>
        <para>
            <ulink
                url="http://livedemo.exadel.com/richfaces-demo/richfaces/queue.jsf?c=queue"
                >Here</ulink> you can see the example of <emphasis
                    role="bold">
                    <property>&lt;a4j:queue&gt;</property>
                </emphasis> usage and sources for the given example. </para>
    </section>
</chapter>