JSF Overview

JavaServer Faces (JSF) is the “official” component-based view technology in the Java EE web tier. JSF includes a set of predefined UI components, an event-driven programming model, and the ability to add third-party components. JSF is designed to be extensible, easy to use, and toolable. This refcard describes JSF 2.0.

Development Process

A developer specifies JSF components in JSF pages, combining JSF component tags with HTML and CSS for styling. Components are linked with managed beans—Java classes that contain presentation logic and connect to business logic and persistence backends.

In JSF 2.0, it is recommended that you use the facelets format for your pages:

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" 
  "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
<html xmlns="http://www.w3.org/1999/xhtml"
  xmlns:f="http://java.sun.com/jsf/core" 
  xmlns:h="http://java.sun.com/jsf/html"
  xmlns:ui="http://java.sun.com/jsf/facelets">
  <h:head>...</h:head>
  <h:body>
    <h:form>
    ...
    </h:form>
  </h:body>
</html>

These common tasks give you a crash course into using JSF.

Text field .

page.xhtml
<h:inputText value="#{bean1.luckyNumber}">
WEB-INF/classes/com/corejsf/SampleBean.java
@ManagedBean(name="bean1")
@SessionScoped
public class SampleBean {
   public int getLuckyNumber() { ... } 
   public void setLuckyNumber(int value) { ... }
   ...
}

Button .

page.xhtml
<h:commandButton value="press me" action="#{bean1.login}"/>
WEB-INF/classes/com/corejsf/SampleBean.java
@ManagedBean(name="bean1")
@SessionScoped
public class SampleBean {
   public String login() { if (...) return "success"; else return "error"; }
   ...
}

The outcomes success and error can be mapped to pages in faces-config.xml. If no mapping is specified, the page /success.xhtml or /error.xhtml is displayed.

Radio buttons

page.xhtml
<h:selectOneRadio value="#{form.condiment}>
  <f:selectItems value="#{form.items}"/>
</h:selectOneRadio>
WEB-INF/classes/com/corejsf/SampleBean.java
public class SampleBean {
  private static Map<String, Object> items;
  static {
    items = new LinkedHashMap<String, Object>();
    items.put("Cheese", 1); // label, value
    items.put("Pickle", 2);
    ...
  }
  public Map<String, Object> getItems() { return items; }
  public int getCondiment() { ... }
  public void setCondiment(int value) { ... }
  ...
}

Alternative 2.0

<h:selectOneRadio value="#{form.condiment}>
  <f:selectItems value="#{form.items}" 
   var="it"
   itemLabel="#{it.description}" 
   itemValue="#{it.productId}"/>
</h:selectOneRadio>

where the getItems method returns a collection or array of objects with getDescription/getProductId methods

Validation and Conversion

Using the Bean Validation Framework (JSR 303) 2.0

public class SampleBean {
  @Max(1000) private BigDecimal amount;
}

Page-level validation and conversion:

<h:inputText value="#{bean1.amount}" required="true">
  <f:validateDoubleRange maximum="1000"/>
</h:inputText>

<h:outputText value="#{bean1.amount}">
  <f:convertNumber type="currency"/>      
</h:outputText>

The number is displayed with currency symbol and group separator: $1,000.00

Error Messages 

<h:outputText value="Amount"/>
<h:inputText id="amount" label="Amount" value="#{payment.amount}"/>
<h:message for="amount"/>

Resources and Styles

page.xhtml
<h:outputStylesheet library="css" name="styles.css" target="head"/>
 ...
<h:outputText value="#{msgs.goodbye}!" styleClass="greeting">
faces-config.xml
<application>
  <resource-bundle>
    <base-name>com.corejsf.messages</base-name>
    <var>msgs</var>
  </resource-bundle>
