|
Mojarra 2.0
|
JSF Community
|
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.
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.
com.sun.facelets.FaceletViewHandler, the JSF 2.0 Facelets
implementation will be disabled.
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.
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:
javax.faces.PARTIAL_STATE_SAVING
with a value of false.
javax.faces.FULL_STATE_SAVING_VIEW_IDS.
The value of this parameter is a comma separated list of views that should
not use partial state saving (e.g., /dynamicView.xhmtl,/dynamicView2.xhtml).