A Practical Introduction into Java Enterprise Edition 6 (with Sample Application)
August 2, 2009 · Robert Söding


While in the past Java Enterprise Edition had a reputation of being overly complex (while being rock-stable), developers' productivity has greatly improved with Java EE 6 (and EE 5, before). Even Rod Johnson, founder of the - much more agile - Spring Framework, came out in support of Java EE 6, remarking that "Java EE 6 gets it right".
This article introduces into Java EE 6, discussing basic and new (and really cool) features of EJB (Enterprise Java Beans) 3.1, JPA (Java Persistence API) 2.0, and JSF (JavaServer Faces) 2.0 from a mostly practical and only partially didactical ("things to remember") perspective.
The associated sample application should - hopefully - work out-of-the-box for anyone importing it.
Studying the article and application is recommended for developers with basic or intermediate skills in the technologies covered.
Feedback is welcome and may be directed to .


Java Version

The sample application has been developed using Sun Java 1.6.

Installing Java EE 6 and the GlassFish Server

Download GlassFish and Java EE 6 and follow the corresponding steps.
Both versions offered at that site, Java EE 6 SDK Preview and Java EE 6 Web Profile SDK Preview, should do for the sample application, however, the former contains more features, in general.
When installing, keep a note of GlassFish's installation path, as well notice the administrator user name / password combination. This information is needed in the step described in chapter Adding the GlassFish Server Adapter.

Preparing Eclipse

The sample application has been developed using the Eclipse IDE for Java EE Developers, version 3.5.
Eclipse WTP (Web Tools Platform) provides several means to support developing the presentation-side code of JSF (JavaServer Faces). However, these features appear to be specifically bound to JSF 1.1 and 1.2.
Most fortunately, however, this article's sample application does provide the JSF 2.0 tag libraries (even when the JSF 2.0 distribution still ships the 1.2 taglibs). See chapter Facelet Tags Do Not Have a Tag Library (TLD) Anymore for more information.
Also see the current status of the Eclipse JSF Facelets Tools Project. See the page Eclipse Web Tools Platform 3.0 - New and Noteworthy for IDE features related to other JSF versions.

Adding the GlassFish Server Adapter

At the time of writing, Sun's GlassFish server probably is the only application server supporting Java EE 6 out-of-the-box.
To add the GlassFish Server Adapter to the Eclipse IDE, normally, one would complete the following steps:
However, there is a common bug (with this GlassFish version - using Eclipse 3.4 as well as 3.5), telling, "An error occurred while collecting items to be installed" (the error message is included to be potentially indexed by search engines).
As a workaround, one can install the server adapter as follows:
The following image displays the corresponding dialog:
Adding the GlassFish Server Adapter
After having installed GlassFish via jMaki plugin, set up a server adaptor in Eclipse by completing the following steps:

Adding the Maven m2eclipse Plugin

Maven is a Java project management and build tool, including management of dependant libraries. The m2eclipse plugin provides graphical support for the Eclipse IDE.
Add Maven Integration for Eclipse (in Eclipse 3.5, click the menu Help --> Install New Software, and add a new update site).
There is a bug with the Maven plugin that removes Eclipse's virtual Web Resources folder from web projects. Thus, firstly, do not necessarily install the plugin into your production copy of Eclipse, and secondly, please find the project's web root as indicated in the image below:
Web Root

Downloading and Importing the Sample Project

Download and unzip the project.
In Eclipse, click File --> Import --> Maven Projects and select the folder created when unzipping.

Running the Application

Start the Derby database by typing ...
sh $GLASSFISH_HOME/bin/asadmin start-database
... in a shell (asadmin.bat on Windows). $GLASSFISH_HOME should be replaced by GlassFish's actual install path.
In Eclipse, right-click the project's root node and select Run As --> Run on Server. Choose the GlassFish server previously set up or follow the Eclipse wizard to set it up.
Point your browser to (by default) http://localhost:8080/pizza-store-jee6.
A customer test account has been pre-configured with a user name / password combination of customer / password.

Use Cases in the Sample Application

There are two user roles in the sample application, customer and vendor.

Customer Use Cases

A customer can perform actions that are described in the following sections.

Common Use Cases

The following screenshot displays a region that is included in almost any page:
Common Options
A customer can ...

Use Cases at the Pizzas Page

The following screenshot displays the Pizzas page:
Pizzas Page
At the Pizzas page, a customer can ...

Use Cases at the Pizza Ingredients Page

The following screenshot displays the Pizza Ingredients page:
Pizza Ingredients Page
At the Pizza Ingredients page, a customer can ...

Use Cases at the Edit Account Page

The following screenshot displays the Edit Account page:
Edit Account Page
At the Edit Account page, depending on her login status, a customer can either create a new account or edit an existing one. There, a customer can ...

Vendor Use Cases

When a customer places an order, the vendor will receive a notification via the vendor's web service endpoint.

Data Access Layer

The application currently uses Apache Derby as DBMS (Database Management System) as it ships with the GlassFish application server by default. It has also been tested with PostgreSQL 8.3, and should work with any other common DBMS, out-of-the-box.
To start the Derby database, in a shell, type:
$GLASSFISH_HOME/bin/asadmin start-database
$GLASSFISH_HOME should be replaced by the installation path of the GlassFish distribution.
The data access layer defined by the Java EE 6 specification is the Java Persistence API 2.0 (JPA), where entities - plain old Java objects (POJOS) - are mapped to the relational database tables. This kind of mapping is usually referred to as Object Relation Mapping (in short, ORM or O/RM).
Basically, these entities have getter and setter methods that each correspond to a database table column or relation (a foreign key).
Mappings can be configured either in XML files (i.e., in persistence.xml) or inline, by Java annotations. - In the sample application, annotations are used.
This article does not provide a conceptual or even didactical view on Java EE 6' data access technologies. It is rather meant to help the reader understand the usage of Java EE 6 technologies in the sample application's context.

