Woodstock to ICEfaces Porting Guide - Part 1

This document guides you through the process of porting Woodstock applications to ICEfaces. The porting process is devised to be evolutionary in nature, allowing you to maintain a functional Woodstock application, while incrementally porting Woodstock pages to ICEfaces. The ultimate goal of the porting process is to entirely eliminate Woodstock from the application, leaving you with a pure ICEfaces application where you can take full advantage of all the rich features provided in the ICEfaces framework.

The migration support in ICEfaces is based on project-level coexistence with Woodstock, which means ICEfaces and Woodstock pages can coexist in the same web application. The approach is not intended to support page-level coexistence of ICEfaces and Woodstock, where components from both frameworks are included in the same page. That being said, subsequent releases of ICEfaces will include selectively ported Woodstock components that will exist as first-class citizens of the ICEfaces framework. The availability of these components will ease the page-level porting effort, but not eliminate it.

The majority of Woodstock applications are based on the Visual JSF project type in NetBeans, so this guide focuses on this particular migration path. If your application leverages Woodstock in some other programming model like Facelets, most of the concepts presented here still apply. The guide is presented in three parts.

Contents

• Adding the ICEfaces Plugins in NetBeans
• Establishing a Working Example
• Adding ICEfaces to an Existing Woodstock Application
• Understanding the ICEfaces Page Template
• Woodstock Component Bindings
  • Eliminating component bindings in the working example
• Creating a New ICEfaces Page
• Page Porting Basics
• Component-by-Component Porting
  • Standard JSF component porting
  • Woodstock component porting
• Porting the Working Example Page
  • Porting the masthead
  • Porting the page body
• Page Navigation
• Automatic Ajax
• Summary

 

At the completion of this guide you will be well-positioned to begin porting your Woodstock application to ICEfaces. Beyond this guide, you can examine issues related to porting data tables in Woodstock to ICEfaces Porting Guide - Part 2. The completed project for this step of the guide is available here.

Adding the ICEfaces Plugins to NetBeans

Woodstock migration support is available for the first time in the ICEfaces 1.7.2SP1 release, which is aligned with the NetBeans 6.5 release. Prior to embarking on a porting exercise you will need to upgrade to NetBeans 6.5, import your Woodstock Visual JSF project, and install the ICEfaces plugins for NetBeans. The steps required to install the ICEfaces plugins are as follows.

1. In the Main Toolbar, choose Tools > Plugins.

   The Plugin Manager opens.

2. In the Availables tab of the Plugin Manager, type the first few letters of the ICEfaces plugins to display the plugins in the Plugin Manager.

   
3. Select the checkbox next to each plugin and click Install.

4. In the NetBeans IDE Installer click Next. Accept the terms in all of the license agreements and click Install.

   Note: A dialog box may appear displaying a warning about third-party plugins.

5. Restart the IDE.

Establishing a Working Example

The working example for this guide is based on a readily available NetBeans sample project call Two Page CRUD With Table. It is chosen for it's relative simplicity, and because it is a multi-page application with navigation. Over the course of the migration we will add the ICEfaces framework, add ICEfaces pages, and port existing Woodstock pages to ICEfaces. We will also establish navigation between ICEfaces and Woodstock pages. You can get your own working copy of the example using the File > New Project dialog and choosing from Samples > Java Web (Visual JSF) > Two Page CRUD With Table, as shown in the following image.

Adding ICEfaces to an Existing Woodstock Application

The first step in the porting process is to add the ICEfaces framework to the project using the following steps.

1. Access the Project Properties dialog by right-clicking the TwoPageCrudTable project and selecting Properties.

2. In the Project Properties dialog box, select Frameworks and click Add. In the Add a Framework dialog box, select the Visual Web ICEfaces frameworks as shown in the following image.

   

3. Complete the dialog by selecting Synchronous Update in ICEfaces Settings and clicking OK, as shown in the following image. Synchronous updates simplify the client/server communications in applications where ICEfaces Ajax Push capabilities are not being leveraged. Synchronous updates most closely match the existing behavior of the application. The other setting, Concurrent DOM View, is discussed in Part 3 of this guide. For now, it should be left unchecked.

   

Adding the ICEfaces framework to the project results in a number of changes, including:

1. Configuration in web.xml is modified to include:
   • ICEfaces-specific context parameters
   • ICEfaces Servlets
   • ICEfaces Servlet mappings
