Migrate JavaServer Faces 1.x applications to JavaServer Faces 2.0

To take advantage of the new capabilities in JavaServer Faces 2.0, you need to migrate your existing JavaServer Faces 1.x applications. This migration guide will help you do that. Learn about the new features and find a list of things to consider when migrating. See how you can use IBM Rational Application Developer to simplify the process.

Gloria Y. Torrealba (gloriay@mx1.ibm.com), Software Developer for IBM Rational Application Developer, IBM

Author1 photoGloria Torrealba has a Master's degree in Computer Science. She works as a software developer at IBM on the IBM Rational Application Developer product.



21 January 2014

Introduction

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"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="http://java.sun.com/xml/ns/javaee http://java.sun.com/xml/ns/javaee/web-app_3_0.xsd"
version="3.0">

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
<context-param>
		<param-name>javax.faces.DEFAULT_SUFFIX</param-name>
		<param-value>.xhtml</param-value>
</context-param>

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

<faces-config
xmlns="http://java.sun.com/xml/ns/javaee"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="http://java.sun.com/xml/ns/javaee http://java.sun.com/xml/ns/javaee/web-facesconfig_2_0.xsd"
version="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="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">
  • 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
<!DOCTYPE HTML>
<%@pagelanguage="java"contentType = "text/html;charset=ISO-8859-1"pageEncoding = "ISO-8859-1"%>
<%@taglib uri =    "http://java.sun.com/jsf/core" prefix="f"%>
<%@taglib uri = "http://java.sun.com/jsf/html" prefix="h"%>
<html>
 <head>
 <title>index</title>
 <meta http-equiv="Content-Type"  content="text/html; charset=ISO-8859-1">
 </head>
 <f:view>
	<body>
	   JavaServer Faces components …
	</body>
 </f:view>
</html>
<?xml version="1.0" encoding="UTF-8" ?>
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.1//EN"
"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>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:

ui:insert
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.
 
ui:composition
Wraps content to be included into another Facelet. The template attribute specifies the Facelet template to use.
 
ui:define
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
<!DOCTYPE HTML>
<%@page language="java" contentType= "text/html;charset=ISO-8859-1"
pageEncoding="ISO-8859-1"%>
<%@taglib uri = "http://java.sun.com/jsf/core" prefix="f"%>
<%@taglib uri = "http://tiles.apache.org/tags-tiles" prefix="tiles"%>

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

<f:view>
  <body>
   <f:subview id="subview1">
	<tiles:insertAttribute name="header" flush="false">
     </tiles:insertAttribute>
  </f:subview>
  <f:subview id="subview2">
     <tiles:insertAttribute   name="bodyarea" flush="false">
      </tiles:insertAttribute>
  </f:subview>
  <f:subview id="subview3">
	<tiles:insertAttribute name="footer" flush="false">
      </tiles:insertAttribute>
  </f:subview>
	</body>
 </f:view>
</html>
<?xml version="1.0" encoding="UTF-8" ?>
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.1//EN"
"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
<!DOCTYPE HTML>
<%-- 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"%>

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

<%--tpl:insert attribute="headarea"--%>
<title>template</title>
<%-- /tpl:insert --%>
</head>
<f:view>
 <body>
 <%--tpl:insert attribute="header"--%>   Default content of header
 <%--/tpl:insert--%>
 <%--tpl:insert attribute="bodyarea"--%> Default content of bodyarea
 <%--/tpl:insert--%>
 <%-- tpl:insert attribute="footer" --%> Default content of footer
 <%--/tpl:insert--%>
 </body>
</f:view>
</html>
<?xml version="1.0" encoding="UTF-8" ?>
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.1//EN"
"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:ui="http://java.sun.com/jsf/facelets"
	xmlns:f="http://java.sun.com/jsf/core"
	xmlns:h="http://java.sun.com/jsf/html" template="/template.xhtml">
	<ui:define name="header">
		<ui:include src="header.xhtml"></ui:include>
	</ui:define>
	<ui:define name="bodyarea">
		<ui:include src="home_content.xhtml"></ui:include>
	</ui:define>
	<ui:define name="footer">
		<ui:include src="footer.xhtml"></ui:include>
	</ui:define>
</ui:composition>

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>
 <managed-bean-name> user
 </managed-bean-name>
 <managed-bean-class>
  com.sample.User
 </managed-bean-class>
 <managed-bean-scope>
  session
 </managed-bean-scope>
 <managed-property>
  <property-name> messages
  </property-name>
  <value> #{messages}
  </value>
 </managed-property>
</managed-bean>
@ManagedBean(name="user")
@SessionScoped
publicclass User {

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

...
}
Faces validator
<validator>
 <validator-id>
  customValidator
 </validator-id>
 <validator-class>
com.sample.CustomValidator
 </validator-class>
</validator>
@FacesValidator("customValidator")
publicclass CustomValidator implements Validator{

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

	}

}
Faces converter
<converter>
 <converter-id>
  customConverter
 </converter-id>
 <converter-class>
com.sample.CustomConverter
 </converter-class>
</converter>
@FacesConverter("customConverter")
publicclass CustomConverter implements Converter {

	@Override
	public Object getAsObject(FacesContext arg0, UIComponent arg1, String arg2)
			throws ConverterException {
		
		..arg0.
	}

	@Override
	public String getAsString(FacesContext arg0, UIComponent arg1, Object arg2)
			throws ConverterException {
	
		...
	}

}
Faces components
<component>
 <component-type>
  customComponent
 </component-type>
 <component-class>
com.sample.CustomComponent
 </component-class>
</component>
@FacesComponent("customComponent")
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:commandButton>

<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,
                        {execute:'userName',render:'sayHellloMessage'});
                        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.

Conclusion

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.

Resources

Learn

Get products and technologies

Discuss

Comments

developerWorks: Sign in

Required fields are indicated with an asterisk (*).


Need an IBM ID?
Forgot your IBM ID?


Forgot your password?
Change your password

By clicking Submit, you agree to the developerWorks terms of use.

 


The first time you sign into developerWorks, a profile is created for you. Information in your profile (your name, country/region, and company name) is displayed to the public and will accompany any content you post, unless you opt to hide your company name. You may update your IBM account at any time.

All information submitted is secure.

Choose your display name



The first time you sign in to developerWorks, a profile is created for you, so you need to choose a display name. Your display name accompanies the content you post on developerWorks.

Please choose a display name between 3-31 characters. Your display name must be unique in the developerWorks community and should not be your email address for privacy reasons.

Required fields are indicated with an asterisk (*).

(Must be between 3 – 31 characters.)

By clicking Submit, you agree to the developerWorks terms of use.

 


All information submitted is secure.

Dig deeper into Rational software on developerWorks


static.content.url=http://www.ibm.com/developerworks/js/artrating/
SITE_ID=1
Zone=Rational
ArticleID=960582
ArticleTitle=Migrate JavaServer Faces 1.x applications to JavaServer Faces 2.0
publish-date=01212014