The goal of this document is to describe queue mechanism and related tags in RichFaces 4.x.

Overview

As JSF2 provides single queue instance which always turned on, RichFaces queue planned to be implemented just as extension on top of it with advanced features like additional options, grouping of the requests, bulk options settings and so on.

Limitations

• RichFaces queue will not handle standard JSF requests or requests from the other libraries Ajax behaviors/components.

Queue Definitions

1. RichFaces global queue could be turned on/off by setting application parameter

<context-param>
   <param-name>org.richfaces.queue.enabled</param-name>
   <param-value>true</param-value> <!-- this is default value -->
</context-param>

2. Global Queue page definition

In order to redefine global queue options one could use unnamed queue defined as viewRoot child without any name:

<a4j:queue requestDelay="" ignoreDupResponce="" onrequestqueue=""/>
<h:form>
     <a4j:command*.../>

     <a4j:command*.../>

     <h:intputText..>
          <a4j:ajax.../>
     </h:intputText>
</h:form>

So it could be defined in some common template or redefined for particular views.

3. form based queue

Definition is the same as for global queue page definition but queue should be placed as form child. Applied to all the form components.

There is no options inheritance from view to form based queue.

4. Named queue and pointing ajax components/behaviors to it: - NOT FOR A2(Ignore this block as could be changed)

<a4j:queue name="foo" requestDelay="" ignoreDupResponce="" onrequestqueue=""/>

<a4j:command*...>
     <a4j:attachQueue name="foo">
</a4j:command*>

or

<a4j:queue name="foo" requestDelay="" ignoreDupResponce="" onrequestqueue=""/>

<a4j:attachQueue name="foo">
     <a4j:command*.../>

     <a4j:command*.../>

     <h:intputText..>
          <a4j:ajax.../>
     </h:intputText>
</a4j:attachQueue>
 

a4j:queue current usage

Currently a4j:queue could be used only to define some common attributes (which could be redefined then using attachement tags). Usage of a few queues (view and form one) does not mean two queues used. Just all requests from the form with queue defined will grab that queue options and the other ones - will use options from view queue.

So all requests actually placed to single queue where them grouped, waits delays, queue event handlers invoked for them and so on. Then them fired through JSF queue.

Attaching to Queue

Common usage rules for a4j:attachQueue tag:

Definitions

• attachQueue should be defined as nested component for submitting component/behavior.
  • not works for standard h:command*(without ajax) at least for now.
  • all the ajax request options defined at a4j:attachQueue will replace ones defined at a4j:queue

Pointing to queue

• If name defined - it's point the requests to named queue overriding the parameters with defined in that queue. - IGNORE named queues is FUTURE
• If name not defined - points the requests to global queue just overriding the same parameters.
• if placed in form and form queue exist should point request to global queue grabbing form queue options and override with parameters defined at attach.

Example

//In this variant we can only nest attachQueue in submitting behaviors/components. Wrapping not supported 
//1) reference tag inside submitting behavior/component
<h:form>
     <h:inputText>
          <a4j:support>
               <a4j:attachQueue ...options... />
          </a4j:support>
     </h:inputText>
     <h:inputText>
          <a4j:support>
               <a4j:attachQueue ...options... />
          </a4j:support>
     </h:inputText>
     <a4j:commandButton/>
          <a4j:attachQueue ...options... />
     </a4j:commandButton>
</h:form>
//2) reference tag inside submitting behavior which 
//applied by wrapping target components
<h:form>
     <a4j:support>
          <h:inputText />
          <h:inputText />
          <a4j:attachQueue ...options... />
     </a4j:support>
</h:form>
 
//3) Complex case with nested submitting behaviors
<h:form>
     <a4j:support event="click">
          <a4j:attachQueue /> //(1)  
          <h:inputText />
          <a4j:commandButton /> "click" support applied there so (1) used
          
          <a4j:support event="valueChange">
               <a4j:attachQueue /> //(2)
               <h:inputText /> (2) used when "valueChange" occurs and (1) on click 
               <a4j:commandButton /> "click" support applied there so also (1) used
          </a4j:support>
     </a4j:support>
</h:form>
 
//POST A2 Future
<a4j:queue name="viewqueue" ...options... />
     
<h:form>
     <a4j:queue name="formqueue" ...options... />
     <h:inputText>
          <a4j:support>
          <a4j:attachQueue name="queue" />
          </a4j:support>
     </h:inputText>
     
     <h:inputText>
          <a4j:support>
          <a4j:attachQueue ...options... /> //Still refer to global
          </a4j:support>
     </h:inputText>
</h:form>
 
<h:form>
<a4j:support>
     <a4j:attachQueue name="viewqueue" />
     <h:inputText />
     <h:inputText />
</a4j:support>
</h:form>

Queue Parameters

Queue provides next set of parameters for ajax requests:

• ignoreDupResponse
• requestDelay
• timeout (JSF should add support for that)
• Open quesiton: will we support size attribute? - Definitely not in A2
• sizeExceedStrategy?
  
  

event handlers:

• onrequestqueue
• onrequestdequeue
• oncomplete
• onbegin
• onsuccess
• onerror
• onsizeexceed?