Home Classroom ICEfaces


In my last article I explained what is Ajax Push and showed you how to use the SessionRenderer API.

This article will show you how to change the code to use RenderManager API in sample chat application explained in the last article.

Also please note that the ICEfaces 1.8.2 was released on 30th September 2009 and there is a new Eclipse update site: http://www.icefaces.org/eclipse-updates/

Introduction to RenderManager API

The RenderManager API is an advanced API, which supports more functionality over SessionRenderer API.

Following table shows a comparison of two APIs.

Table 1: Comparison of SessionRenderer and RenderManager API


Rendering Architecture

There are three key elements to the Ajax Push. (I mentioned these in my previous article)

  1. Render Manager – This is an application scoped managed bean to coordinate all render requests. This is also used to register render groups. The object we use is an instance of class “RenderManager”
  2. Render Group – A render group manages several Renderables (clients) that will receive same push updates. Types of render groups are: on-demand, interval and delay. Here we use objects that are instance of “GroupAsyncRenderer” class
  3. Renderable – Any request or session scoped managed bean implementing “Renderable” interface can be added to render group and push updates.
The figure 1 from ICEfaces Developer’s Guide shows how updates are pushed to client by different Group Renderers.

According to the architecture, you need to do following steps to use RenderManager API.

  1. Add Render Manager to application. This is for us to access the Render Manager in the application code.
  2. Create Render Groups, which will allow us to group the push events.
  3. Request a render on a Render Group.

Let’s see how we use above mentioned three key elements in our application. I will explain each in detail and show you the complete code in a separate section.


Renderable Interface

The Renderable interface has two methods.

