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.

Figure 3.1. <a4j:commandButton>


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.

Figure 3.2. <a4j:commandLink>


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>
    <servlet-name>Push Servlet</servlet-name>
    <servlet-class>org.richfaces.webapp.PushServlet</servlet-class>
    <load-on-startup>1</load-on-startup>
</servlet>
<servlet-mapping>
    <servlet-name>Push Servlet</servlet-name>
    <url-pattern>/__richfaces_push</url-pattern>
</servlet-mapping>

<!-- setups servlet-mapping in RichFaces configuration -->
<context-param>
    <param-name>org.richfaces.push.handlerMapping</param-name>
    <param-value>/__richfaces_push</param-value>
</context-param>

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.


Ensure the Create durable subscriber and Delete durable subscriber options are set to true for 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

The 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 method session.createObjectMessage(message);.

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


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


This example demonstrates a simple use of the <a4j:push> causing an immediate update of page content.