### Create new RichFaces Documentation Jira issue

Summary
255 characters left
Description
Environment
This will launch the RichFaces Jira page - to complete your feedback please login if needed, and submit the Jira.

JBoss.org Community Documentation

- Prev
- Next

### 6.1.11. < a4j:queue > available since 3.3.0

expand all

#### 6.1.11.1. Description

The <a4j:queue> component enqueues set of Ajax requests sent from client. The RichFaces components with built-in Ajax can reference the queue to optimize Ajax requests.

Table 6.20. a4j : queue attributes

Attribute Name | Description
--- | ---
binding | JSF: The attribute takes a value-binding expression for a component property of a backing bean
disabled | HTML: If "true", disables this component on page.
id | JSF: Every component may have a unique id that is automatically created if omitted
ignoreDupResponses | Attribute allows you to ignore an Ajax response produced by a request if the newest 'similar' request is in the queue already. ignoreDupResponses="true" does not cancel the request while it is processed on the server, but just allows avoiding unnecessary updates on the client side if the response isn't actual now
name | Specifies to name for the named queue.
onbeforedomupdate | The client-side script method to be called before DOM is updated
oncomplete | The client-side script method to be called after the request is completed
onerror | The client-side script method to be called whenever a JavaScript error occurs
onrequestdequeue | The client-side script method to be called after the request is removed from the queue
onrequestqueue | The client-side script method to be called when the request is added to the queue
onsizeexceeded | The client-side script method to be called when a size is exceeded
onsubmit | DHTML: The client-side script method to be called before an ajax request is submitted
requestDelay | Attribute defines the time (in ms) the request will be waiting in the queue before it is ready to be sent.
size | HTML: Defines the number of requests allowed in the queue at one time.
sizeExceededBehavior | Defines the strategies of the queue's behavior if the number of the requests waiting in the queue is exceeded. There are four strategies: dropNext (by default), dropNew, fireNext , fireNew.
status | ID (in format of call UIComponent.findComponent()) of Request status component
timeout | Waiting time for response on a particular request. If no response is received during this time, the request is aborted

Table 6.21. Component identification parameters

Name | Value
--- | ---
component-family | org.ajax4jsf.Queue
component-class | org.ajax4jsf.component.html.HtmlQueue
renderer-type | org.ajax4jsf.QueueRenderer
tag-class | org.ajax4jsf.taglib.html.jsp.QueueTag

#### 6.1.11.2. Creating the Component with a Page Tag

To create the simplest variant of the Form Based queue use the following syntax.

Example:

    <h:form id="form">

          <a4j:queue />

          <h:inputText value="#{bean.a}">

                <a4j:support event="onkeyup" />

          </h:inputText>

    </h:form>

#### 6.1.11.3. Creating the Component Dynamically Using Java

Example:

    import org.ajax4jsf.component.html.HtmlQueue;

    ...

    HtmlQueue myQueue = new HtmlQueue();

#### 6.1.11.4. Details of usage

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 "Queue Principles" section). The current section will take closer to the form based queue. The usage of other types is similar.

In order to disable or enable the <a4j:queue> component on the page you can use the "disabled" attribute.

The "requestDelay" attribute defines delay time for all the requests fired by the action components.

The "size" 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's behaviour when it's size is exceeded. Use the "sizeExceededBehavior" for this purpose. There are four possible strategies of exceeded queue's behavior:

- "dropNext" drops next request that should be fired

- "dropNew" drops the incoming request

- "fireNext" immediately fires the next request in line to be fired

- "fireNew" immediately fires the incoming request.

Example:

    <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>

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 "onsizeexceeded" attribute fires a JavaScript function) saying that the queues is exceeded will be displayed.

The "ignoreDupResponses" 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.

Example:

    <h:form>

          <a4j:queue requestDelay="500" ignoreDupResponses="true" />

          <h:inputText value="#{bean.a}">

                <a4j:support event="onkeyup" />

          </h:inputText>

    </h:form>

In this example, the requests are glued together and only the last one is submitted.

Another key attribute that easies server load is "timeout" . 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.

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.

Example:

    <h:form>

          <a4j:queue timeout="1000" />

          <h:inputText value="#{bean.a}">

                <a4j:support event="onkeyup" />

          </h:inputText>

    </h:form>

In this case if the sever doesn't respond within a second the request will be aborted.

As you can see the implementation of the queue provides some custom event handlers that you may use to call JavaScript functions.

The "oncomplete" is fired after request completed. In this event handler request object is be passed as a parameter. Thus queue is be accessible using `request.queue`. And the element which was a source of the request is available using `this`.

Example:

    <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>

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.

The "onbeforedomupdate" event handler called before updating DOM on a client side.

The "onrequestqueue" event handler called after the new request has been added to queue. And the "onrequestdequeue" event handler called after the request has been removed from queue.

The "onsubmit" event handler called after request is completed. This attribute allows to invoke JavaScript code before an Ajax request is sent.

#### 6.1.11.5. JavaScript API

Table 6.22. JavaScript API

Function | Description
--- | ---
getSize() | Returns the current size to the queue
getMaximumSize() | Returns the maximum size to the queue, specified in the "size" attribute

#### 6.1.11.6. Relevant resources links

Vizit the Queue Page at the RichFaces LiveDemo for examples of component usage and their sources.

Useful articles:

"Queue Principles" section of the RichFaces developer guide describes general Queue principles.

- Prev6.1.10. < a4j:push > ...
- Top of page
- Front page
- Next6.1.12. < a4j:status > ...