Data Source Setup

In the /META-INF/persistence.xml file, the database connection is defined.
It points to a data source with the JNDI name "jdbc/__default". This is a pre-configured data source pointing to an Apache Derby DBMS that ships with the GlassFish server. Additional data sources can be set up within the GlassFish administrative console (http://localhost:4848 by default), in the section JDBC.
The database used by the sample application gets created on application startup, and dropped on shutdown (search for "create" and "drop" in the persistence.xml file). The custom DatabaseInitializer class is used to populate the database with sample data.


The entities (AKA domain or model objects) used in the sample application are located in the model and model.base Java packages.
The following class diagram shows their structure:
Entities Class Diagram
A Login represents a user name / password combination, and it has-an associated Customer.
The Login, in this case, also has a repeatedPassord and a loggedIn property. These are not persisted to the database (as indicated by a @Transient annotation, see chapter Annotations Related to Java Persistence). They are solely used for business flow logic. - In another strategy, it might be regarded cleaner (more cohesive) to use a wrapper on the Login class that separates these concerns.
There is another issue of potential bad design: The Login object is of a more common type than the Customer it refers to. I.e., as the application evolves, it could get a Vendor, Administrator, etc. Thus, the design would be more extensible when the Customer would refer to the Login instead.
A Customer has-a name and an Adress. In this case, the Customer is supposed to have one address only, so the Address can be embedded (see @Embedded in chapter Annotations Related to Java Persistence) into the Customer's database table.
Again, it would be more extensible to define an address in its own table.
An Adress has a number of well-known properties.
A Pizza has a name and a price, and consists of a number of Ingredients, which have a name.
The formattedPrice property, BTW, is at the client-side layer by now ;-).
Not shown in the class diagram (and not related to the database) is the PizzaLineItem wrapper, that, additionally, has a quantity, and user-configurable, optional and additional, Ingredients list.
All entities have an id and name property. Thus, they derive from the AbstractIdentifyable and AbstractNameable types in the model.base package. See chapter Generic Data Access Objects for information on the intention of that pattern.

Annotations Used in the Model Layer

There are two types of annotations used on the entities: Annotations related to Java Persistence (JPA) (in the javax.persistence namespace) and annotations related to the Bean Validation Framework (in the javax.validation.constraints namespace).

Annotations Related to Java Persistence

