Migrate JavaServer Faces 1.x applications to JavaServer Faces 2.0


JavaServer™ Faces technology makes it easier to build user interfaces for JavaServer applications. Developers can quickly build web applications with reusable user interface components that can be connected to an application data source. JavaServer Faces 2.0 offers many development improvements and increases the performance of JavaServer Faces applications.

To simplify the migration process, you can use IBM® Rational® Application Developer for WebSphere® Software, which currently provides support for JavaServer Faces 1.2 and 2.0. IBM® WebSphere Application Server also supports both Java Server Faces 1.2 and Java Server Faces 2.0.

Main features of JavaServer Faces 2.0

JavaServer Faces 2.0 includes many new functions and improvements. The sections following this list describe the changes required to take advantage of these improvements:

  • Facelets technology: The view declaration language for JavaServer Faces technology. Facelets, the preferred presentation technology for JavaServer Faces applications, offers:
    • The ability to use xhtml code for web pages
    • The ability to set up page templates with Facelet tags
    • Support for composite user interface components
    • Support for the Expression Language
    • High-performance rendering
  • Less XML configuration: New options replace the need for XML tagging:
    • Use annotations for managed beans and their scopes
    • Take advantage of component annotations such as @FacesComponent, @FacesConverter, @FacesValidator
    • Rely on implicit navigation rules
  • Conditional navigation: You can implement conditional navigation by adding if statements.
  • Ajax technology: JavaServer Faces 2.0 now supports Ajax technology. Create an Ajax request using the <f:ajax> tag jsf.ajax.request() directly in a Facelet page.
  • Project Stage: Enables you to specify the role of the current deployment of the application. It offers better error reporting and debugging during software development, better performance in production, and improvements to system and unit test.
  • GET requests: Implement GET requests by adding view parameters and by using the preRenderView event.
  • Partial stages: You can now save only the state that has been changed since the creation of the component tree.
  • Improved validation: Take advantage of improved validation for:
    • Beans: <f:validateBean>
    • Required fields: <f:validateRequired>
    • Regular expressions: <f: validateRegexp>
    • Empty fields: javax.faces.VALIDATE_EMPTY_FIELDS context parameter
  • New scopes: Implement new scopes, such as:
    • Flash: Preserves FacesContext messages across redirects
    • View: Persists as long as a user interacts with the same view
    • Custom scopes
  • Java Context Dependency Injection beans: Use the new support for Java Context Dependency Injection beans (not covered in this article).

Migration considerations

To migrate existing JavaServer Faces 1.2 applications, implement the changes described in the following sections. The main migration tasks include:

Update JavaServer Faces configuration files

Update the JavaServer Faces configuration files (web.xml and faces.config) to accommodate the JavaServer Faces 2.0 specification.

To achieve compliance, use Rational Application Developer software to create a new JavaServer Faces 2.0 project and create these configuration files automatically with the basic configuration. Copy the extra artifacts included into the original configuration files.

If you don't have access to Rational Application Developer software, update the configuration files manually, using the directions in the following sections.

Modify the web.xml file manually

Update the web module attributes to be 2.5 or newer, as shown Listing 1.

Listing 1. Web module 2.5 attributes
<web-app xmlns="http://java.sun.com/xml/ns/javaee"

Change the javax.faces.DEFAULT_SUFFIX context parameter from .jsp to .xhtml, as shown in Listing 2. The extension used for Facelet pages is .xhtml.

Listing 2. Change the javax.faces.DEFAULT_SUFFIX

Modify faces-config.xml file

Update the version and schemaLocation to 2.0, as shown in Listing 3.

Listing 3. Update the version and schemaLocation to 2.0


Migrate JavaServer Pages to Facelet technology

JavaServer Pages technology still works with JavaServer Faces 2.0. To take advantage of JavaServer Faces 2.0 improvements, replace JavaServer Pages with Facelet technology.

Create a new Facelet page to get the basic template instead of replacing the content in an existing JavaServer Pages file.

Changes between JavaServer Pages and Facelets

  • Facelets are XHTML files, so the file extension for JavaServer Faces pages should be *.xhtml instead of *.jsp
  • The content type of the Facelet page is XHTML:
    	<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.1//EN" "http://www.w3.org/TR/xhtml11/DTD/xhtml11.dtd">
  • Tag libraries are defined as xmnls instead of <%@taglib%>:
    <html xmlns=xmlns:ui=
  • There are two additional name spaces for Facelets:

Defined for xhtml: http://www.w3.org/1999/xhtml

Taglib for user interface Facelet tags: http://java.sun.com/jsf/facelets

Table 1. JavaServer Page basic template compared to Facelet basic template
JavaServer Pages basic templateFacelet basic template
<%@pagelanguage=contentType = pageEncoding = %>
<%@taglib uri =    "http://java.sun.com/jsf/core" prefix="f"%>
<%@taglib uri = "http://java.sun.com/jsf/html" prefix="h"%>
 <meta http-equiv="Content-Type"  content="text/html; charset=ISO-8859-1">
	   JavaServer Faces components …