</application>
WEB-INF/classes/com/corejsf/messages.properties
goodbye=Goodbye
WEB-INF/classes/com/corejsf/messages_de.properties
goodbye=Auf Wiedersehen
resources/css/styles.css
.greeting {
  font-style: italic;
  font-size: 1.5em;
  color: #eee;
}

Table with links

page.xhtml
<h:dataTable value="#{bean1.entries}" var="row" styleClass="table" rowClasses="even,odd">
  <h:column>
    <f:facet name="header">
      <h:outputText value="Name"/>
    </f:facet>
    <h:outputText value="#{row.name}"/>
  </h:column>
  <h:column>
    <h:commandLink value="Delete" action="#{bean1.deleteAction}" immediate="true">
      <f:setPropertyActionListener target="#{bean1.idToDelete}"
        value="#{row.id}"/>
    </h:commandLink>
  </h:column>
</h:dataTable>
WEB-INF/classes/com/corejsf/SampleBean.java
public class SampleBean {
   private int idToDelete; 
   public void setIdToDelete(int value) { idToDelete = value; }
   public String deleteAction() {
      // delete the entry whose id is idToDelete
      return null;
   }
   public List<Entry> getEntries() { ... }
   ...
}

AJAX 2.0

<h:commandButton value="Update">
  <f:ajax execute="input1 input2" render="output1"/>
</h:commandButton>

When the button is clicked, run the lifecycle's “execute” phase on the components with IDs input1 input2 and the “render” phase on the component with ID output1.

The AJAX actions are triggered by onclick events for buttons and links, onchange events for input fields and selection lists.

Lifecycle

faces-config.xml

The faces-config.xml file contains a sequence of the following entries. When indicated, annotations can be used instead.

The JSF Expression Language (EL)

An EL expression is a sequence of literal strings and expressions of the form base[expr1][expr2]... As in JavaScript, you can write base.identifier instead of base['identifier'] or base["identifier"]. The base is one of the names in the table below or a name defined in faces-config.xml.

header A Map of HTTP header parameters, containing only the first value for each name.
headerValues A Map of HTTP header parameters, yielding a String[] array of all values for a given name.
param A Map of HTTP request parameters, containing only the first value for each name.
paramValues A Map of HTTP request parameters, yielding a String[] array of all values for a given name.
cookie A Map of the cookie names and values of the current request.
initParam A Map of the initialization parameters of this web application.
requestScope, sessionScope, applicationScope, viewScope 2.0 A Map of all attributes in the given scope.
facesContext The FacesContext instance of this request.
view The UIViewRoot instance of this request.
component 2.0 The current component
cc 2.0 The current composite component
resource 2.0 Use resource['library:name'] to access a resource

In JSF, EL expressions are enclosed in #{...} to indicate deferred evaluation. The expression is stored as a string and evaluated when needed. In contrast, JSP uses immediate evaluation, indicated by ${...} delimiters.

2.0: EL expressions can contain JSTL functions

fn:contains(str, substr)
fn:containsIgnoreCase(str, substr)
fn:startsWith(str, substr)
fn:endsWith(str, substr)
fn:length(str)
fn:indexOf(str)
fn:join(strArray, separator)
fn:split(str, separator)
fn:substring(str, start, pastEnd)
fn:substringAfter(str, separator)
fn:substringBefore(str, separator)
fn:replace(str, substr, replacement)
fn:toLowerCase(str)
fn:toUpperCase(str)
fn:trim()
fn:escapeXml()

JSF Core Tags

Tag Description/ Attributes
f:facet Adds a facet to a component
name the name of this facet
f:attribute Adds an attribute to a component
name, value the name and value of the attribute to set
f:param Constructs a parameter child component
name An optional name for this parameter component.
value The value stored in this component.
f:actionListener

f:valueChangeListener