These annotations map the entities and their properties to database tables, fields, relations (i.e., foreign keys) and other objects (i.e., indexes).
See chapter 11, Metadata for Object/Relational Mapping, of the JPA 2.0 Specification for a reference. You might also want to read chapter Hibernate Mappings of my previously written article A Comprehensive Introduction into the Spring Framework (with Sample Application) (discussing XML-based mapping configuration). (The Hibernate framework has been incorporated into JPA 2.0 to a large degree.)
First-off, every entity needs to be annotated with @Entity, at the type level. By default, the corresponding table name equals the type name. This can be changed by using the @Entity's name attribute, or by adding a @Table annotation.
By default, any Java property is mapped to a database table field. The field name equals the Java property name. Using the @Column annotation on a Java property, additional definitions can be set, including the database column name, nullability, or a unique constraint. Properties annotated with @Transient are not mapped to database columns.
Every entity needs to have a property annotated with @Id, which maps to a table's primary key. Primary keys in databases are usually auto-incremented, which is expressed by the @GeneratedValue annotation on the corresponding property.
Entities that do not map to their own database table (and also are not annotated with @Entity) may be @Embeddable into other entities (and, in consequence, into the latters' corresponding tables), which, in turn, do embed their dependencies by annotating the corresponding property with @Embedded.
There are one-to-one, one-to-many, many-to-many and many-to-one relationships, most of them referring to Java Collections. In the sample application, a @OneToMany relation ist used.
See chapter Relations for more general information.

Annotations Related to the Bean Validation Framework

This article's author's knowledge of Bean Validation currently is shallow, so information on the usage of this framework may be somewhat inaccurate in portions. See JSR 303: Bean Validation for the specification.
The sample application uses Bean Validation annotations, along with a JSF BeanValidator and the corresponding tag f:validateBean to validate HTML form field values against the constraints of a targeted backing bean.
Bean Validation annotations used in the sample application include @NotNull (which is pretty useless in the context of JSF form field validation), @Pattern (i.e., @Pattern(regexp = "[\\w-]+@([\\w-]+\\.)+[\\w-]+") for validating an email address) (there would be an alternative, corresponding, JSF tag, f:validateRegex), and @Size (i.e. @Size(min = 5, max = 255)) (there would be an alternative, corresponding, JSF tag, f:validateLength).
Note that Bean Validation constraints do not get applied, automatically, i.e., when using JPA to persist an entity. The Validation API needs to be invoked, explicitely.

Data Access Objects

Data Access Objects (DAOs) are used to retrieve, persist, or delete, entities.
In the sample application, related classes are organized into Java interfaces (in the packages dao.interfaces and dao.interfaces.base) and (JPA) implementations (in package dao.impl.jpa and dao.impl.jpa.base).
Referring to the DAO layer via interfaces instead of concrete implementations makes sense for the purpose of interchanging the data access layer. In contrast, the entities themselves are not guarded by interfaces in the sample application: Semantically, they do act as interfaces, theirselves: They do not have inline code, and if their definition should change, their (potential) interfaces would need to change, too.
The DAOs in the sample application are exposed as EJBs. See chapter Enterprise JavaBeans (EJBs) for information on that aspect.

Generic Data Access Objects

This section is not specifically related to the Java Persistence API (JPA), but to OR/M, in general.
Most common data access operations - retrieving, inserting, updating and deleting instances - are based on the entities' id or name property, solely, - or (find all) even based on no property at all.
Of course, there are more complex cases, when the search criteria comprise of other properties - potentially of other, related, JOINed, entities. Nevertheless, there is a number of common operations that apply to any entity. The following code snippet shows a DAO base class:
public class GenericAbstractIdentifiableDaoImpl<T extends AbstractIdentifiable>
                implements GenericAbstractIdentifiableDAO<T> {
        protected EntityManager entityManager;

        protected Class<T> tClass;

        public GenericAbstractIdentifiableDaoImpl(Class<T> clazz) {
                tClass = clazz;

        public void remove(T entity) {

        public T get(long id) {
                return entityManager.find(tClass, id);

        public T save(T entity) {
                return entityManager.merge(entity);

        public List<T> getAll() {
                return (List<T>) entityManager.createQuery(
                        "select x from " + tClass.getSimpleName() + " x")
The above class handles common data access operations for all entities that inherit from AbstractIdentifyable (which has no more than an id property).
Obviously, this pattern is not directly related to Java EE, but to data access, in general.
In the method annotated with @SuppressWarnings("unchecked"), normally, we would use the overloaded, generic, version of the EntityManager.createQuery(.., Class<T>) method. At runtime, however, when the javax.persistence-XXX.jar is used that GlassFish provides, a NoSuchMethod exception will be thrown (with the author's current version), indicating that the API is not stable yet.

Data Access APIs

The data access APIs - as used in the sample application - are pretty simple.
For a code sample, please refer to the previous chapter Generic Data Access Objects.
First-off, a JPA EntityManager gets injected by the Java EE container:
protected EntityManager entityManager;
The EntityManager provides several methods, including find(..), remove(..), merge(..) and createQuery(..). With the createQuery(..) method, the PQL (Persistence Query Language) is used, which is quite similar to SQL.
For more information, see chapter 3.8, Query API, chapter 4, Query Language and chapter 6, Criteria API (where the latter is, BTW, overly complex compared to other data access frameworks) of the JPA 2.0 specification.

Service Layer

Any business logic that - finally - relates the data model to the (user interface) views may be regarded a Service Layer module.
JSF managed beans, however, contain both business logic and logic for controlling views' task flow. In more complex applications, they would rather be assigned to the presentation layer.

Enterprise JavaBeans (EJBs)

In the sample application, the Data Access Objects (DAOs) (in the package dao.impl.jpa), along with their interfaces (in the package dao.interfaces) are exposed as stateless EJBs (Enterprise JavaBeans).
This article only covers EJB features used in the sample application. For more information, see an overview from the specification lead, chapter Enterprise Beans in The Java EE 6 Tutorial, and the EJB 3.1 specification.
Development before version 3.0 has been unnecessarily complex (i.e., compared to using the Spring Framework or Seam Framework). EJB 3.1 further improves the handling by adding features including those listed below:
As mentioned, in the sample application, the DAOs are exposed as EJBs. The following code snippet shows how to expose an EJB by simply annotating a class with @Stateless:
public class PizzaDaoImpl extends GenericAbstractNameableDaoImpl<Pizza>
        implements PizzaDAO {
While - as of EJB 3.1 - this is no more mandantory, the EJB does implement an interface. That interface is annotated with @Local:
public interface PizzaDAO extends GenericAbstractNameableDAO<Pizza> {
Programming against interfaces is - almost - almost advisable, causing classes to be loosely coupeled.
The interface - or implementation, alternatively - can now be dependency-injected into other classes:
private PizzaDAO pizzaDAO;
In the sample application, @EJB annotations are used by the JSF managed beans, in the facade package.

JavaServer Faces (JSF) Managed Beans

JSF managed beans act as controllers for JSF views (see chapter Model-View-Controller (MVC) Pattern in my article on the Spring Framework). Tasks that JSF managed beans perform include ...
In the sample application, the JSF managed beans are located in the facade package. Related classes are located in the util.jsf package.
This article only covers features and concepts that are used in the sample application. For further information see tutorials like Die Konzepte von JavaServer Faces (in German), Sun's Tutorial and the JSF 2.0 specification.

Basic Configuration

Basic Configuration in the web.xml File

The following code snippet shows the contents of a basic /WEB-INF/web.xml file:
<web-app xmlns:xsi=""
        xmlns="" xmlns:web=""


                <servlet-name>Faces Servlet</servlet-name>
                <servlet-name>Faces Servlet</servlet-name>
The JSF FacesServlet is mapped to be invoked on any URL matching the *.xhtml pattern.

Basic Configuration in the faces-config.xml File

The /WEB-INF/faces-config.xml file that the sample application uses is shown in the following code block:
<faces-config xmlns=""




Most elements - except the navigation-rules - are optional. Managed beans for example can now be defined via annotations (as is done with the sample application).
First, there is a resource-bundle and a message-bundle, as well as a locale-config. See chapter Internationalization for more information. The view-handler, in this case, is also related to internationalization. See chapter Switching the Locale for a discussion.
The phase-listener is currently not used in the sample application, as its functionality is implemented by the view handler. See chapter Switching the Locale for more information on this specific functionality. See chapter JavaServer Faces Lifecycle for a discussion of lifecycle-related concepts.
There are no more navigation-rule (see chapter Handling Views) and managed-bean (see chapter Bean Declaration and Scope) declarations in the sample application's faces-config.xml as these settings can be configured less verbose by using annotations.

Bean Declaration and Scope

JSF managed beans in the sample application - in the facade package - are annotated as in the following code snippet:
public class PizzasBean {
The @ManagedBean optionally takes a name parameter. By default, the bean name is set to the class name, with a lower-case first letter.
There are different bean scopes (in the javax.faces.bean package), corresponding to the managed-bean-scope element in XML configuration. "Scope" refers to the life span of a bean, in practice that means, how long the bean can be used with the same state (particularly, instance fields' values). The following scopes exist:
Managed beans can - reasonably - only access other beans, whose life span is the same or longer as the calling bean. Consider the above scopes list ordered: Only @RequestScoped beans should access beans of all other scopes.
There are also implications on built-in objects (see chapter Implicit Objects Available with JSF) that scoped managed beans can reasonably access. - I.e., it makes no sense letting an @ApplicationScoped bean access request parameters. See chapter 5.3, The Managed Bean Facility, in the JSF 2.0 specification for more information.

Providing Model Data to Views

Views access their backing beans' via bean getter and setter methods. These can take or return Java objects of any type, commonly, including primitives and their wrappers, Collections and, to be used in tables, JSF's DataModel.
See chapter Unified Expression Language (EL) for more information.

Form Validation in Form-Backing Beans

It should be useful to read chapter Validating Forms (using JSF Core and HTML Tags) before continuing with the current chapter.
Basically, there are two ways of implementing validation functionality in JSF Java components: using validator methods or implementing the Validator interface. In both cases, a method with the following signature is implemented:
public void validate(
        FacesContext context, UIComponent component, Object value) 
        throws ValidatorException;
The ValidatorException is an unchecked RuntimeException and does not actually need to be declared. The FacesContext refers to the context in which the current request gets processed, the UIComponent the component to be validated, and the Object the component's value, typically.
When the validator method finds that the value should be rejected, it should set setValid(false) on the component, optionally, setValidatorMessage("some message") on a UIInput component, and finally, throw a ValidatorException. The ValidatorException may contain a FacesMessage to be queued for processing.
For sample code, see facade.CustomerBean and other beans in that package.
JSF provides a number of built-in Validators (and corresponding f:validate* tags). The following image lists the built-in validators JSF provides:
The BindingValidator and MethodBindingValidator listed above are used for more internal purposes by JSF.

Handling Views

In JSF, there is the notion of actions - as attributes of the h:commandButton and h:commandLink tags as well as form-backing beans' action methods. These methods must have the signature public String methodName().
Actions return an outcome - as string - which will, finally, be passed to a JSF NavigationHandler to determine which view to render.
Traditionally, outcomes have been mapped to view ids in the faces-config.xml file, using navigation-case elements. Since JSF 2.0, it is possible to directly return a view id, like in the action method in the following code snippet:
public String editAccount() {
        return "/editAccount.xhtml"; // instead of "editAccount"
When decorating JSF actions with the f:ajax tag, action outcomes are considered not at all.
The sample application, at first, has been developed without using AJAX, at all. At a later stage, the views have been amended to use AJAX. - When switching back to non-AJAX navigation, all action outcomes would have to be reviewed.
Actions always result in an HTTP POST request. As a negative side effect, the resulting view cannot be reloaded by the user without re-sending data (which is annoying to the user and as well jeopardizes the application's data integrity).
Appending the request parameter faces-redirect=true to the outcome (i.e., somePage.xhtml?faces-redirect=true) will cause JSF to conduct a redirect on the page, which, subsequently, can be reloaded by the user as normal.
All action outcomes in the sample application instruct a redirection.
Using string values to control business flows is inherently unsafe. For instance, the target might not exist because the value expression is misspelled. This problem exists with action outcomes, as well as with session attributes, request parameters, and message keys used for localization. Thus, there is a central application.common.Constants class in the sample application that holds these definitions in Java enums to provide at least a minimum of secureness at compile time.

JavaServer Faces Lifecycle

See chapter 2, Request Processing Lifecycle in the JSF 2.0 specification for a more in-depth discussion.
The following image (borrowed from the JSF 2.0 specification, thanks) shows the JSF Render and Execute lifecycle:
Render and Execute Lifecycle
In JSF, there is a component tree of UIComponent subclasses (represented by the corresponding tag - UIComponentELTag - before being rendered). The tree's root component is a UIViewRoot.
In the Restore View phase, after loading - a new or POSTed page -, this component tree gets built from the JSF page elements, the components being initialized with the corresponding tag attribute values.
In the Apply Request Values phase, any request parameters are applied by recursively calling processDecodes(FacesContext) on UIViewRoot and its children, finally causing the decode(..) method to be called on each Renderer.
After the Apply Request Values phase has finalized, a component's getValue() method will not yet hold the value that matches the corresponding request parameter. In contrast, getSubmittedValue() will do.
At this stage, normally, the Process Validations phase would begin, causing all components in the view to be validated. At times, this is not desirable. I.e., the sample application's "list pizzas" page contains two forms for letting the user edit her shopping card and for letting the user login, respectively. Logging in would not be possible when the shopping cart's form contained errors.
Therefor, the login form's h:commandButton contains an immediate="true" attribute, causing the related component to bring registered listeners, converters and validators forward, leaving unrelated components unaffected.
In the Process Validations phase - starting at the component tree's root, again -, firstly, Converters are used to convert the string represention of the submitted value to the object representation of the model (i.e., a date string to a Date object). Next, any registered Validators or validator methods get applied.
In case of conversion or validation errors, the next phases will be skipped and the Render Response phase be selected.
Converter error messages will be choked if there is no h:messages tag on the view.
Conversion in the Process Validation phase means that the components local values are set, but not the backing beans' properties.
In the Update Model Values phase, in contrast, the backing bean's properties are set. If conversion errors occur in this phase, the next phase will be skipped and the Render Response phase selected.
In the Invoke Application phase, registered action methods get executed, i.e., h:commandButton action="#{loginBean.login}".
In the Render Response phase, finally, the UIComponent.encodeAll(FacesContext) method gets called, being recursively called on any child component, and causing the component to generate the (HTML) output.

JAX-WS WebService

When a customer places an order in the sample application, a corresponding vendor is notified via a web service she supplies.
This chapter is kept short, intentionally. For further information, see chapter 11, Building Web Services with JAX-WS, in The Java EE 6 Tutorial.

Web Service Endpoint

The following code snippet shows the vendor's web service endpoint (in package vendor.service:
@WebService(serviceName = "orderService")
@SOAPBinding(style = Style.RPC)
public class OrderServiceEndpoint {

        @WebMethod(operationName = "add-order")
        @WebResult(name = "order-placed")
        public boolean addOrder(@WebParam(name = "order") Order order) {
                System.out.println("processing order ...");
                return true;
Only the @Stateless, @WebService, and @WebMethod, annotations are mandantory.
The service, in this case, is available at the URL http://localhost:8080/pizza-store-jee6/orderService?wsdl.

Web Service Client

At the client side, the JDK tool wsimport can be used to generate supporting classes (into package service.vendorclient) (shell script
wsimport \
-d target \
-p service.vendorclient \
The resulting OrderService class extends and contains hard-coded strings referencing server properties, including the location of the WSDL document. The endpoint's contract (in this case, a class, but that could also be an interface) has been exported as an interface (OrderServiceEndpoint). Of any other type that may be passed through the web service (objects passed as method parameters or method return values, as well as dependant objects of those) a class stub has been exported - being annotated with interfaces from the javax.xml.bind.annotation namespace.

Working Around wsimport Limitations

As the XML Binding annotations, that the wsimport tool adds, are hard to maintain, manually, it has been decided to keep the generated classes as a copy of the original ones. In other words, both a model.Customer class and a service.vendorclient.Customer class exist.
To "translate" the model.wrappers.Order, the application is working with, to the service.vendorclient.Order class, the OrderServiceEndpoint expects, the - general purpose - BeanAdapter class has been written, that translates the object trees using Java reflection.
See the BeanAdapter's source code for more information.
Furthermore, the wsimport tool, as already indicated, queries the web service's resulting WSDL document to generate stubs. The WSDL document, in turn, does not provide information on bean setters not needed for processing the corresponding web service method.
In the use case currently bespoken, setter methods in the generated Order and PizzaLineItem classes are missing.
Thus, wrappers around the aforementioned classes have been written, adding these missing setter methods.

Presentation Layer

New features of JavaServer Faces (JSF) 2.0 include:


Since JSF 2.0, alternatively to JSP, Facelets are used by default in the presentation layer.
JSF 1.2's FaceletViewHandler class - to be assigned to the web.xml view-handler tag - has been removed from the JSF 2.0 API.
See chapter JSF 2.0 Facelets for resources on that matter.

Facelet Tags Do Not Have a Tag Library (TLD) Anymore

In a simplified view, Facelets are the h:outputText and f:validator (etc.) tags defined in /META_INF/html_basic.tld and /META_INF/jsf_core.tld, within jsf-impl.jar. Because of the taglibs, there is code completion support in common IDEs.
The above statement is not true. Actually, Facelets do not use tag libraries (in the common TLD format), at all. It only happens that Facelets technology does support these tags.
The reason why, in your IDE, you get code completion for the h:commandButton tag (that already existed with JSF 1.2), but not for the new h:button tag, is: The freaking JSF 2.0 JARs do ship the old taglibs.
So, the old tags are still supported, however there are new tags, for which no taglibs exist.
I have not dived too deep into the code, however, apparently, the tags are hard-coded in JSF Java code. I.e., the following code snippet is from the HtmlLibrary:
package com.sun.faces.facelets.tag.jsf.html;

public final class HtmlLibrary extends AbstractHtmlLibrary {
    public final static String Namespace = "";

    public final static HtmlLibrary Instance = new HtmlLibrary();

    public HtmlLibrary() {

        this.addHtmlComponent("body", "javax.faces.Output",
        this.addHtmlComponent("button", "javax.faces.HtmlOutcomeTargetButton",
        this.addHtmlComponent("column", "javax.faces.Column", null);
        this.addHtmlComponent("commandButton", "javax.faces.HtmlCommandButton",
        this.addHtmlComponent("commandLink", "javax.faces.HtmlCommandLink",
Related tag libraries are listed in the following image:
Facelet Tag Libraries
Obviously, these classes are always created, and created without any additional configuration (in class ApplicationAssociate).
Anyways, it is too bad that there are no more (matching) tag libraries. It is really hard to develop, and impossible to validate, code in an IDE that way.
While Sun's current JSF 2.0 Reference Implementation does ship the JSF 1.2 taglibs, the sample application contains the *whoohoo* JSF 2.0 taglibs for JSF HTML, JSF Core, and Composite Components. These TLDs are located in the /WEB-INF/tld folder of the sample application.
As for the ui (core Facelets) portion of the issue, a corresponding TLD file (as of 2005) is also contained. That one has been taken from here.

Facelets vs. JavaServer Pages (JSP)

Facelets are not JSPs - and not compiled to Servlets - but representations of a JSF components tree. Such a components tree might be represented by the following code snippet:
<HtmlForm enctype="application/x-www-form-urlencoded" id="j_id1064806737_3f77a9d3"
        inView="true" prependId="true" rendered="true" submitted="false"
        <HtmlPanelGrid border="-2147483648" columns="1"
                id="j_id1064806737_3f77a9cd" inView="true" rendered="true" transient="false">
                <HtmlPanelGroup id="j_id1064806737_3f77a9e7" inView="true"
                        rendered="true" transient="false">
                        <HtmlOutputText escape="true" id="j_id1064806737_3f77a84f"
                                inView="true" rendered="false" transient="false" value="Englisch" />
                        <HtmlOutputText escape="true" id="j_id1064806737_3f77a87a"
                                inView="true" rendered="true" transient="false" value=" - " />
                        <HtmlCommandLink action="#{userOptionsBean.changeLanguage}"
                                actionExpression="#{userOptionsBean.changeLanguage}" disabled="false"
                                id="j_id1064806737_3f77a869" immediate="true" inView="true"
                                rendered="false" transient="false" value="Deutsch">
                                <UIParameter disable="false" id="j_id1064806737_3f77a803"
                                        inView="true" name="language" rendered="true" transient="false"
                                        value="de" />
                        <HtmlOutputText escape="true" id="j_id1064806737_3f77a83d"
                                inView="true" rendered="true" transient="false" value="Deutsch" />
It is recommended to read the article Improving JSF by Dumping JSP that illustrates the different - even concurrent - rendering strategies of JSF and JSP.
It has been already mentioned in chapter Facelet Tags Do Not Have a Tag Library (TLD) Anymore that tag libraries are not needed anymore (and not shipped as well ...).
While both technologies support compositing (by including files), templating (by overwriting pre-defined variables or areas) is supported by Facelets, only.

Unified Expression Language (EL)

In a nutshell, Expression Language can be described as in the following text (quoted from Expression Language Specification, Version 2.1):
The syntax is quite simple. Model objects are accessed by name. A generalized [] operator can be used to access maps, lists, arrays of objects and properties of a JavaBeans object; the operator can be nested arbitrarily. The . operator can be used as a convenient shorthand for property access when the property name follows the conventions of Java identifiers, but the [] operator allows for more generalized access.
Relational comparisons are allowed using the standard Java relational operators. Comparisons may be made against other values, or against boolean (for equality comparisons only), string, integer, or floating point literals. Arithmetic operators can be used to compute integer and floating point values. Logical operators are available.
The EL features a flexible architecture where the resolution of model objects (and their associated properties), functions, and variables are all performed through a pluggable API, making the EL easily adaptable to various environments.
The succeeding Unified Expression Language - #{...} (actually, # and $ being exchangeable) - additionally accounts for the JavaServer Faces nature, featuring
The first designator in an EL expression refers to an implicit object, managed bean, or resource bundle.
In method expressions, next, there is a dot and the (no-args) method name, i.e.,
<h:commandLink ... action="#{loginBean.logout}">
In value expressions, the part after the dot often refers to a property, i.e.,
<h:outputText value="#{}" />
The above expression #{} gets evaluated equally to #{pizzasBean[selectedPizza][name]}. The latter notation, however, allows for evaluating nested statements, i.e., #{i18n.languageName[sessionBean.currentLanguageCode]}.
It is possible to plug in custom ELResolvers, which is regularly done by several Java frameworks. The following image shows the ELResolvers used with JSF:
JSF EL Resolvers
See the article Unified Expression Language for a thorough discussion of "unifying" EL. Also see chapter 3, Expression Language Overview, in the JSTL specification.

Implicit Objects Available with JSF

Additionally to managed bean properties (and methods), several, basic, implicit objects can be accessed:
Since JSF 2.0, there is a new resource implicit object available. See chapter Handling Resources for more information.
From within a composite component, there is an additional cc implicit object available. There are the attributes cc.attrs and cc.parent. See chapter Composite User Interface Component for more information.

Tag Libraries Supported by Facelets

JSF HTML Tag Library

The JSF HTML tag library contains components for all UIComponent / HTML RenderKit Renderer combinations of the default renderkit.
The namespace is, common prefix is h:.
Tag names (i.e., h:inputSecret) are normally composed by a designator referring to a UIComponent, followed by on referring to the Renderer. For instance, a h:inputText can also be rendered as an h:inputSecret, displaying asteriks (*) in place of the string value (h:inputSecret being used as password input text box).
There are
Common tag attributes include
Introduced with JSF 2.0, the h:button and h:link tags allow for bookmarkability. Other new tags are h:outputScript and h:outputStylesheet.
The new h:outputScript and h:outputStylesheet tags have a library attribute (as well as h:graphicImage has this attribute), referring to a library of a resource. See chapter Handling Resources for more information.
See a (non-normative and JSF 1.2) JavaServer Faces HTML Tags Reference for an overview. See chapter 7, Using JavaServer Faces Technology in Web Pages, of the The Java EE 6 Tutorial for a more detailed discussion.

JSF Core Tag Library

The JSF Core tag library contains tags for JSF custom actions that are independant from the renderkit implementation.
The namespace is, common prefix is f:.
The tags can be categorized into
Since JSF 2.0, there is the f:ajax tag, used to execute server-side code and rendering the results at the client side, without reloading the page. See chapter Adding AJAX Support for a discussion.
See the article Introduction to JSF Core Tags Library for an overview. See chapter Using the Standard Converters, and the following chapters, of the The Java EE 6 Tutorial for a more detailed discussion.

JSF UI Tag Library

The JSF UI tag library is used for templating. This is the Facelets core tag library.
The namespace is, common prefix is ui:.
In templating there are relationship between templates and template clients.
UI tags to be used in templates include
UI tags to be used in template clients include
UI tags to be used in both templating roles include
There is also the jsfc attribute to convert plain HTML tags to JSF UI components, i.e.,
<input type="text" jsfc="h:inputText" value="#{}" />
See chapter 5, Templating and Re-Use, of the Facelets - JavaServer Faces View Definition Framework - Developer Documentation for a reference.

JSTL Core Tag Library

The JSTL Core tag library contains tags to control flow, input and output.
The namespace is, common prefix is c:.
There are
Other JSTL tag types (internationalization, XML processing, and database access) are not supported by Facelets, according to the JSF specification.
For further information see the JSTL specification.

JSTL Functions Library

The JSTL Functions library contains utility functions.
The namespace is, common prefix is fn:.
There is the fn:length function to be used with collections as well as several read-only, string-related, functions.
For further information see the JSTL specification.

Composite User Interface Components

Composite tags can be used to create custom tags from a combination of other tags, faciliating component reuse.
The namespace is, common prefix is composite:.
Composite user interface components are components made of the common JSF tags (HTML Basic, JSF Core, etc.), being reusable within a JSF application. Components development and use is accomplished purely by using markup tags, Java code is not required. (Custom) tag libraries are not involved.
At runtime, a composite component will be treated as an instance of UIComponent.
JSF 2.0 has a new notion of resources, which basically means regarding the $WEBAPP_ROOT/resources folder as a "special place". In the sample application for example, the composite components are placed within the $WEBAPP_ROOT/resources/components.
Composite components consist of a composite:interface and a composite:implementation. In the following paragraphs the changeLanguageLink component from the sample application is discussed. That component displays a link that allows a user for changing the UI language, where that link should not be clickable when that language is already selected in her session.
As always, the namespaces need to be declared:
<html xmlns=""
        <title>This will not be present in rendered output</title>
Note that in the the page (or component) that uses that component, only the markup within composite:implementation will be rendered.
The composite:interface in this case defines three attributes:

Display a link that will change the UI language.
If that UI language is already selected (see attribute "clickable")
that link should not be clickable.

        <composite:attribute name="languageDisplayName" required="true"
                type="java.lang.String" shortDescription="Language display name."
                targets="" />
        <composite:attribute name="languageCode" required="true"
                type="java.lang.String" shortDescription="2-char language code."
                targets="" />
        <composite:attribute name="clickable" required="true"
                shortDescription="Whether to display a link or just the text."
                targets="" />
The composite:implementation consists of a h:commandLink and h:outputText that are selectively rendered:
        <h:commandLink value="#{cc.attrs.languageDisplayName}"
                action="#{userOptionsBean.changeLanguage}" immediate="true"
                <f:param name="language" value="#{cc.attrs.languageCode}" />
                <f:ajax execute="@this" render="@form" />
        <h:outputText value="#{cc.attrs.languageDisplayName}"
                rendered="#{!cc.attrs.clickable}" />
Note the cc implicit object that is always available within a composite component's implementation section. There is its attrs property, pointing to the composite:attributes defined in the interface portion, and also there is a parent property, to access the parent UIComponent.
That's it for the component. - Using it - in changeLanguagePanel.xhtml in the sample application - starts with declaring the matching namespace:
<html ...
The components part therein points to the $WEBAPP_ROOT/resources/components folder. So, resource folders can be accessed via matching namespaces. (The "components" portion in xmlns:components of course could be any other designator.)
The components itself are referenced as in the following code snippet:
        languageDisplayName="#{i18n.languages_en_name}" languageCode="en"
        clickable="#{!userOptionsBean.currentLanguage.equals('en')}" />
The component's properties match those declared by the composite:interface's composite:attributes.
There would be more to say on composite user interface components. As they are UIComponents, validators, converters and action listeners can be assigned to them. See the article True Abstraction: Composite UI Components in JSF 2.0 -- Part 2 for a sample of assigning an f:actionListener to a composite:actionSource.
See a video on creating JSF 2.0 composite components in the IntelliJ IDEA 9 (Maia) Preview.
For a reference, see chapter 3.6, Composite User Interface Components, in the JavaServer Faces 2.0 specification.

Selected Tasks

Displaying a List of Checkboxes

In the editPizzaIngredients.xhtml page, there is a user-editable list of optional ingredients that can be added to a pizza.
The following code snippet shows the relevant portion of that page:
                var="ingredient" itemLabel="#{}"
                itemValue="#{}" />
The h:selectManyCheckbox' value holds a Collection of selected items. This property is read-write and will be written back to the backing bean.
The f:selectItems's value holds the list of all available items.
Both tags' value attribute can take a Collection, Map, or array reference.
The behavior is similar to the h:selectManyListbox and h:selectManyMenu tag's behavior.
See chapter Rendering Components for Selecting Multiple Values in The Java EE 6 Tutorial.

Validating Forms (using JSF Core and HTML Tags)

JSF provides a number of standard validators in the JSF Core Tag Library, including
f:validateBean relates to model objects' (or entities') annotated properties the user interface component to be validated is bound to. See chapter Annotations Related to the Bean Validation Framework for more information.
f:validator allows for registering a custom Validator implementation. See chapter Form Validation in Form-Backing Beans for information on that.
The other validator tags are self-containing.
A - typical - form field to be POSTed and validated is shown in the following code snippet:
<h:outputLabel value="#{i18n.customerForm_password}" for="password" />

<h:inputSecret id="password" maxlength="255" redisplay="true"
        required="true" requiredMessage="#{i18n.validators_required}"
        <f:validateBean />

<h:message styleClass="errors" for="password" />
Firstly, that input component named password has a maxlength attribute, which does not allow for inserting more than the given number of characters - checked by the web browser, JSF not being invoked.
There is an h:message container that displays any potential conversion or validation error messages.
There is a required constraint and an associated requiredMessage to be displayed when the matching check fails.
The f:validateBean Validator reference is nested within the h:inputSecret tag. When the matching check fails, the associated validatorMessage will go into the h:message container.
For more information see chapter Using the Standard Validators in The Java EE 6 Tutorial.

Handling Resources

Since JSF 2.0, there is the notion of managed resources.
A resource identifier consists of the following segments (expressions in brackets - [] - being optional):
The default resource folder location is /resources in a web application, and /META-INF/resources in packed JARs.
The following list of fictuous resources illustrates possible usage:
These resources can be accessed like
With resource, there is a new implicit object avaiable in EL.
UIComponents and Renderers may declare a @ResourceDependency annotation at the type level, i.e., @ResourceDependency(library="corporate", name="colorAndMedia.css").
It is commonly considered sensible to place resources (including custom components) within the /WEB-INF folder of a web application - where they cannot be directly read from outside (then not having a certain context needed, etc.). This intention has not been pursued with JSF's resources concept.

Writing Composite User Interface Components

See chapter Composite User Interface Components for a working sample and discussion.

Adding AJAX Support

Most actions that do not forward to other pages are "ajaxified" in the sample application.
Using the f:ajax tag is fairly straight-forward.
The f:ajax tag can either enclose other components (i.e., a view, or group of related components) or be nested as a child tag into a component (i.e., a h:commandButton). If there are both outer and inner tags, referring to the same actions, the outermost tag will be executed, only.
The following code snippet shows one possible usage case. The h:commandButton shall execute a single method and then re-render a region.
<h:commandButton value="#{i18n.listPizzas_commands_removeFromCart}"
        action="#{pizzasBean.removeFromCart}" immediate="true"
        <f:ajax execute="@this" render="@form" event="action" />
The optional execute attribute takes a - space-separated - list of component IDs to process. @this is the default value and refers to the parent component. Other pre-defined values are @all, @form, and @none.
The - likewise - optional render attribute can take the same values and is used to specify which components to re-render after processing. The default is @none.
The event attribute, too, is optional. The default value is action for ActionSource components and valueChange for EditableValueHolder components. Other possible values are those defined as attributes of the corresponding HTML elements, however, onblur is blur in this case.
render="@all" may not work with multiple forms.
f:ajax' onerror attribute - that takes the name of a JavaScript function - is not well documented. I.e., it is unclear whether and how the underlying error message can be accessed. Moreover, the JavaScript function passed does not get called when an error occurs. - With or without using the onerror attribute, errors are currently swallowed in the sample application. - Although the AjaxExceptionHandlerImpl does write out the error information as partial response, that information is not going to land in a h:messages sink.
Currently exceptions in the sample application's action methods are handling by queuing a FacesMessage.
Normally, the string outcomes of action methods determine which view to display next. In AJAX mode, the outcomes are not evaluated at all.
There are more attributes on the f:ajax tag. See chapter, <f:ajax>, in the JavaServer Faces 2.0 specification for further information.


See the blog article JSF and I18N for a basic introduction on internationalization in JSF.
While by Expression Language, in the views, messages of message-bundles defined in faces-config.xml can be accessed, JSF's MessageFactory - that creates FacesMessages - will not use that resource. To enable localized (or otherwise externalized) messages for the JSF backend, a resource-bundle needs to be set up in faces-config.xml (optionally, pointing to the same .properties file).
Unfortunately, the .properties files are interpreted by a java.util.ResourceBundle, which supposes them to be ISO-8859-1-encoded (see PropertyResourceBundle's JavaDoc). In applications that use Unicode (Java internally does, and web applications should do, throughout), problems arise whenever there are non-ASCII charactes.
Java's generic solution to this issue is the JDK's native2ascii tool that converts any offending characters to their Unicode representation, i.e., "ö" to "\u00F6". The sample application comes with a script ( that converts all files matching a given pattern.
Alternatives include the .properties file editor that ships with the JBoss Tools Eclipse plugins, as well as a Maven plugin / goal and an Ant task.

Switching the Locale

For a glance of most of areas involved, see this article.
The Locale of the current JSF lifecycle can (could) be changed by the following code:
FacesContext.getCurrentInstance().getViewRoot().setLocale(new Locale("de"));
This setting, however, does not get persisted across requests.
Therefor, in the sample application, a custom LocaleChangerViewHandler extends a JSF ViewHandler, overwriting the Locale calculateLocale(FacesContext context) method. In that method, it first tries to derive a valid locale from a custom request parameter, and if that is null, tries to locate a locale that might have been stored in the HttpSession, previously. Only if no locale is found by these methods, the super class' locale is used.
Alternatively, a custom PhaseListener can be used in a similar way.
In the sample application, the current locale is determined by evaluation a request parameter and / or HTTP session attribute. Alternatively, the locale could be determined by portions of a view's URL, providing benefits regarding bookmarkeability and search engines support.


All links retrieved at the date of publication.

Java Persistence API (JPA) 2.0

Enterprise JavaBeans (EJB) 3.1

JavaServer Faces (JSF) 2.0

JSF 2.0 Facelets

Related Resources

Tools and Frameworks

Related Resources

Valid XHTML 1.0 Transitional Valid CSS!