<?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>
            This is how you can create a form based queue. All other types of the queue are described in the &quot;<link linkend="QueuePrinciples">Queue Principles</link>&quot; section.
        </para>
        <para>
            <emphasis role="bold">Example:</emphasis>
        </para>
        <programlisting role="XML"><![CDATA[<h:form>
	<a4j:queue />
	<h:inputText value="#{bean.a}">
		<a4j:support event="onkeyup" />
	</h:inputText>
</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>As it was said earlier the queue implemented in Richfaces has 4 types.
       In this section we will take a closer look at the form based queue. All other types of queue are similar is usage(except for the  &quot;global queue&quot;) but different is their scope.</para>
        
      
        <para>In order to disable or enable the <emphasis role="bold"><property
                    >&lt;a4j:queue&gt;</property></emphasis> component on the page you can use the
                    <emphasis><property>&quot;disabled&quot;</property></emphasis> attribute.</para>
       
        <para> The <emphasis><property>&quot;requestDelay&quot;</property></emphasis> attribute
            defines delay time for all the requests fired by the action components. </para>
        <para>
            
            The <emphasis><property>&quot;size&quot;</property></emphasis> attribute specifies the number of request that can be stored in the queue at a time. 
      The attribute can help you prevent overloading of a sever with requests. You can also determine the type of behaviour when the size of the queue is exceeded.
             </para>
        <para>You should use the <emphasis><property>&quot;sizeExceededBehavior&quot;</property></emphasis> for the purpose.</para>
        <para> The <emphasis><property>&quot;sizeExceededBehavior&quot;</property></emphasis>
            attribute can set 4 the strategies of the queue&apos;s behavior if the number of the
            requests waiting in the queue is exceeded: </para>
        <itemizedlist>
            <listitem>
                <para>&quot;dropNext&quot;  drops next request that should be fired</para>
            </listitem>
            <listitem>
                <para>&quot;dropNew&quot;   drops the incoming request</para>
            </listitem>
            <listitem>
                <para>&quot;fireNext&quot;   immediately fires the next request in line to be fired</para>
            </listitem>
            <listitem>
                <para>&quot;fireNew&quot;   immediately fires the incoming request.</para>
            </listitem>
        </itemizedlist>    
        <para>
            <emphasis role="bold"> Example: </emphasis>
        </para>
        <programlisting role="XML"><![CDATA[...
<h:form>
	<a4j:queue size="2" requestDelay="500" sizeExceededBehavior="dropNext" onsizeexceeded="alert('The size of the queue is exceeded')" />
	<h:inputText value="#{bean.a}">
		<a4j:support event="onkeyup" />
	</h:inputText>
	<h:inputText value="#{bean.b}">
		<a4j:support event="onblur" />
	</h:inputText>
	<h:selectBooleanCheckbox value="#{bean.check}" id="checkboxID">
		<a4j:support id="checkboxSupport" event="onchange" />
	</h:selectBooleanCheckbox>
</h:form>
...]]></programlisting>
        <para>
            In this example if the queue has more than 2 requests waiting to be processed the next event will be dropped and a message (the  <emphasis><property>&quot;onsizeexceeded&quot;</property></emphasis> attribute fires a JavaScript function ) saying that the queues is exceeded will be displayed.
        </para>
        
        <para>
            The <emphasis><property>&quot;ignoreDupResponses&quot;</property></emphasis> attribute that takes a boolean value can also help optimize your Ajax requests. 
            If set to true, response processing for request will not occur if a similar request is already waiting in the queue. New request will be fired immediately when the response from the previous one returns.
         
        </para>
        
        <para>
            <emphasis role="bold"> Example: </emphasis>
        </para>
        <programlisting role="XML"><![CDATA[...
<h:form>
	<a4j:queue requestDelay="500" ignoreDupResponses="true" />
	<h:inputText value="#{bean.a}">
		<a4j:support event="onkeyup" />
	</h:inputText>
</h:form>
...]]></programlisting>
        
        <para>In this example, the requests are glued together and only the last one is submitted.</para>
        
        <para>Another key attribute that easies server load is <emphasis><property
            >&quot;timeout&quot;</property></emphasis>.
            The attribute specifies the  amount of time an item can be in the queue before the sent event is be aborted and dropped from the queue.
          </para> 
        <para>If the request is sent and response is not returned within the
            time frame defined in this attribute - the request is aborted, and the next one is sent.
        </para>
          <para>
                <emphasis role="bold"> Example: </emphasis>
          </para>            
        <programlisting role="XML"><![CDATA[...
<h:form>
	<a4j:queue timeout="1000" />
	<h:inputText value="#{bean.a}" >
		<a4j:support event="onkeyup" />
	</h:inputText>
</h:form>
...]]></programlisting>
        
        <para>
            In this case if the sever doesn&apos;t respond within a second the request will be aborted.
        </para>
     
        <para>
            As you can see the implementation of the queue provides some custom event handlers that you may use to call JavaScript functions.</para>
        <para>
            The <emphasis><property>&quot;oncomplete&quot;</property></emphasis>is fired after request completed.
        </para>
        <para>
            In this event handler request object is be passed as a parameter. 
            Thus queue is be accessible using <code>request.queue</code>. 
            And the element which was a source of the request is available using <code>this</code>.
                        
        </para>
        <para>
            <emphasis role="bold"> Example: </emphasis>
        </para>
        <programlisting role="XML"><![CDATA[...
<h:form  >
	<a4j:queue oncomplete="alert(request.queue.getSize())" requestDelay="1000" />
	<h:inputText value="#{bean.a}">
		<a4j:support event="onkeyup" />
	</h:inputText>
	<h:selectBooleanCheckbox value="#{bean.check}">
		<a4j:support event="onchange"/>
	</h:selectBooleanCheckbox>
</h:form>
...]]></programlisting>
        
        <para>In this example you can see how the number of requests waiting  in the queue change. You will get a message with the number of the requests in the queue.</para>
        
        <para>The <emphasis><property>&quot;onbeforedomupdate&quot;</property></emphasis> event handler called before
        updating DOM on a client side.</para>
        
        <para> The <emphasis><property>&quot;onrequestqueue&quot;</property></emphasis> event handler called after the new request has been added to queue.
            And the <emphasis><property>&quot;onrequestdequeue&quot;</property></emphasis> event handler called after the request has been removed from queue. </para>
        <para> The <emphasis><property>&quot;onsubmit&quot;</property></emphasis> event handler called
            after request is completed. This attribute allows to invoke JavaScript code before an
            Ajax request is sent. </para>

    </section>
    
    <section>
        <title>JavaScript API</title>
        <table> 
            <title>JavaScript API</title>
            <tgroup cols="2">
                <thead>
                    <row>
                        <entry>Function</entry>
                        <entry>Description</entry>
                    </row>
                </thead>
                <tbody>
                    <!--Sorting API -->
                    <row>
                        <entry>getSize()</entry>
                        <entry>Returns the current size to the queue</entry>
                        
                    </row>
                    <row>
                        <entry>getMaximumSize()</entry>
                        <entry>Returns the maximum size to the queue, specified in the &quot;size&quot; attribute</entry>
                    </row>
                </tbody>
            </tgroup>
        </table>
    </section>
    <section>
        <title>Relevant resources links</title>
        <para>
            <ulink url="http://livedemo.exadel.com/richfaces-demo/richfaces/queue.jsf?c=queue"
                >On the component LiveDemo page</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>
        <para>General queue principals are documented in the &quot;<link linkend="QueuePrinciples">Queue Principles</link>&quot; section.</para>
    </section>
</chapter>
