JBoss.orgCommunity Documentation

Chapter 3. Actions

3.1. <a4j:ajax>
3.1.1. Basic usage
3.1.2. Reference data
3.2. <a4j:param>
3.2.1. Basic usage
3.2.2. Interoperability
3.2.3. Passing client-side parameters
3.2.4. Reference data
3.3. <a4j:actionListener>
3.4. <a4j:commandButton>
3.4.1. Basic usage
3.4.2. Reference data
3.5. <a4j:commandLink>
3.5.1. Basic usage
3.5.2. Reference data
3.6. <a4j:jsFunction>
3.6.1. Basic usage
3.6.2. Parameters and JavaScript
3.6.3. Reference data
3.7. <a4j:poll>
3.7.1. Timing options
3.7.2. Reference data
3.8. <a4j:push>
3.8.1. Setting up Push
3.8.2. Server-side Push methods
3.8.3. Client-side Push methods
3.8.4. Push Topics
3.8.5. Handling a push message
3.8.6. Handling a push subscription
3.8.7. Using TopicsContext to publish message
3.8.8. Integrating Push with CDI events
3.8.9. Push and JMS integration
3.8.10. Reference data

This chapter details the basic components that respond to a user action and submit an Ajax request.

The <a4j:ajax> behavior allows Ajax capability to be added to a non-Ajax component. The non-Ajax component must implement the ClientBehaviorHolder interface for all the event attributes that support behavior rendering.

The <a4j:param> behavior combines the functionality of the JavaServer Faces ( JSF) components <f:param> and <f:actionListener>.

Use the <a4j:actionListener> tag to register an ActionListener class on a parent action component. The class provided as a listener must implement the javax.faces.event.ActionListener interface. Multiple listener methods can be registered on an action component in this way.

The <a4j:actionListener> tag differs from the standard JSF tag by allowing a listener method to be defined instead of just a class. Use the listener attribute to define the listener method.

The <a4j:commandButton> component is similar to the JavaServer Faces ( JSF) <h:commandButton> component, but additionally includes Ajax support.

The <a4j:commandButton> component executes the complete form

Button controls are typically used to perform complete form submissions for data storing. As a consequence, the <a4j:commandButton> component has the execute="@form" setting by default. To limit rendering to a different scope, redefine the execute attribute.

The <a4j:commandLink> component is similar to the JavaServer Faces ( JSF) <h:commandLink> component, except that it includes plugged-in Ajax behavior.

The <a4j:commandLink> component executes the complete form

Link controls are typically used to perform complete form submissions for data storing. As a consequence, the <a4j:commandLink> component has the execute="@form" setting by default. To limit rendering to a different scope, redefine the execute attribute.

The <a4j:jsFunction> component performs Ajax requests directly from JavaScript code and retrieves server-side data. The server-side data is returned in JavaScript Object Notation ( JSON) format prior to the execution of any JavaScript code defined using the oncomplete attribute.

The <a4j:jsFunction> component requires the data attribute. Use the data attribute to define where the retrieved server-side data is stored.

Example 3.4, “<a4j:jsFunction> example” shows how an Ajax request can be initiated from the JavaScript and a partial page update performed. The JavaScript function can be invoked with the data returned by the Ajax response.

The <a4j:poll> component allows periodical sending of Ajax requests to the server. It is used for repeatedly updating a page at specific time intervals.

The <a4j:push> component performs real-time updates on the client side from events triggered at the server side. The events are pushed out to the client through the RichFaces messaging queue. When the <a4j:push> component is triggered by a server event, it can in turn cause Ajax updates and changes.

The <a4j:push> component uses the Comet model for pushing data to the client.

Using the Push component requires configuration steps which depends on an environment in which the Push is used:

The Push requires a PushServlet registered in web application and listening for Push client connections.

In the Servlets 3.0 and higher environments, the servlet will be registered automatically.

However in the Servlets 2.5 and lower environments, the servlet needs to be registered manually in web.xml:

<!-- Push Servlet - listens for user sessions -->
    <servlet-name>Push Servlet</servlet-name>
    <servlet-name>Push Servlet</servlet-name>

<!-- setups servlet-mapping in RichFaces configuration -->

Manual registration of servlet in Servlets 3.0

When you attempt to register the Push servlet manually in Servlet 3.0 environments, RichFaces will detect that the Push servlet is already registered and avoid initializing it again.

However, be sure to setup the Push servlet to support asynchronous requests - modify the servlet registration from the previous web.xml snippet as follows:

    <servlet-name>Push Servlet</servlet-name>

Switching to Blocking I/O instead of asynchronous servlets

Although a container you use supports Servlets 3.0, you may experience problems with using asynchronous servlets.

It is possible to force the Atmosphere to use a blocking I/O approach with the following web.xml configuration:


An integration of the RichFaces Push and the Java Messaging Service ( JMS) allows to write robust interactive applications.

The JMS instance on the back-end must be configured to work with your <a4j:push> components.

Configuring JMS on JBoss EAP

Refer to the JBoss EAP Administration and Configuration Guide for details on configuring JMS in JBoss EAP.

Ensure the Create durable subscriber and the Delete durable subscriber options are set to true for proper push functionality.

Durable subscriptions

Durable subscriptions receive all events, including those events which were sent while the push component was not connected.

Refer to JMS Documentation for details on configuring the JMS Server.

JMS integration with custom configuration

RichFaces looks for the JMS Connection Factory on the JNDI context /ConnectionFactory by default.

The prefix /topic is used for deriving JMS topic names from Push topic names.

When integrating component into an enterprise system, this defaults can be changed.

Use following web.xml parameters to change default values: org.richfaces.push.jms.connectionFactory, org.richfaces.push.jms.topicsNamespace.

When RichFaces obtains a connection, an empty user name is used with an empty password.

Use following web.xml parameters or equivalent JVM parameters to change default values: org.richfaces.push.jms.connectionUsername, org.richfaces.push.jms.connectionPassword.

The JMS message which should be propagated to Push needs to be created with the method session.createObjectMessage(message);.

The message could be then published using publisher.publish(message); like in a following example:

Receiving messages from a JMS queue doesn’t differ from receiving messages sent by the TopicsContext or using CDI events.

The above example demonstrates a simple use of the <a4j:push> tag that causes an immediate update of the page content.