Converting ICEfaces 1.8 Applications to 2.0

You are viewing an old version (v. 4) of this page.
The latest version is v. 37, last edited on Feb 08, 2017 (view differences | )
<< View previous version | view page history | view next version >>

Converting ICEfaces 1.8 Applications to 2.0

With the release of JSF 2.0 and ICEfaces 2.0.x, a common situation arises of porting and converting existing ICEfaces 1.8.x. This tutorial will demonstrate the required steps to convert a legacy application to "compat mode" in ICEfaces 2.0. This means you can still use your existing ice: components and backing beans, but aren't yet taking advantage of 2.0 specific features and benefits. The majority of the converting effort involves configuration files and libraries, so most of your page markup won't need to be significantly changed.

This tutorial assumes the reader has a basic understanding of JSF and ICEfaces, especially creating and working with projects related to those technologies. The focus is not to teach the foundations, but instead to learn about porting applications.

The goal of this tutorial is to examine a real world ICEfaces 1.8.x application. Once we have an understanding of the project we will begin the steps to port the application to ICEfaces 2.0. The application is a slightly modified version of the "jobApplication" used in the ICEfaces Online Training. There is a central form based page that can redirect to two pages based on different outcomes.

Here is the entire list of steps worked through during this tutorial:

  1. [Make the windowScope Project]
  2. [Add ICEfaces]
  3. [Create 3 Beans with Different Scopes]
    • [Create]
    • [Create]
    • [Create]
  4. [Create]
  5. [Create Two Pages]
    • [Create page1.xhtml]
    • [Create page2.xhtml]
  6. [Deploy and Test the Application]
  • [Tutorial Source Code Downloads]

Development Tools Used

The following tools were used to create the project.

1.8 jobApplication Source Code

Example Source Notes
1.8 jobApplication project [jobApplication source code |^|Download Source Code] The Eclipse workspace of the jobApplication project written in ICEfaces 1.8.

jobApplication Introduction

Download and extract the above source code bundle, and Import -> Existing Project into Workspace the folder into your Eclipse instance. Build and deploy the application to your Tomcat instance, and navigate to the deployed jobApplication. You will see a page similar to the following:

Now let's examine the page code, to get a better idea of what the application is doing. There are three main pages:

  • applicantForm.xhtml
    • Main page that has a series of internationalized form fields with validation, partialSubmit, a ice:selectInputDate component, etc.
  • noThanks.xhtml
    • Basic page redirected to when the first name equals "John".
  • thankYou.xhtml
    • Similar page redirected to when the first name is anything else.

The Java code is fairly standard for 1.8, focusing on two beans:

    • Controller/backing bean for the applicantForm.xhtml page. This controls the submission and some of the rendering toggles on that page.
    • Model object containing variables for the different Applicant fields, like First Name and Travel Percentage. No UI specific functionality.
  • Supporting Beans
    • The and classes are used to back the available items in the ice:selectOneMenu found on the main page.

Other features:

  • Internationalization
    • The and are used to internationalize the various form labels.

Begin Converting the jobApplication

Now that we understand the project a bit better, we'll start the 1.8 to 2.0 conversion process. The steps below will help you understand the requirements of porting, and can be applied to any of your own projects.

*Step 1* - Add and Update Libraries

Currently jobApplicaiton is using ICEfaces 1.8.2 and JSF 1.2. We will want to upgrade these versions to 2.0.

*Step 1a* - Remove Old Libraries

First remove references in our project to ICEfaces 1.8.2 and JSF 1.2. This will likely require Build Path changes inside Eclipse. The ICEfaces Core, Facelets, and Support Libraries 1.8.2 should be removed, as should JSF 1.2 Sun RI. The exact naming may be different in your project.

*Step 1b* - Add Compat Jars

Download and extract the ICEfaces 2 bundle, and copy the following jar files from icefaces/compat/lib/ to jobApplication/WEB-INF/lib/:

  • commons-beanutils.jar
  • commons-collections.jar
  • commons-digester.jar
  • commons-logging.jar
  • icefaces-compat.jar
  • icefaces.jar
  • jstl.jar
  • jxl.jar
  • krysalis-jCharts-1.0.0-alpha-1.jar

Note that jstl.jar is only required when running an ICEfaces compat application on Tomcat, which we are, so include it.

The primary jars are icefaces.jar and icefaces-compat.jar. The former contains all the ICEfaces 2.0 code we need, while the latter has compat specific code around ice: components.

*Step 1c* - Add JSF 2.0 Jars

Now we will add JSF 2.0. There are two jars we need to reference in icefaces/lib/ called jsf-api.jar and jsf-impl.jar. The recommended approach is to create a custom User Library in your Eclipse project, but the jars could also be copied to the jobApplication/WEB-INF/lib/ folder.

There will probably be a few errors within the project because of these changes. That's okay, we just need to modify the configuration and pages to be 2.0 specific to resolve this problem.

*Step 2* - Update faces-config.xml

Now we will change the XML configuration file faces-config.xml. The main changes will be scope related, to accomodate the new JSF 2.0 scopes.

*Step 2a* - Update Header

First we'll update the faces-config.xml header to be 2.0, instead of 1.2. Near the top of the file replace:

Old faces-config.xml Header
<faces-config xmlns=""


New faces-config.xml Header
<faces-config xmlns=""

As you can see we changed the version and schema location to 2.0.

*Step 2b* - Remove View Handler

Now we can remove the old reference to the D2DFaceletViewHandler, as this ICEfaces customization is handled transparently in 2.0. Remove the following line inside the <application> node:

Old faces-config.xml View Handler

*Step 2c* - Change Bean Scopes

Next we will modify the old <managed-bean-scope> nodes to conform to those available in ICEfaces 2.0. Previously ICEfaces 1.8.x used "extended request scope", which meant request was handled differently than it is now. The closest we can get to duplicating this functionality is using the new view scope.

Change all 3 beans to have a scope of view:

Old faces-config.xml Bean Scope

Will become:

New faces-config.xml Bean Scope

*Step 3* - Update web.xml

Enter labels to add to this page:
Please wait 
Looking for a label? Just start typing.

© Copyright 2017 ICEsoft Technologies Canada Corp.