2. ICEfaces design and run time libraries are added.
3. A template ICEfaces page called IcePage1.jsp is created.
4. A template index.html page is created.

The project should be runnable as is, but with the introduction of index.html, you need to do one of the following:

• Adjust the Run properties in Project Properties to specify a relative URL of /faces/Page1.jsp
• Modify index.html to redirect to the appropriate page, something resembling the following code sample.

   <meta http-equiv="refresh" content="0;url=faces/Page1.jsp">     

Understanding the ICEfaces Page Template

The ICEfaces NetBeans plugin provides JSF Visual Design capabilities similar to the Woodstock-based JSF Visual Design capabilities that your existing project is based on. The ICEfaces page template strongly resembles the Woodstock template as shown in the following image in a diff of these two pages. If you only use navigation.xml for navigation rules in imported projects, you should not have any problems. The following rules should help you resolve such conflicts.

As of NetBeans 6.5, the standard HTML tags <html>, <head>, and <body> are supported in the design view, so ICEfaces replacements are not required for <webuijsf:html>, <webuijsf:head>, and <webuijsf:body> and the standard HTML tags are used in the ICEfaces page template. Any page porting exercise will involve migrating the page content in the <webuijsf:form> of the Woodstock page to the <ice:form> in the replacement ICEfaces page.

Woodstock Component Bindings

Before you start porting Woodstock pages to ICEfaces pages, there is a potential problem with the application data model that you might need to address. If your Visual Web JSF Project was created prior to the NetBeans 6.1 release, and you have not already refactored to eliminate the component bindings, it will be necessary to do so. In the case of our working example, that refactoring has not occurred, so we will use it to describe the process of achieving this refactoring.

A quick review of JSF component bindings vs. value bindings is in order before proceeding. A component binding binds the view component to a component instance in the backing bean as shown in the following code sample.

The view component definition,

<h:outputText binding="#{myBean.someOutputText}" />

is bound to an instance of HtmlOutputText in the backing bean.

public class MyBean {
    HtmlOutputText someOutputText;
    public HtmlOutputText getSomeOutputText() {
       return someOutputText;
    }
    public void setSomeOutputText(HtmlOutputText outputText) {
       someOutputText = outputText;
    }
}

While component binds facilitate manipulation of the component directly from Java code, the view and the model become tightly coupled through the component class itself. When you consider porting away from a particular component you are forced to port the model as well, because the component instance will no longer be present. In contrast, value bindings bind the view component to a property in the backing bean as shown in the following code sample.

The view component definition,

<h:outputText value="#{myBean.someText}" />

is value bound to an instance of String in the backing bean.

public class MyBean {
    String someText;
    public String getSomeText() {
       return someText;
    }
    public void setSomeText(String text) {
       someText = text;
    }
}

This completely separates the view from the model, and ensures that the backing bean can be represented as a portable POJO. This is the essence of the refactoring that must occur prior to porting the page to ICEfaces.

Creating a New ICEfaces Page

Before we begin the process of porting a Woodstock page to ICEfaces, we need a template ICEfaces page to port into. The context menu Web Pages > New > ICEfaces Visual Web JSF Page will result in a new page dialog as shown in the following image. For our working example, the page is called IceCreatePage.jsp.

Page Porting Basics

There are two likely scenarios that are encountered when embarking on a page porting exercise.

1. If the new page design is significantly different than the existing page design and will take advantage of the extended features and components available in ICEfaces, the recommenced approach is to build an entirely new ICEfaces page using the Visual Editor and not attempt to port the existing Woodstock page. It is likely that the existing backing beans can be reused, but it may be necessary to augment those beans to support the new page functionality.
2. If the new ICEfaces page is to initially remain the same, with the intent of adding additional features only after the existing functionality has been reproduced, you should preserve the original page structure as much as possible, and reuse the existing backing beans. The recommended approach is to use the JSP editor to cut the page contents from the old page, and paste them into the new ICEfaces page. From there you can perform component-by-component conversion using the JSP editor. Considering our working example with CreatePage.jsp being ported to IceCreatePage.jsp, the resulting starting point for the page conversion is shown in the following image.

Component-by-Component Porting