Adds an action listener or value change listener to a component
type The name of the listener class
f:setPropertyChangeListener 1.2 Adds an action listener to a component that sets a bean property to a given value.
target The bean property to set when the action event occurs
value The value to set it to
f:phaseListener 1.2 Adds a phase listener to this page.
type The name of the listener class
f:event 2.0 Adds a system event listener to a component
name One of preRenderComponent, postAddToView, preValidate, postValidate
listener A method expression of the type void (ComponentSystemEvent) throws AbortProcessingException
f:converter Adds an arbitrary converter to a component
converterId The ID of the converter
f:convertDateTime Adds a datetime converter to a component
type date (default), time, or both
dateStyle, timeStyle default, short, medium, long, or full
pattern Formatting pattern, as defined in java.text.SimpleDateFormat
locale Locale whose preferences are to be used for parsing and formatting
timeZone Time zone to use for parsing and formatting (Default: UTC)
f:convertNumber Adds a number converter to a component
type number (default), currency , or percent
pattern Formatting pattern, as defined in java.text.DecimalFormat
minIntegerDigits, maxIntegerDigits, minFractionDigits, maxFractionDigits Minimum, maximum number of digits in the integer and fractional part
integerOnly True if only the integer part is parsed (default: false)
groupingUsed True if grouping separators are used (default: true)
locale Locale whose preferences are to be used for parsing and formatting
currencyCode ISO 4217 currency code to use when converting currency values
currencySymbol Currency symbol to use when converting currency values
f:validator Adds a validator to a component
validatorId The ID of the validator
f:validateDoubleRange, f:validateLongRange, f:validateLength Validates a double or long value, or the length of a string
minimum, maximum the minimum and maximum of the valid range

f:validateRequired 2.0 Sets the required attribute of the enclosing component
f:validateBean 2.0 Specify validation groups for the Bean Validation Framework (JSR 303)
f:loadBundle Loads a resource bundle, stores properties as a Map
basename The resource bundle name
value The name of the variable that is bound to the bundle map
f:selectitem Specifies an item for a select one or select many component
binding, id Basic attributes
itemDescription Description used by tools only
itemDisabled false (default) to show the value
itemLabel Text shown by the item
itemValue Item’s value, which is passed to the server as a request parameter
value Value expression that points to a SelectItem instance
escape true (default) if special characters should be converted to HTML entities
noSelectionOption 2.0 true if this item is the “no selection option”
f:selectitems Specifies items for a select one or select many component
value Value expression that points to a SelectItem, an array or Collection, or a Map mapping labels to values.
var 2.0 Variable name used in value expressions when traversing an array or collection of non-SelectItem elements
itemLabel 2.0, itemValue 2.0, itemDescription 2.0, itemDisabled 2.0, itemLabelEscaped 2.0 Item label, value, description, disabled and escaped flags for each item in an array or collection of non-SelectItem elements. Use the variable name defined in var.
noSelectionOption 2.0 Value expression that yields the “no selection option” item or string that equals the value of the “no selection option” item
f:ajax 2.0 Enables Ajax behavior
execute, render Lists of component IDs for processing in the “execute” and “render” lifecycle phases
event JavaScript event that triggers behavior. Default: click for buttons and links, change for input components
immediate If true, generated events are broadcast during “Apply Request Values” phase instead of “Invoke Application”
listener Method binding of type void (AjaxBehaviorEvent)
onevent, onerror JavaScript handlers for events/errors
f:viewParam 2.0 Defines a “view parameter” that can be initialized with a request parameter
f:metadata 2.0 Holds view parameters. May hold other metadata in the future
f:view, f:subview, f:verbatim Not needed with facelets

JSF HTML Tags

Tag Description
h:head 2.0,h:body2.0, h:form HTML head, body, form
h:outputStylesheet 2.0, h:outputScript 2.0 Produces a style sheet or script
h:inputText Single-line text input control. .
h:inputTextArea Multiline text input control. .
h:inputSecret Password input control. .
h:inputHidden Hidden field
h:outputLabel Label for another component for accessibility
h:outputLink HTML anchor. .
h:outputFormat Like outputText, but formats compound messages
h:outputText Single-line text output.
h:commandButton, h:button 2.0 Button: submit, reset, or pushbutton. .
h:commandLink, h:link 2.0 Link that acts like a pushbutton. .
h:message Displays the most recent message for a component

