a4j:queue in 4.x

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?
Note:  ignoreDupResponse, timeout and requestDelay - moved to queue options. That means them should be defined either at queue or at attachQueue only.

Notes and exceptions for queuing options

requestDelay defined at queue - ignored by push and poll component as periodical ajax request or requests initiated from server side should not wait for "similar" ones.

Queue functionality

Next sections from http://community.jboss.org/wiki/DesignofRichFacesa4jqueue still valid for 4.x queue mechanism:
  • Events similarity
  • Similar request during request delay


Request generation

     As opposite to 3.3.x queue we will collect just events in the queue, and generate the request(serialize form values) before actuall sending. This will fix the synchronization problems like with some added/changed or removed by previous ajax request inputs from form. And  in this way the information sent with request will be more actuall in difference with former approach.

 

E.g. in the past form was serialized on putting request to queue. So if previous request added/removed some inputs in form - new request will be sent with not valid form info. And now the form will be serialized before sending so previous request changes will be also there.

 

JSF queuing extensions implementation points

http://community.jboss.org/wiki/JSFAjaxpointsfordiscussionwithEG

 

https://javaserverfaces-spec-public.dev.java.net/issues/show_bug.cgi?id=682 - timout support.

https://javaserverfaces-spec-public.dev.java.net/issues/show_bug.cgi?id=689 - queues count in JSF queue

https://javaserverfaces-spec-public.dev.java.net/issues/show_bug.cgi?id=726 - queue size

https://javaserverfaces-spec-public.dev.java.net/issues/show_bug.cgi?id=727 - requestDelay

 

JS API

queue should provide next js api:

  • <queueObject>.getSize
  • <queueObject>.getMaximumSize?
  • <queueObject>.getEvents(name) - name is optional. if not exist - all would be returned. if name defined - only events which belongs to named queue will be returned
  • <queueObject>.getEvent(name, i) - name could have some value which will means "all" in order not to create two function WDYT?
  • <queueObject>.removeEvent(name, i) - ^
  • <queueObject>.clear()
  • <queueObject>.isEmpty()
  • <queueObject>.push() - similar to jsf.ajax.request(...)
  • <queueObject>.submitFirst()