<?xml version="1.0" encoding="UTF-8" ?>
"http://www.w3.org/TR/xhtml11/DTD/xhtml11.dtd"> <html xmlns = xmlns:ui= xmlns:f= xmlns:h=> <h:head> <title>index</title> <meta http-equiv="Content-Type" content= "application/xhtml+xml;charset=UTF-8" /> </h:head> <h:body> JavaServer Faces components ... </h:body> </html>

Use Facelet tags to create page templates

Facelet technology provides a set of predefined tags to create and use page templates without require a configuration file. The main Facelet user interface tags used for Facelet templates include the following:

Defines a content section in a Facelet template. Optionally, assign a name with the name attribute. This tag is to be referenced by a define tag in another Facelet page.
Wraps content to be included into another Facelet. The template attribute specifies the Facelet template to use.
Defines the content to be inserted into a template. A name with the name attribute is required and must match with a ui:insert tag name of the template.

Migrate from Tiles to the Facelet template

Tiles templates (referred to as the Dynamic Page template in Rational Application Developer) have to be replaced for Facelet templates to work with JavaServer Faces 2.0. The main changes to make are:

  • At template creation replace the <tiles:insertAttribute name="..."> tags with <ui:insert name="..."> tags, for example:
    • With Tiles:
      <tiles:insertAttribute name="header"></tiles:insertAttribute>
    • With Facelet templates:
      <ui:insert name="header"></ui:insert>
  • To apply the template, use <ui:composition template="..."> instead of <tiles:insertDefinition name="...">
  • Use <ui:define name="..."> instead of <tiles:putAttribute name="..."> to insert the template's sections in the page.
Table 2. Tiles template compared to Facelet template
Tiles templateFacelet template
<%@page language="java" contentType= "text/html;charset=ISO-8859-1"
<%@taglib uri = "http://java.sun.com/jsf/core" prefix="f"%>
<%@taglib uri = "http://tiles.apache.org/tags-tiles" prefix="tiles"%>

  <tiles:getAsString name=   "documentTitle" />
 <meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">

   <f:subview id="subview1">
	<tiles:insertAttribute name="header" flush="false">
  <f:subview id="subview2">
     <tiles:insertAttribute   name="bodyarea" flush="false">
  <f:subview id="subview3">
	<tiles:insertAttribute name="footer" flush="false">
<?xml version="1.0" encoding="UTF-8" ?>
"http://www.w3.org/TR/xhtml11/DTD/xhtml11.dtd"> <html xmlns="http://www.w3.org/1999/xhtml" xmlns:ui="http://java.sun.com/jsf/facelets" xmlns:f="http://java.sun.com/jsf/core" xmlns:h="http://java.sun.com/jsf/html"> <h:head> <title>template</title> <meta http-equiv="Content-Type" content="application/xhtml+xml; charset=UTF-8" /> </h:head> <h:body> <f:subview id="subview1"> <ui:insert name="header"></ui:insert> </f:subview> <f:subview id="subview2"> <ui:insert name="bodyarea"> </ui:insert> </f:subview> <f:subview id="subview3"> <ui:insert name="footer"></ui:insert> </f:subview> </h:body> </html>

Migrate from design-time template (jtpl) to Facelet template (optional)

Optionally, replace design-time templates with Facelet templates. This change is not mandatory, because these templates do not use the JavaServer Faces runtime. It's easy to transform design-time templates into Facelet templates by making the following changes:

  • To create a template, replace <%--tpl insert attribute=""--%> tags for <ui:insert name="..."> tags
  • To apply the template, use <ui:composition template="..."> instead of <%--tpl:insert page="..."%>
  • To define the template sections to use, specify <ui:define name="..."> instead of <%-- tpl:put name="...">
Table 3. JTPL template compared to Facelet template
Design-time template (jtpl)Facelet template
<%-- tpl:metadata --%>
<%@page language="java"
  contentType="text/html; charset=ISO-8859-1" pageEncoding="ISO-8859-1"%>
<%@taglib uri = "http://java.sun.com/jsf/core" prefix="f"%>

<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">

<%--tpl:insert attribute="headarea"--%>
<%-- /tpl:insert --%>
 <%--tpl:insert attribute="header"--%>   Default content of header
 <%--tpl:insert attribute="bodyarea"--%> Default content of bodyarea
 <%-- tpl:insert attribute="footer" --%> Default content of footer
<?xml version="1.0" encoding="UTF-8" ?>
"http://www.w3.org/TR/xhtml11/DTD/xhtml11.dtd"> <html xmlns="http://www.w3.org/1999/xhtml" xmlns:ui="http://java.sun.com/jsf/facelets" xmlns:f="http://java.sun.com/jsf/core" xmlns:h="http://java.sun.com/jsf/html"> <h:head> <title>template</title> <meta http-equiv="Content-Type" content="application/xhtml+xml; charset=UTF-8" /> </h:head> <h:body> <f:subview id="subview1"> <ui:insert name="header"></ui:insert> </f:subview> <f:subview id="subview2"> <ui:insert name="bodyarea"> </ui:insert> </f:subview> <f:subview id="subview3"> <ui:insert name="footer"> </ui:insert> </f:subview> </h:body> </html>

