<?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>Here is the simplest way for a component creation on a page.</para>
        <para>
            <emphasis role="bold">Example:</emphasis>
        </para>
        <programlisting role="XML"><![CDATA[<h:form>
       <a4j:queue name="fooQueue" ... />
</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 a user can create several types of queues associated with it.</para>
        <itemizedlist>
            <listitem>
                <para>
                    A user 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 see the following examples:
                </para>
                <programlisting role="XML"><![CDATA[<a4j:queue name="org.richfaces.global_queue" disabled="false"... />]]></programlisting>
                <para>
                    or:
                </para>
                <programlisting role="XML"><![CDATA[<a4j:queue name="org.richfaces.global_queue" disabled="true"... />]]></programlisting>
            </listitem>
            <listitem>
                <para>
                    A user can create a separate queue for 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 will be the global queue only for this form.
                </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 <a4j:queue name="fooQueue" ... /> 
    ...
</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="fooQueue" ...>
   ...
   </a4j:form>]]></programlisting>
            </listitem>
            <listitem>
                <para>With the help of the <emphasis><property>&quot;eventsQueue&quot;</property></emphasis> attribute a user 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="fooQueue" ... />
...
<h:inputText value="#{foo2.bar1}">
    <a:support id="onblur" event="onblur" reRender="bar21" eventsQueue="fooQueue"/>
</h:inputText>

<a4j:commandButton eventsQueue="fooQueue" ... >]]></programlisting>
                <para>
                    As a result all requests generated through the onblur 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;fooQueue&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 - this strategy is default. It drops next request that should be fired</para>
            </listitem>
            <listitem>
                <para>dropNew - it drops the incoming request</para>
            </listitem>
            <listitem>
                <para>fireNext - with the help of this strategy you can immediately fire the next request in line to be fired</para>
            </listitem>
            <listitem>
                <para>fireNew - This type of the strategy immediately fires the incoming request.</para>
            </listitem>
        </itemizedlist>
        <para>
            The <emphasis><property>&quot;requestDelay&quot;</property></emphasis> attribute defines time delay 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 which were fired using this queue will have 2 sec delay.
        </para>
        <para>
            The requests collect in the queue, combining similar ones, during request delay. 
            User should remember 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>