h:messages Displays all messages
h:grapicImage Displays an image. .
h:selectOneListbox Single-select listbox. .
h:selectOneMenu Single-select menu. .
h:selectOneRadio Set of radio buttons. .
h:selectBooleanCheckbox Checkbox. .
h:selectManyCheckbox Set of checkboxes. .
h:selectManyListbox Multiselect listbox. .
h:selectManyMenu Multiselect menu. .
h:panelGrid HTML table
h:panelGroup Two or more components that are laid out as one
h:dataTable A feature-rich table component
h:column Column in a data table

Basic Attributes

Attribute Description
id Identifier for a component
binding Reference to the component that can be used in a backing bean
rendered A boolean; false suppresses rendering
value A component’s value, typically a value binding
validator A method expression of the type void (FacesContext, UIComponent, Object)
valueChangeListener A method expression of the type void (ValueChangeEvent)
converter Converter class name
required A boolean; if true, requires a value to be entered in the associated field

Attributes for h:body and h:form

Attribute Description
binding, id, rendered Basic attributes
dir, lang, style, styleClass, target, title

h:form only: accept, acceptcharset, enctype

 HTML 4.0 attributes (acceptcharset corresponds to HTML accept-charset, styleClass corresponds to HTML class)
onclick, ondblclick, onkeydown, onkeypress, onkeyup, onmousedown, onmousemove, onmouseout, onmouseover

h:body only: onload, onunload

h:form only: onblur, onchange, onfocus, onreset, onsubmit

 DHTML events

Attributes for h:inputText, h:inputSecret, h:inputTextarea, and h:inputHidden .

Attribute Description
cols For h:inputTextarea only—number of columns
immediate Process validation early in the life cycle
redisplay For h:inputSecret only—when true, the input field’s value is redisplayed when the web page is reloaded
required Require input in the component when the form is submitted
rows For h:inputTextarea only—number of rows
binding, converter, id, rendered, required, value, validator, valueChangeListener Basic attributes
accesskey, alt, dir, disabled, lang, maxlength, readonly, size, style, styleClass, tabindex, title HTML 4.0 pass-through attributes—alt, maxlength, and size do not apply to h:inputTextarea. None apply to h:inputHidden.
onblur, onchange, onclick, ondblclick, onfocus, onkeydown, onkeypress, onkeyup, onmousedown, onmousemove, onmouseout, onmouseover, onselect DHTML events. None apply to h:inputHidden.

Attributes for h:outputText and h:outputFormat

Attribute Description
escape If set to true, escapes <, >, and & characters. Default value is true.
binding, converter, id, rendered, styleClass, value Basic attributes
style, title HTML 4.0

Attributes for h:outputLabel

Attribute Description
for The ID of the component to be labeled.
binding, converter, id, rendered, value Basic attributes

Attributes for h:graphicImage .

Attribute Description
library 2.0, name 2.0 The resource library (subdirectory of resources) and file name (in that subdirectory)
binding, id, rendered, value Basic attributes
alt, dir, height, ismap, lang, longdesc, style, styleClass, title, url, usemap, width HTML 4.0
onblur, onchange, onclick, ondblclick, onfocus, onkeydown, onkeypress, onkeyup, onmousedown, onmousemove, onmouseout, onmouseover, onmouseup DHTML events

Attributes for h:commandButton, h:commandLink, h:button, and h:link .

