<?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>There is possibility of the creation as a named queue so and a queue with the default name. 
            You can reference the named queue only from such components which have <emphasis><property>&quot;eventsQueue&quot;</property></emphasis> attribute.</para>
        <para>So, the following example helps to create the named queue.</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>
...>]]></programlisting>
        <para>See the example of the creation the default queue 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>It&apos;s possible by means of the <emphasis role="bold"><property>&lt;a4j:queue&gt;</property></emphasis> component to create the several types of the queues.</para>
        <itemizedlist>
            <listitem>
                <para>
                    So that to create a global queue you should add the following code into your &quot;web.xml&quot; file. In this instance the queue can be used for the all pages and all components of these pages.
                </para>
                <para>
                    You can define only one global queue.
                </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>
                    By default the global queue is disabled. In order to enable or disable the queue the value of the &quot;<code>org.richfaces.global_queue</code>&quot; parameter should be &quot;true&quot; or &quot;false&quot; accordingly. 
                </para>
                <programlisting role="XML"><![CDATA[<a4j:queue name="org.richfaces.global_queue" disabled="false"... />]]></programlisting>
            </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>