public interface Renderable {

PersistentFacesState getState();

void renderingException(RenderingException renderingException);



This interface is typically implemented in request-scoped or session-scoped managed beans. The “getState()” method should return the current persistent faces state of the application. The “renderingException()” method is the exception callback method.


In order to return the PesistenceFacesState, you need to get the state from “PersistentFacesState” using the static “getInstance()” method.

You can use the constructor of the bean to get the “PersistentFacesState” in a request scoped bean.

Please note that the “PersistentFacesState” might be changed during the session, therefore in session-scoped beans you have to make sure that “getState()” returns the current state.

A recommended way is to get the state inside a valid getter method, which is bound to a page.


RenderManager Class

The RenderManager is the main class in the push API. There should be only one instance per application and therefore it can be configured as an application-scoped managed bean in JSF configuration file.

Then you can “inject” the RenderManager instance to any request-scoped or session-scoped managed beans.

GroupAsyncRenderer Implementations

There are several GroupAsyncRenderer implementations for use in application. Each instance provides a way to handle group rendering requests.

For example, in the sample chat application, a group is created and each user can be notified via the the group.

Each implementation allows to add or remove instances of “Renderable”.

Table 2: Comparison of GroupAsyncRenderer implementations

As you can see, the methods used to get GroupAsyncRenderer implementation has a String argument. That argument is the name we define for the group.


DisposableBean interface

This interface can be used to write the clean up code. This is not only used for RenderManager API.

public interface DisposableBean {

void dispose()throws Exception;


The “dispose()” method is called by ICEfaces framework whenever the bean goes out of scope.


Rendering Exceptions

Whenever server-initiated rendering fails, you will be notified via the exception callback method in Renderable. When exception is thrown, client will not receive recent set of updates.

There are three exceptions and the figure 2 shows the class hierarchy.   

Figure 2 : Rendering Exception Hierarchy


1. RenderingException

The RenderingException exception indicates general failure and the application may handle TransientRenderingException and FatalRenderingException subclasses in different ways.

2. TransientRenderingException

The TransientRenderingException exception is thrown when the rendering fails, but future rendering may succeed.

3. FatalRenderingException

The FatalRenderingException exception is thrown when the rendering fails and the cause might be the client is no longer connected (i.e. session expired). In this case, the server should clean up any resources used for the client.  


Sample application using the RenderManager API

Finally, it’s time to see the RenderManager API in action. The same chat application used in the previous article is used. Actually the chat application is similar to an IRC (Internet Relay Chat) client.

Here SessionRenderer API related code will be removed from sample application. There will be no change to the XHTML page.

1. We need to changed the code in our ManagedBean.java to use RenderManager API. (ManagedBean.java is the request scoped managed bean).

There are two interfaces to implement: Renderable and DisposableBean. Here “OnDemandRenderer” is used as we want to request a render after a chat message is added.

In the constructor, the PersistentFacesState is saved to an instance variable. The RenderManager is injected to this bean and it is configured in the faces-config.xml.

Whenever there is a failure or when the bean goes out of scope, the bean is removed from “OnDemandRenderer”.

The Renderable instance is added to the OnDemandRenderer group in the “setRenderManager()” method. This method is called when the RenderManager is injected to the bean.  

Following is the code.

package view;

import java.text.MessageFormat;

import javax.faces.event.ActionEvent;

import com.icesoft.faces.async.render.RenderManager;

import com.icesoft.faces.async.render.Renderable;

import com.icesoft.faces.context.DisposableBean;

import com.icesoft.faces.webapp.xmlhttp.PersistentFacesState;

import com.icesoft.faces.webapp.xmlhttp.RenderingException;

publicclass ManagedBean implements Renderable, DisposableBean {

private String name;

private String message;

private ApplicationBean applicationBean;

private RenderManager renderManager;

private PersistentFacesState state;

public ManagedBean(){

// Get PersistentFacesState instance.

// This is a request-scoped managed bean

// and therefore we can get the instance

// in constructor

state =PersistentFacesState.getInstance();


publicvoid send(ActionEvent event){


MessageFormat.format(“{0}: {1}”, name, message));

// Request render call using OnDemandRenderer



public String getName(){

return name;


publicvoid setName(String name){

this.name= name;


public String getMessage(){

return message;


publicvoid setMessage(String message){

this.message= message;


publicvoid setApplicationBean(ApplicationBean applicationBean){

this.applicationBean= applicationBean;


publicvoid setRenderManager(RenderManager renderManager){

this.renderManager= renderManager;



public PersistentFacesState getState(){

// return current PersistentFacesState instance

return state;


publicvoid renderingException(RenderingException renderingException){

// No logic for handling exception

// Just remove this from the group



publicvoid dispose()throws Exception {




2. Configuring RenderManager application-scoped managed bean.

In faces-config.xml, we need to define the RenderManager as application-scoped managed bean

The qualified class name is “com.icesoft.faces.async.render.RenderManager” and we will use “renderManager” as the bean name.

Then the RenderManager should be injected to ManagedBean.

Following is the code for faces-config.xml





xsi:schemaLocation=“http://java.sun.com/xml/ns/javaee http://java.sun.com/xml/ns/javaee/web-facesconfig_1_2.xsd”
























<description>ICEfaces RenderManager</description>







Running the application

The final output of the application is same as the application I demonstrated in the previous article.

Following is a demonstration using Mozilla Firefox and Google Chrome.



In this article, you learned RenderManager API and how to use it. We used the sample application used in previous article, which used the SessionRenderer API.

You also learned how RenderManager API gives you better control over Ajax Push.

Please send your questions or suggestions to chrishantha@gmail.com





Ajax Push with ICEfaces
Welcome back to another article on ICEfaces. This time, you are going to learn how to build a simple application with Ajax Push.


What is Ajax Push?

Ajax Push is a powerful feature in ICEfaces and it is a way of pushing presentation changes to the client browser based on server-side events. This means that the server can decide when to refresh the client user interface based on dynamic state changes.

So, what is interesting here is that Ajax Push enables real-time collaborative features. When multiple users are interacting with the same application, each user can be instantly aware of each others actions.

Ajax Push is also known as “Server-initiated Rendering”.


How it works?

ICEfaces Ajax Push is based on the concept of HTTP protocol inversion, which uses the technique of holding an open request from the browser, and responding to that request when something is available to be pushed.

Following diagram from www.icefaces.org shows the mechanism in Ajax Push.


  1. ICEfaces application initially makes a blocking request to server.
  2. The state of the application is changed and the application requests to render.
  3. JSF Component Tree is created.
  4. Server DOM changes are identified.
  5. Incremental update is sent back to the client browser via Ajax Bridge.
  6. Application makes another blocking request.
  7. Incremental update is applied to client DOM.

Let’s see how to make use of this mechanism.


APIs for Ajax Push

There are three key elements to the Ajax Push.

  • Render Manager – This is an application scoped managed bean to coordinate all render requests. This is also used to register render groups.



  • Render Group – A render group manages several Renderables (clients) that will receive same push updates. Types of render groups are: on-demand, interval and delay.



  • Renderable – Any request or session scoped managed bean implementing Renderable interface can be added to render group and push updates.



ICEfaces framework provides two different APIs for us to use server-initiated rendering in our application.

  1. RenderManager – The RenderManager API is a very powerful API, which provides better control over Ajax Push requests. This API make use of above mentioned key elements and there are several steps to configure.
  2. SessionRenderer – The SessionRenderer API is the most easiest API to use as it is designed to make use of Ajax Push with least effort. Actually the RenderManager API is used inside this API.

I am explaining only SessionRenderer API in this article and other API will be explained in a later article.


Sample application using the SessionRenderer API

Let’s use the SessionRenderer API to create a very simple chat application, which will be similar to an IRC (Internet Relay Chat) client.

The application will consist of two inputs. One input will be used to enter the user name and the other input will be the chat message. The command button “Send”, will add the message to application scoped list and list of messages will be displayed in the same page.

Here we are using a list in application scoped managed bean as every user connected should be able to see the message. When a message is added, we use SessionRenderer API to update message list in all users.

In my last article, I created a sample application using Eclipse IDE. This time we will extend the same application to meet our requirements.

1. First we will create the Application Scoped Managed Bean. Create the bean in the same way we created the managed bean in last article. Remember to select “application” as the scope.

Following is the code.

package view;

import java.util.ArrayList;

import java.util.Collections;

import java.util.List;

public class ApplicationBean {

private List<String> messagesList;

public ApplicationBean() {

messagesList = Collections.synchronizedList(new ArrayList<String>());


public List<String> getMessagesList() {

return messagesList;




This bean contains the list of messages. I created a synchronized list to avoid any concurrency issues.

Only one instance of this bean will be created for the application.


2. Following is the changed code for ManagedBean.java. (The request scoped managed bean).


package view;

import java.text.MessageFormat;

import javax.faces.event.ActionEvent;

import com.icesoft.faces.async.render.SessionRenderer;

public class ManagedBean {

private String name;

private String message;

private ApplicationBean applicationBean;

public ManagedBean() {



public void send(ActionEvent event) {


MessageFormat.format(“{0}: {1}”, name, message));



public String getName() {

return name;


public void setName(String name) {

this.name = name;


public String getMessage() {

return message;


public void setMessage(String message) {

this.message = message;


public void setApplicationBean(ApplicationBean applicationBean) {

this.applicationBean = applicationBean;




This bean has properties to store name and message.

When using the SessionRenderer API, the we need to add the current session to a named group.

Therefore in constructor, we call SessionRenderer.addCurrentSession(String groupName) method.

Render groups are maintained using unique names and here we used “chat” as the group name. Then an update related to “chat” group is pushed via SessionRenderer.render(“chat”) method call.

Also note that the group for current session can be removed from SessionRenderer.removeCurrentSession(String groupName) method.


3. Defining managed beans. Open faces-config.xml. You can select “Source” tab in Faces Configuration Editor.


?xml version=“1.0″ encoding=“UTF-8″?>




xsi:schemaLocation=“http://java.sun.com/xml/ns/javaee http://java.sun.com/xml/ns/javaee/web-facesconfig_1_2.xsd”




















You can see that “applicationBean” is injected to “managedBean” by using <managed-property> tag.

4. The ICEfacesPage1.xhtml file

<?xml version=“1.0″ encoding=“UTF-8″?>

<!DOCTYPE html PUBLIC “-//W3C//DTD XHTML 1.0 Transitional//EN” “http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd”>

<html xmlns=“http://www.w3.org/1999/xhtml”






<title><ui:insert name=“title”>Ajax Push Demo</ui:insert></title>



<div id=“header”></div>

<div id=“content”>



<ice:outputLabel value=“Name:” for=“txtName”></ice:outputLabel>

<ice:inputText id=“txtName” value=“#{managedBean.name}”></ice:inputText>



<ice:outputLabel value=“Message:” for=“txtMsg”></ice:outputLabel>

<ice:inputText id=“txtMsg” value=“#{managedBean.message}”></ice:inputText>

<ice:commandButton value=“Send” actionListener=“#{managedBean.send}”></ice:commandButton>


<ice:panelSeries id=“pngMsg” value=“#{applicationBean.messagesList}”


<ice:outputText id=“otxtMsg” value=“#{msg}”

style=“display: block; border-bottom: 1px dotted blue;”>







There are two inputs to get the Name and Message.

PanelSeries component is used to display the list of messages. This component is used to iterate over a collection of objects. In this example, we iterate all messages in applicationBean and display using outputText component.

Running the application

From Eclipse IDE, run the application. To demonstrate the collaborative features, we will open the application in two different browsers. Running the application in different browsers will create different sessions.

I will use Mozilla Firefox and Google Chrome to demonstrate the application.

In both browsers, enter name, message and click on “Send”. Keep the browsers side by side to see how the message you entered in one browser appear in other browser.



I only showed you the basics of Ajax Push, but you saw how easy to use this feature in an ICEfaces application. Every hard work has been done by ICEfaces framework for us to make things easier to use server initiated rendering.

In next article, I will show you how to use the RenderManager API for this same application.

Please send your questions or suggestions to chrishantha@gmail.com





Getting started with ICEfaces and Eclipse
In my last article, I introduced the ICEfaces framework and I hope you all enjoyed reading it.

As I promised, I am going to explain how to create a simple project using Eclipse IDE (Integrated development environment). Needless to say, Eclipse is one of the best IDEs in the world and it is my favorite.

ICEfaces has released a plug-in to Eclipse. I will show you how to install the plug-in. ICEfaces plug-in will help you to get started with ICEfaces project development.

By the way, are you new to Eclipse? Please visit http://www.eclipse.org/ and explore.

Installing ICEfaces Integration For Eclipse Galileo

Eclipse Galileo is the latest annual release from Eclipse Foundation. If you do not have it, please download from http://www.eclipse.org/downloads/. Make sure you download “Eclipse IDE for Java EE Developers (189 MB)” as we are going to create a web application.

Here are the steps to install ICEfaces Integration For Eclipse Galileo.


1. Download “ICEfaces-1.8-Eclipse-3.5.0-plugins-v3.6.1.zip” from www.icefaces.org downloads page and extract it to a directory. (Eclipse Galileo version is 3.5)


2.  Now run Eclipse and select Help → Install New Software…


3.  Then select “Add” → “Local…”


4. Please give the path to extracted ICEfaces plugin directory.


5. Click “OK”.


6. Make sure “Group items by category” is unchecked.



7. Select all features listed:ICEfaces Eclipse Integration – Core, ICEfaces Facelets Eclipse Integration and JSF Facelets Tools Incubator


8. Click Next.


9. Accept licenses and Finish


10. Restart Eclipse


That’s all you have to do to install ICEfaces integration.


Creating a new ICEfaces Project

Now I am going to show you how to create a new ICEfaces project in Eclipse.

1. In Eclipse, select File → New → Other…

2. Select Web → Dynamic Web Project and click on Next


3. Give a name to the project.


4. Select a Target Runtime. We will use Tomcat 6. Click on “New” and select “Apache Tomcat v6.0”. Click next and select the directory of tomcat installation. I recommend you to download “tar.gz” version of Tomcat 6 Core Binary Distribution from http://tomcat.apache.org/download-60.cgi. Then you can extract tomcat to a new directory and give the path.


5. Now you should be back in “New Dynamic Web Project” window. Dynamic web module version should have changed automatically to 2.5 after selecting Tomcat 6.


6. Select “ICEfaces Facelets Project” for Configuration.



Note:I recommend you to select Facelets, which is an alternative view technology for building JSF applications. It’s very simple and easy to use. See Resources for more information.


7. Click “Next”. You will be asked to configure source and build directories. Keep the defaults and click “Next”.


8. Also keep the defaults in Web module configuration. Click “Next”



9. Now you should get “JSF Compatibilities” page and here you have to download the required libraries. Click on “Download Library…”



10. There is a list of libraries to select. You have download one library at a time.


11. Download “ICEfaces Core Library v1.8.1”, “ICEfaces Facelets Library v1.8.1”, “ICEfaces Support Library v1.8.1” and “JSF 1.2 (Sun RI)”
12. Make sure “Include libraries with this application” is checked. Click “Finish”. (There are some more additional configuration, but defaults will be okay. Click “Next” if you want to see additional configuration


You should see the new project in Project Explorer view.

I hope you now understand how to create a new ICEfaces Project from Eclipse.

Creating a simple application

Let’s create a simple application.

We will add components to “ICEfacesPage1.xhtml” page, which was created automatically by the new project wizard.

You can also add new pages and the you can select a template using the wizard. When using Facelets, make sure to create new HTML page using .xhtml as extension.

We will create the page to enter a name and then say “Hello” to the user after clicking on a button.

First of all, we will create a managed bean to store data. Following are the steps.

1. In WEB-INF directory, double click on “faces-config.xml”. Eclipse should open Faces Configuration Editor. Click on “Managed Bean”


2. Then click “Add” and create a new Java Class.

3. Enter “view” as the package, and “ManagedBean”as the class name. Click “Next”

4. Select “request” as scope. Click “Finish”

5. Click on “Managed Bean class” to go to the class file




6. Write code for storing name and the action listener method for button in the managed bean. Following is the source code for ManagedBean.java


package view;

import javax.faces.event.ActionEvent;

publicclass ManagedBean {

private String name;

private String greeting;

public String getName() {



publicvoid setName(String name) {

    this.name = name;


public String getGreeting() {



publicvoid sayHello(ActionEvent event) {

    this.greeting = “Hello, “ + name;



7. Now create the page for the requirement. Following is the source code for the ICEfacesPage1.xhtml page.

Note:You can also get a close-to-WYSIWIG Web Page editor in Eclipse. Right click xhtml file in Project Explorer View and select Open With → Web Page Editor.


<?xml version=“1.0″ encoding=“UTF-8″?>

<!DOCTYPE html PUBLIC “-//W3C//DTD XHTML 1.0 Transitional//EN” “http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd”>

<html xmlns=“http://www.w3.org/1999/xhtml”






<title><ui:insert name=“title”>Hello World</ui:insert></title>



<div id=“header”></div>

<div id=“content”><ice:form>

<ice:outputLabel value=“Your Name:” for=“txtName”></ice:outputLabel>

<ice:inputText id=“txtName” value=“#{managedBean.name}”></ice:inputText>

<ice:commandButton value=“Say Hello”


<ice:outputText value=“#{managedBean.greeting}”

    style=“color:blue; font-size:16pt;”></ice:outputText>




Running the Project

Now it’s time to run the project.

Before running you can select which browser to open the web page. We will select the “Default system Web Browser” from Eclipse Window Menu → Web Browser.

Right click on the project name, “ICEfacesProject” in Project Explorer view and select Run As → Run on Server.

Select Tomcat v6.0 Server and click on “Finish”.


Now enter your name and click on “Say Hello”


In this article I demonstrated creating a very simple project.

In the next issue, I will explain creating a little more advanced application with the use of Ajax Push.

If you have any questions, please send a mail to chrishantha@gmail.com



ICEfaces Main Website – http://www.icefaces.org/

ICEfaces Documentation – http://documentation.icefaces.org/

ICEfaces Blog – http://blog.icefaces.org/

The component showcase – http://component-showcase.icefaces.org/

ICEfaces Forums – http://www.icefaces.org/JForum/

ICEfaces Twitter  - http://twitter.com/icefaces

The ICEfaces Tutorial – http://facestutorials.icefaces.org/tutorial/index.html

Inside Facelets Part 1:An Introduction – http://www.jsfcentral.com/articles/facelets_1.html

Inside Facelets Part 2:Using Facelets – http://www.jsfcentral.com/articles/facelets_2.html

Facelets fits JSF like a glove -http://www.ibm.com/developerworks/java/library/j-facelets/


Introducing ICEfaces!

In this article, I am going to introduce ICEfaces and why you should start learning it.

ICEfaces is a product from ICEsoft Technologies Inc., and the official website is http://www.icefaces.org

ICEfaces is open source and it is licensed under the Mozilla Public License 1.1 (MPL).



ICEfaces is an integrated Ajax Java application framework that enables Java EE Ajax application developers to easily create and deploy thin-client rich Internet applications (RIA) in pure Java.

ICEfaces applications are JavaServer Faces (JSF) applications. I would say that most significant difference with ICEfaces and pure JSF application is the integration of Ajax.

Since ICEfaces applications are based on JSF, having a general knowledge about JSF is essential.

If you know JSF well, then you can learn ICEfaces very easily.

When it comes to Ajax, you know that JavaScript plays the main role. With ICEfaces, you do not have to do any JavaScript related development. Therefore ICEfaces enables you to develop rich internet applications using pure Java. Main advantage is that you can concentrate more on business logic.

I believe you also have an idea about RIA. Rich Internet applications (RIAs) are web applications similar to desktop applications. There was an article about RIA in April 2009 issue of diGIT magazine.


ICEfaces Architecture

Main goal of ICEfaces is to hide complexities in developing Ajax applications. As mentioned in ICEfaces web site, the key to the ICEfaces architecture is a server-centric application model, where all application logic is developed in pure Java, and executes in a standard Java application server runtime environment.

Since ICEfaces is based on JSF, it offers component based architecture for developing user interfaces.

Also note that ICEfaces requests and responses follow the standard JSF Application Lifecycle.

There are three core elements to the ICEfaces architecture.

1. ICEfaces Framework

2. Ajax Bridge

3. ICEfaces Component Suite


The ICEfaces framework extends the JSF framework by introducing a new way to render the page. In standard JSF, render phase causes a full page refresh in the browser.

With ICEfaces framework, the page is rendered to a server side DOM (Document Object Model). Only incremental changes to the DOM are sent to the browser. This incremental update result in a seamless, smooth update of the browser page.

For example, suppose there is a text box and a button in a page. When a user initially requests the page, ICEfaces creates a server side DOM and sends the entire DOM to the browser. You write the application logic to accept the name from text box when the button is pressed and you display a label below the text box greeting the user. When a user enters a name and clicks on the button, ICEfaces only sends the new label to the browser using an algorithm to identify the changed elements in the DOM.

The Ajax Bridge coordinates communication between the client browser and the server application. As it name suggests, all requests and responses are Ajax based. The Bridge is responsible for applying incremental changes to browser DOM. The Bridge is also responsible for detecting user interaction with the browser, and delivering user events back to the application.

ICEfaces Component Suite provides the components to develop the user interface. Each ICEfaces component has an attribute for using partial submit, which enables automatics event generation over the Ajax Bridge based on user interaction.


Ajax Push

Ajax Push is a great feature in ICEfaces. Ajax Push refers to the technique of updating user interface based on server side events.

This is very useful for collaborative features as every user can be instantly aware of each others actions.

ICEfaces framework provides a pure Java API for enabling Ajax Push.


Benefits of using ICEfaces

  • Over 50+ auto Ajax components.
  • Easy Ajax
  • Ajax Push
  • Open Source
  • Based on Java Standards. (JavaServer Faces)
  • Compatibility with wide range of Java Application Servers. (Tomcat, Websphere Application Server, GlassFish etc.)
  • Support for IDE Tools. (Eclipse, Netbeans)
  • Easy styling with CSS
  • Security and many more.



My main goal of this article was to introduce ICEfaces framework. I am a Java Developer and I have more than one year experience with ICEfaces.

ICEfaces is very powerful and there are lot of things to learn.

Please make sure to visit http://www.icefaces.org/ for more information. All the information in this article are obtained from the ICEfaces web site.

In the next issue, I will explain how to create a simple project using Eclipse IDE. I will also explain how to install the ICEfaces tool integration for Eclipse.