Attribute Description
action (command tags) Navigation outcome string or method expression of type String ()
outcome 2.0 (non-command tags) Value expression yielding the navigation outcome
fragment 2.0 (non-command tags) Fragment to be appended to URL. Don't include the # separator.
actionListener Method expression of type void (ActionEvent)
charset For h:commandLink only—The character encoding of the linked reference  
image (button tags) For h:commandButton only—A context-relative path to an image displayed in a button. If you specify this attribute, the HTML input’s type will be image.
immediate A boolean. If false (the default), actions and action listeners are invoked at the end of the request life cycle; if true, actions and action listeners are invoked at the beginning of the life cycle.
type For h:commandButton: The type of the generated input element: button, submit, or reset. The default, unless you specify the image attribute, is submit. For h:commandLink and h:link: The content type of the linked resource; for example, text/html, image/gif, or audio/basic
value The label displayed by the button or link
binding, id, rendered Basic attributes
accesskey, dir, disabled (h:commandButton only), lang, readonly, style, styleClass, tabindex, title

link tags only: charset, coords, hreflang, rel, rev, shape, target

 HTML 4.0
onblur, onclick, ondblclick, onfocus, onkeydown, onkeypress, onkeyup, onmousedown, onmousemove, onmouseout, onmouseover, onmouseup DHTML events

Attributes for h:outputLink .

Attribute Description
accesskey, binding, converter, id, lang, rendered, value Basic attributes
charset, coords, dir, hreflang, lang, rel, rev, shape, style, styleClass, tabindex, target, title, type HTML 4.0
onblur, onchange, onclick, ondblclick, onfocus, onkeydown, onkeypress, onkeyup, onmousedown, onmousemove, onmouseout, onmouseover, onmouseup DHTML events

Attributes for h:selectBooleanCheckbox, h:selectManyCheckbox, h:selectOneRadio, h:selectOneListbox, h:selectManyListbox, h:selectOneMenu, h:selectManyMenu .

Attribute Description
enabledClass, disabledClass CSS class for enabled/disabled elements—h:selectOneRadio and h:selectManyCheckbox only
selectedClass 2.0, unselectedClass 2.0 CSS class for selected/unselected elements—h:selectManyCheckbox only
layout Specification for how elements are laid out: lineDirection (horizontal) or pageDirection (vertical)—h:selectOneRadio and h:selectManyCheckbox only
collectionType 2.0

selectMany tags only: the name of a collection class such as java.util.TreeSet
hideNoSelectionOption 2.0 Hide item marked as “no selection option”
binding, converter, id, immediate, required, rendered, validator, value, valueChangeListener Basic attributes
accesskey, border, dir, disabled, lang, readonly, style, styleClass, size, tabindex, title HTML 4.0—border only for h:selectOneRadio and h:selectManyCheckbox, size only for h:selectOneListbox and h:selectManyListbox.
onblur, onchange, onclick, ondblclick, onfocus, onkeydown, onkeypress, onkeyup, onmousedown, onmousemove, onmouseout, onmouseover, onmouseup, onselect DHTML events

Attributes for h:message and h:messages

Attribute Description
for The ID of the component whose message is displayed—applicable only to h:message
errorClass, fatalClass, infoClass, warnClass CSS class applied to error/fatal/information/warning messages
errorStyle, fatalStyle, infoStyle, warnStyle CSS style applied to error/fatal/information/warning messages
globalOnly Instruction to display only global messages—h:messages only. Default: false
layout Specification for message layout: table or list—h:messages only
showDetail A boolean that determines whether message details are shown. Defaults are false for h:messages, true for h:message.
showSummary A boolean that determines whether message summaries are shown. Defaults are true for h:messages, false for h:message.
tooltip A boolean that determines whether message details are rendered in a tooltip; the tooltip is only rendered if showDetail and showSummary are true
binding, id, rendered Basic attributes
style, styleClass, title HTML 4.0

Attributes for h:panelGrid

