<?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 the Component with a Page Tag</title>
          <para>
                To create the simplest variant of the Form Based queue use the following syntax.
          </para>
          <para>
                <emphasis role="bold">Example:</emphasis>
          </para>
          <programlisting role="XML"><![CDATA[<h:form id="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>Details of usage</title>
            
            <para>
                  The RichFaces Queue has four different types: global default, view scoped default, view scoped named and form-based default queue (general Queue principles are good documented in the &quot;<link linkend="QueuePrinciples">Queue Principles</link>&quot; section). 
                  The current section will take closer to the form based queue. The usage of other types is similar.
            </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 requests that can be stored in the queue at a time. 
                  The attribute helps to prevent server overloading. 
                  It is also possible to determine queue&apos;s behaviour when it&apos;s size is exceeded. 
                  Use the <emphasis><property>&quot;sizeExceededBehavior&quot;</property></emphasis> for this purpose. 
                  There are four possible strategies of exceeded queue&apos;s behavior: 
            </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. 
              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>
              Vizit the <ulink url="http://livedemo.exadel.com/richfaces-demo/richfaces/queue.jsf?c=queue">Queue Page</ulink> at the RichFaces LiveDemo for examples of component usage and their sources. 
        </para>
        
        <para>
              Useful articles:
        </para>
          <para>&quot;<link linkend="QueuePrinciples">Queue Principles</link>&quot; section of the RichFaces developer guide describes general Queue principles.</para>
    </section>
</chapter>