Porting away from Woodstock components to ICEfaces components must be addressed on a component by component basis. To assist in this process a Component Mapping Matrix is available that provides component to component mappings, and attribute comparisons. We now examine the variations on component porting that you will likely encounter.

Porting the Working Example Page

Several different strategies can be taken when porting a page from Woodstock to ICEfaces. You can copy the entire page and its backing beans to a new page and do your porting there, or you can build a new JSP page, and reuse the existing backing bean as is. For the working example we take the later approach and reuse the exising Page1.java backing bean. To complete the page port we need to do the following.

1. Port Masthead.jspf
2. Port the main panelGrid in CreatePage.jsp

Page Navigation

With Woodstock, the request path is defined by the Servlet mapping /faces/* through the standard Faces Servlet. With ICEfaces the request path is defined by the Servlet mapping*.iface through the ICEfaces Persistent Faces Servlet. Because different Servlets are used for these request paths, it is necessary to use redirects when navigating to and from ICEfaces pages. The changes required to modify the navigation rules for the working example are shown in the following image.

The resulting navigation rules are:

 <navigation-rule>
        <from-view-id>/Page1.jsp</from-view-id>
        <navigation-case>
            <from-outcome>createCase</from-outcome>
            <to-view-id>/IceCreatePage.iface</to-view-id>
            <redirect/>
        </navigation-case>
        <navigation-case>
            <from-outcome>updateCase</from-outcome>
            <to-view-id>/UpdatePage.jsp</to-view-id>
        </navigation-case>
    </navigation-rule>
    <navigation-rule>
        <from-view-id>/IceCreatePage.jsp</from-view-id>
        <navigation-case>
            <from-outcome>created</from-outcome>
            <to-view-id>/faces/Page1.jsp</to-view-id>
            <redirect/>
        </navigation-case>
        <navigation-case>
            <from-outcome>canceled</from-outcome>
            <to-view-id>/faces/Page1.jsp</to-view-id>
            <redirect/>
        </navigation-case>
    </navigation-rule>

As you can see, Page1.jsp now navigates to IceCreatePage.iface using a redirect as the outcome of the Create button, and IceCreatePage.jsp navigates back to Page1.jsp using a redirect as the outcome of the Create and Cancel buttons.

Note: You cannot use the visual Page Flow Editor to make the necessary changes to incorporate ICEfaces navigation rules.

Automatic Ajax

With the functional ICEfaces page now in place you can begin to explore some of the Automatic Ajax features that the framework delivers - without altering a single line of code. Intelligent form processing is one such feature, where the application can react to the user on a field by field basis instead of processing the entire form when it is submitted. As an example, simple type some gibberish into the date field and then tab out of that field to the next. You will see that validation on the date field runs immediately and informs you that an invalid date has been entered, as shown in the following image.

A capability called partial submit is responsible for this behavior. Basically, a partial submit occurs as focus leaves the date field, which causes the JSF lifecycle to run. The submit is partial in that it will not validate the entire form, so you don't see validation messages for fields that have not been visited yet. Because the lifecycle runs it is possible to add business logic that analyzes the users input and adjust the form accordingly. In our case we have simply allowed the validation to run on the date input.

We will now extend the intelligent form processing by requiring that the From and To city fields are filled in prior to submitting the form. This is achieved by turning on the partialSubmit and required attributes in the inputText fields, as shown in the followin image.

<ice:inputText value="#{CreatePage.fromCity}" id="fromCity" partialSubmit="true" required="true"/>
<ice:inputText value="#{CreatePage.toCity}" id="toCity" partialSubmit="true" required="true"/>

If you rerun the application now, enter a valid date and then tab through the From City inputText, you will see validation occurring immediately as shown in the following image.

So you can see a more interactive form can be presented to the user with very little effort using ICEfaces. Of course you could add more sophisticated processing like checking the city against a database of valid destinations, and disabling the Add button until a valid form has been completed. Have a look at the ICEfaces Address Form Demo as another example of intelligent form processing.

Summary

You have now completed Part 1 of the Woodstock to ICEfaces Porting Guide. The complete project up to this point can be downloaded here. At this point you can go back to the table of contents, or move on to Part 2 of the guide, which focuses on porting a data table from Woodstock to ICEfaces.

See Also

• Woodstock to ICEfaces Porting Guide - Part 2
• Woodstock to ICEfaces Porting Guide - Part 3
• Java Web Applications Learning Trail

---