Apply the Facelet template to a Facelet page

The following sample shows how to apply a Facelet template to a Facelet page with the <ui:composition> tag:

<?xml version="1.0" encoding="UTF-8" ?>
<ui:composition xmlns="http://www.w3.org/1999/xhtml"
	xmlns:h="http://java.sun.com/jsf/html" template="/template.xhtml">
	<ui:define name="header">
		<ui:include src="header.xhtml"></ui:include>
	<ui:define name="bodyarea">
		<ui:include src="home_content.xhtml"></ui:include>
	<ui:define name="footer">
		<ui:include src="footer.xhtml"></ui:include>

Insert a document into a Facelet page with the include tag

Use the <ui:include> tag to insert a document into a Facelet page. Use the src attribute to specify the document to insert.

To migrate JavaServer Pages to Facelet technology, replace the <jsp:include> tags with <ui:include> tags as follows:

  • In JavaServer Pages:<jsp:include page="filePath">
  • In Facelet pages: <ui:include src="filePath">

Replace XML configurations with annotations

If you make no changes to the faces-config file, the artifacts registered in it will continue to work as before. However, you can replace the faces-config file with annotations. When both are available, the faces-config declarations take precedence over annotations at runtime.

Table 4. Replace XML artifacts with annotations
ArtifactIn faces-config.xmlWith annotations
Managed Beans, properties, and scopes

Valid scopes
 <managed-bean-name> user
  <property-name> messages
  <value> #{messages}
publicclass User {

	@ManagedProperty (value="#{message}")
	private Message message;

Faces validator
publicclass CustomValidator implements Validator{

	publicvoid validate(FacesContext arg0, UIComponent arg1, Object arg2)
			throws ValidatorException {


Faces converter
publicclass CustomConverter implements Converter {

	public Object getAsObject(FacesContext arg0, UIComponent arg1, String arg2)
			throws ConverterException {

	public String getAsString(FacesContext arg0, UIComponent arg1, Object arg2)
			throws ConverterException {

Faces components
publicclass CustomComponent extends UIComponent{

Note: Annotations for renderers (@FacesRenderer) and behaviors (@FacesBehavior) are supported as well.

Add Ajax support to a Facelet page

Ajax support, one of the major new features in JavaServer Faces 2.0, is provided by a built-in JavaScript resource library that is included as part of the JavaServer Faces core libraries. Add Ajax support to a Facelet page in two different ways:

  1. Use the <f:ajax> tag associated to a standard JavaServer Faces component. The following attributes implement an Ajax action:
  • render: ID or list of IDs of the components to redisplay in a page.
  • execute: ID or list of IDs of the components to send to the server to be processed.
  • event: The type of event to which the Ajax action will apply. If unspecified, the default event is used.
  • onevent: The JavaScript function to be executed when the event occurs.

In Listing 4, the Ajax call is added to the command button and is run after you click on it. The userName inputText is run on the server and the sayHelloMessage outputText is redisplayed.

Listing 4. Add the Ajax call to the command button
<h:inputText id="userName" styleClass="inputText"value="#{user.name}"></h:inputText>

<h:commandButton type="submit" value="Submit" id="button1" styleClass="commandButton">
	<f:ajax render="sayHelloMessage" execute="userName" ></f:ajax>

<h:outputText id="sayHelloMessage" styleClass="outputText"value="#{message.sayHello}"></h:outputText>
  1. Use the JavaScript API method jsf.ajax.request() that provides direct access to Ajax methods. To use the bundled JavaScript resource API Facelet page, identify the default JavaScript resource for the page using the <h:outputScript> tag. The jsf.ajax.request method takes up to three parameters that specify source, event, and options. Listing 5 shows how to implement Ajax support by using the jsf.ajax.request() method.
Listing 5. Implement Ajax support with the jsf.ajax.request() method
<h:outputScript name="jsf.js" library="javax.faces" target="head"/>
<h:inputText id="userName" styleClass="inputText" value="#{user.name}"/>
<h:commandButton type="submit" value="Submit" 
id="button1" styleClass="commandButton" onclick="jsf.ajax.request(this, event,
                        returnfalse;" />
<h:outputText id="sayHelloMessage"styleClass="outputText"></h:outputText>

Replace JavaServer Faces Widget Library (JWL) components

The JWL library is not supported on JavaServer Faces 2.0. It is a deprecated library.

Many third-party libraries for JavaServer Faces 2.0 can be used to replace JWL components. The details of migrating pages from JWL to another library depend on what library is used. In general, migrate components on a page one at a time, by finding a component in the new library that provides similar function to the JWL component.


To take advantage of annotations and Facelet technology, migrate existing JavaServer Faces 1.x applications to JavaServer Faces 2.0. Many JavaSever Faces third-party libraries offer a set of components and behaviors that can be used to enhanced an application.

Downloadable resources

Related topics


Sign in or register to add and subscribe to comments.

ArticleTitle=Migrate JavaServer Faces 1.x applications to JavaServer Faces 2.0