Attribute Description
bgcolor Background color for the table
border Width of the table’s border
cellpadding Padding around table cells
cellspacing Spacing between table cells
columns Number of columns in the table
frame frame Specification for sides of the frame surrounding the table that are to be drawn; valid values: none, above, below, hsides, vsides, lhs, rhs, box, border
headerClass, footerClass CSS class for the table header/footer
rowClasses, columnClasses Comma-separated list of CSS classes for rows/columns
rules Specification for lines drawn between cells; valid values: groups, rows, columns, all
summary Summary of the table’s purpose and structure used for non-visual feedback such as speech
binding, id, rendered, value Basic attributes
dir, lang, style, styleClass, title, width HTML 4.0
onclick, ondblclick, onkeydown, onkeypress, onkeyup, onmousedown, onmousemove, onmouseout, onmouseover, onmouseup DHTML events

Attributes for h:panelGroup

Attribute Description
binding, id, rendered Basic attributes
style, styleClass HTML 4.0

Attributes for h:dataTable

Attribute Description
bgcolor Background color for the table
border width of the table's border
cellpadding Padding around table cells
cellspacing Spacing between table cells
first index of the first row shown in the table
frame Specification for sides of the frame surrounding the table should be drawn; valid values: none, above, below, hsides, vsides, lhs, rhs, box, border
headerClass, footerClass CSS class for the table header/footer
rowClasses, columnClasses comma-separated list of CSS classes for rows/columns
rules Specification for lines drawn between cells; valid values: groups, rows, columns, all
summary summary of the table's purpose and structure used for non-visual feedback such as speech
var The name of the variable created by the data table that represents the current item in the value
binding, id, rendered, value Basic attributes
dir, lang, style, styleClass, title, width HTML 4.0
onclick, ondblclick, onkeydown, onkeypress, onkeyup, onmousedown, onmousemove, onmouseout, onmouseover, onmouseup DHTML events

Attributes for h:column

Attribute Description
headerClass 1.2, footerClass 1.2 CSS class for the column's header/footer
binding, id, rendered Basic attributes

Facelets Tags 2.0

Tag Description
ui:define Give a name to content for use in a template
name the name of the content
ui:insert If a name is given, insert named content if defined or use the child elements otherwise. If no name is given, insert the content of the tag invoking the template.
name the name of the content
ui:composition Produces content from a template after processing child elements (typically ui:define tags) Everything outside the ui:composition tag is ignored.
template The template file, relative to the current page
ui:component Like ui:composition, but makes a JSF component
binding, id Basic attributes
ui:decorate, ui:fragment Like ui:composition, ui:component, but does not ignore the content outside the tag
ui:include Include plain XHTML, or a file with a ui:composition or ui:component tag
src The file to include, relative to the current page
ui:param Define a parameter to be used in an included file or template
name Parameter name
value A value expression (can yield an arbitrary object)
ui:repeat Repeats the enclosed elements.
value A List, array, ResultSet, or object
offset, step, size starting index, step size, ending index of the iteration
var Variable name to access the current element
varStatus Variable name to access the iteration status, with integer properties begin, end, index, step and Boolean properties even, odd, first, last
ui:debug Shows debug info when CTRL+SHIFT+a key is pressed
hotkey the key to press (default d)
rendered true (default) to activate
ui:remove Do not include the contents (useful for comments or temporarily deactivating a part of a page)

About the Author

Cay S. Horstmann has written many books on C++, Java and object-oriented development, is the series editor for Core Books at Prentice-Hall and a frequent speaker at computer industry conferences. For four years, Cay was VP and CTO of an Internet startup that went from 3 people in a tiny office to a public company. He is now a computer science professor at San Jose State University. He was elected Java Champion in 2005.

Recommended Book

Core JavaServer Faces is the Sun Microsystems book on the JavaServer Faces technology. Authors David Geary and Cay Horstmann delve into all facets of JSF development, offering systematic best practices for building robust applications and maximizing developer productivity. Drawing on unsurpassed insider knowledge of the Java platform, they present solutions, hints, tips, and "how-tos" for writing superior JSF production code, without requiring prior knowledge of JSF, JSP, or servlets.