Mojarra 2.0.3 Release Notes
Migration Guide

Specification Version: 2.0
Implementation Version: 2.0.3

Migration from JSP to JSF 2.0 Facelets

First and foremost, a lot of new features in JSF 2.0 are only available when using Facelets, so we highly recommend that JSP/JSF applications are migrated. At a high level, the migration steps will look something like this:

Conversion of JSP tag libraries to Facelet tag libraries should be a relatively straight forward process. In cases where the JSP tag handler has more logic than what a standard component tag would typical have, more work will be involved.

To begin the conversion of a JSP tag library to a Facelets tag library, create the base document:

1    <?xml version="1.0" encoding="UTF-8" standalone="no"?>
2    <!--
3       COPYRIGHT
4    -->
5    
6    <facelet-taglib xmlns="http://java.sun.com/xml/ns/javaee"
7                    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
8                    xsi:schemaLocation="http://java.sun.com/xml/ns/javaee http://java.sun.com/xml/ns/javaee/web-facelettaglibary_2_0.xsd"
9                    version="2.0">
10   
11   </facelet-taglib>

Next, using the content of the <uri> element within the JSP tag library descriptor, insert a <namespace> element in the document we started in the step above:

1    <?xml version="1.0" encoding="UTF-8" standalone="no"?>
2    <!--
3       COPYRIGHT
4    -->
5    
6    <facelet-taglib xmlns="http://java.sun.com/xml/ns/javaee"
7                    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
8                    xsi:schemaLocation="http://java.sun.com/xml/ns/javaee http://java.sun.com/xml/ns/javaee/web-facelettaglibary_2_0.xsd"
9                    version="2.0">
10   
11       <namespace>[namespace value from 'uri' element in JSP descriptor]</namespace>
12   
13   </facelet-taglib>

Now the tag definitions from the JSP tag library can be added. For the sake of this example, let's assume that the JSP tag library provided one custom component, one custom converter, and one custom validator. Staring with the custom component:

1    <?xml version="1.0" encoding="UTF-8" standalone="no"?>
2    <!--
3       COPYRIGHT
4    -->
5    
6    <facelet-taglib xmlns="http://java.sun.com/xml/ns/javaee"
7                    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
8                    xsi:schemaLocation="http://java.sun.com/xml/ns/javaee http://java.sun.com/xml/ns/javaee/web-facelettaglibary_2_0.xsd"
9                    version="2.0">
10   
11       <namespace>[namespace value from 'uri' element in JSP descriptor]</namespace>
12   
13       <!-- Components -->
14   
15       <tag>
16           <tag-name>[name of the tag as defined by the 'name' element of the tag in the JSP tag library]</tag-name>
17           <component>
18               <component-type>[the component type]</component-type>
19               <renderer-type>[the renderer type of the component (if any)]</renderer-type>
21           </component>
22       </tag>
23   
24   </facelet-taglib>

That's all that needs to be done! No custom tag handler needs to be written, nor do any of the attributes that tag exposes need to be listed. The schema for this document type does allow the description of the tag attributes for documentation purposes, but the lack or presence of these attributes has no impact on the runtime.

Now, add the custom converter:

1    <?xml version="1.0" encoding="UTF-8" standalone="no"?>
2    <!--
3       COPYRIGHT
4    -->
5    
6    <facelet-taglib xmlns="http://java.sun.com/xml/ns/javaee"
7                    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
8                    xsi:schemaLocation="http://java.sun.com/xml/ns/javaee http://java.sun.com/xml/ns/javaee/web-facelettaglibary_2_0.xsd"
9                    version="2.0">
10   
11       <namespace>[namespace value from 'uri' element in JSP descriptor]</namespace>
12   
13       <!-- Components -->
14   
15       <tag>
16           <tag-name>[name of the tag as defined by the 'name' element of the tag in the JSP tag library]</tag-name>
17           <component>
18               <component-type>[the component type as defined in the faces-config.xml or @FacesComponent annotation]</component-type>
21               <renderer-type>[the renderer type of the component (if any)]</renderer-type>
23           </component>
24       </tag>
25   
26       <!-- Converters -->
27       <tag>
28           <tag-name>[name of the tag as defined by the 'name' element of the tag in the JSP tag library]</tag-name>
29           <converter>
30               <converter-id>[the ID of the converter as defined in the faces-config.xml or @FacesConverter annotation]</converter-id>
33           </converter>
34       </tag>
35   
36   </facelet-taglib>

And finally, the validator:

1    <?xml version="1.0" encoding="UTF-8" standalone="no"?>
2        <!--
3           COPYRIGHT
4        -->
5    
6    <facelet-taglib xmlns="http://java.sun.com/xml/ns/javaee"
7                    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
8                    xsi:schemaLocation="http://java.sun.com/xml/ns/javaee http://java.sun.com/xml/ns/javaee/web-facelettaglibary_2_0.xsd"
9                    version="2.0">
10   
11       <namespace>[namespace value from 'uri' element in JSP descriptor]
12       </namespace>
13   
14       <!-- Components -->
15   
16       <tag>
17           <tag-name>[name of the tag as defined by the 'name' element of the tag in the JSP tag library]</tag-name>
18           <component>
19               <component-type>[the component type as defined in the faces-config.xml or @FacesComponent annotation]</component-type>
20               <renderer-type>[the renderer type of the component (if any)]</renderer-type>
21           </component>
22       </tag>
23   
24       <!-- Converters -->
25       <tag>
26           <tag-name>[name of the tag as defined by the 'name' element of the tag
27               in the JSP tag library]
28           </tag-name>
29           <converter>
30               <converter-id>[the ID of the converter as defined in the faces-config.xml or @FacesConverter annotation]</converter-id>
31           </converter>
32       </tag>
33   
34       <!-- Validators -->
35       <tag>
36           <tag-name>[name of the tag as defined by the 'name' element of the tag in the JSP tag library]</tag-name>
37           <validator>
38               <validator-id>[the ID of the validator as defined in the faces-config.xml or @FacesValidator annotation]</validator-id>
39           </validator>
40       </tag>
41   
42   </facelet-taglib>

If custom handling is needed for a component, validator, or converter, it is possible to specify a the custom TagHandler by using the <handler-class> (a child element of the <tag> element). See the javadocs for javax.faces.view.facelets.ComponentHandler, javax.faces.view.facelets.ConverterHandler, and javax.faces.view.facelets.ValidatorHandler for details on what functionality these base classes provide.

If you have a JSP tag handler that doesn't represent a component, converter, or validator, then create a new class extending from javax.faces.view.facelets.TagHandler, implement the appropriate logic based on the API and the needs of the handler, and then register it like so:

1    <tag>
2        <tag-name>[name of the tag as defined by the 'name' element of the tag in the JSP tag library]</tag-name>
3        <handler-class>[fully qualified class name of the custom TagHandler implementation]</handler-class>
4    </tag>

Like JSP tag library descriptors, Facelet tag library descriptors, to be found, must be put in META-INF directory of your component library JAR. And like JSP, there is a naming scheme. The Facelet tag library descriptor must end with .taglib.xml (e.g., acmelibrary.taglib.xml). If you don't wish to include your taglib.xml within a JAR file, then the taglib.xml files must be included in your application and referenced via the context init parameter javax.faces.FACELETS_LIBRARIES. The value of this context init parameter is a semi-colon list of taglib.xml files relative to the docroot of the web application.

After the tag library has been converted, the next step will be migration from JSP pages to Facelet templates. As far as the tags references themselves are concerned, there is little to no difference in the usage between the two. There are some important differences between JSP and Facelets that should be called out.

A simple Facelet will look something like:

1    <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
2    <html xmlns="http://www.w3.org/1999/xhtml"
3          xmlns:ui="http://java.sun.com/jsf/facelets"
4          xmlns:h="http://java.sun.com/jsf/html">
5    
6        <body bgcolor="white">
7            <h2>My name is Duke.  What is yours?</h2>
8            <h:form id="helloForm" >
9                <h:graphicImage id="waveImg" url="/wave.med.gif" />
10               <h:inputText id="username"
11                       value="#{HelloBean.name}"/>
12               <h:commandButton id="submit" action="success" value="Submit"
13                           type="submit" />
14           </h:form>
15       </body>
16   </html>

Lines 8-14 represent JSF tags, while the rest of the page is template text. It's important to note that Facelet templates must be, at a minimum, valid XML.

Migration from Facelets 1.1.x to JSF 2.0 Facelets

In general Facelet 1.1.x applications should deploy and run as is in a JSF 2.0 runtime. There are some application configurations that do effect the behavior of the JSF 2.0 runtime.

If you use Facelets 1.1.x application extend or implement any com.sun.facelets classes, you will need to migrate to the standard API before removing the Facelets 1.1.x library. You cannot use the Facelets 1.1.x-based classes with the 2.0 Facelet implementation.

Differences in state saving that may impact Facelets-based applications (affected versions: Facelets 1.1.x and JSF 2.0 Facelets)

JSF 2.0, by default, will use a new state saving feature called Partial State Saving. Partial state saving reduces the amount of state that is saved for each view. Partial state saving, at a high level, works as follows:

In initial testing with client-side state saving, this new feature reduced view state from a sample view from 10K down to 2k. However, there are some use cases where using partial state saving may cause unexpected behavior:

In general, the rule of thumb for partial state saving is that the same view should be created on post-back as was what was created on the initial GET. If this can't be guaranteed, there are two options available to the developer:

Application configurations that impact annotation scanning