FacesServlet

The FacesServlet is an implementation of javax.servlet.Servlet and acts as the central controller element, through which all user requests pass. As shown in Figure 11-2, when an event occurs (e.g., when the user clicks a button), the event notification is sent via HTTP to the server and is intercepted by the javax.faces.webapp.FacesServlet. It examines the request and calls various actions on the model using backing beans.

Behind the scenes, the FacesServlet accepts incoming requests and hands control over to the javax.faces.lifecycle.Lifecycle object. Using a factory, it creates an object of type javax.faces.context.FacesContext, which contains and processes all the per-request state information. The Lifecycle object uses the FacesContext object during the six different phases of the page life cycle (previously described in Chapter 10) before rendering the response.

Out of the box, user requests are processed by the JSF runtime that declares a FacesServlet using common behavior, thanks to configuration by exception. If the defaults do not suit you, you can configure the FacesServlet in a web.xml file. Listing 11-1 shows the web.xml as an example.

Listing 11-1.  web.xml Defining the FacesServlet

<?xml version='1.0' encoding='UTF-8'?>
<web-app xmlns=" http://xmlns.jcp.org/xml/ns/javaee "
         xmlns:xsi=" http://www.w3.org/2001/XMLSchema-instance "
         xsi:schemaLocation=" http://xmlns.jcp.org/xml/ns/javaee →
         http://xmlns.jcp.org/xml/ns/javaee/web-app_3_1.xsd "
         version="3.1">
 
  <servlet>
    <servlet-name>Faces Servlet</servlet-name>
    <servlet-class> javax.faces.webapp.FacesServlet </servlet-class>
    <load-on-startup>1</load-on-startup>
  </servlet>
  <servlet-mapping>
    <servlet-name>Faces Servlet</servlet-name>
    <url-pattern> *.jsf </url-pattern>
  </servlet-mapping>
 
  <context-param>
    <param-name> javax.faces.PROJECT_STAGE </param-name>
    <param-value>Development</param-value>
  </context-param>
  <context-param>
    <param-name> javax.faces.FACELETS_SKIP_COMMENTS </param-name>
    <param-value>true</param-value>
  </context-param>
</web-app>

This web.xml file defines the javax.faces.webapp.FacesServlet by giving it a name (e.g., Faces Servlet) and a mapping. In this example, all requests that have the .jsf extension are mapped to be managed by the Servlet, and any request such as http://localhost:8080/chapter11-1.0/newBook.jsf will be handled by JSF.

You can also configure a few JSF-specific parameters in the <context-param> element. Table 11-1 lists some of these parameters.

FacesContext

JSF defines the javax.faces.context.FacesContext abstract class for representing the contextual information associated with processing an incoming request and creating the corresponding response. This is the class that allows interaction with the UI and the rest of the JSF environment.

To gain access, you can either use the implicit facesContext object in your pages (see Chapter 10 for discussion on implicit objects) or obtain a reference in your backing beans using the static method getCurrentInstance(). This will return the FacesContext instance for the current thread, and then you can invoke the methods listed in Table 11-2.

Faces Config

The FacesServlet is internal to JSF implementations, and, though you don’t have access to its code; you do require metadata to configure it or some properties in the web.xml as seen in Listing 11.1. By now, you may be accustomed to the two possible choices of metadata in Java EE 7: annotations and XML deployment descriptors (/WEB-INF/faces-config.xml).

Before JSF 2.0, the only choice was to use XML; today, backing beans, converters, event listeners, renderers, and validators can have annotations, and so using XML configuration files has become optional. Even most of the navigation between pages can be orchestrated with either XML or Java code. Listing 11-2 shows an extract of what a faces-config.xml file looks like. In this example it defines a default locale (fr), a message bundle for internationalization, and some navigation rules. Soon you will see how to navigate with and without faces-config.xml.

Listing 11-2.  Snippet of a faces-config.xml File

<?xml version='1.0' encoding='UTF-8'?>
<faces-config xmlns=" http://xmlns.jcp.org/xml/ns/javaee "
              xmlns:xsi=" http://www.w3.org/2001/XMLSchema-instance "
              xsi:schemaLocation=" http://xmlns.jcp.org/xml/ns/javaee →
              http://xmlns.jcp.org/xml/ns/javaee/web-facesconfig_2_2.xsd "
              version="2.2">
 
  <application>
    <locale-config>
      < default-locale >fr</default-locale>
    </locale-config>
    < resource-bundle >
      <base-name>messages</base-name>
      <var>msg</var>
    </resource-bundle>
  </application>
 
  < navigation-rule >
    <from-view-id>*</from-view-id>
    <navigation-case>
      <from-outcome>doCreateBook-success</from-outcome>
      <to-view-id>/listBooks.htm</to-view-id>
    </navigation-case>
  </navigation-rule>
 
</faces-config>

Anatomy of a Backing Bean

Backing beans are Java classes that are managed by the FacesServlet. The UI components are bound to the backing bean’s properties and can invoke action methods. A backing bean needs to follow these requirements:

• The class must be annotated with @javax.inject.Named or the XML equivalent in the faces-config.xml deployment descriptor.
• It must have a scope (e.g., @RequestScoped).
• The class must be defined as public; it must not be final or abstract.
• The class must have a public no-arg constructor that the container will use to create instances.
• The class must not define the finalize() method.
• Attributes must have public getters and setters to be bound to a component.

Following the ease-of-use model of Java EE 7, a backing bean can simply be an annotated POJO, eliminating most of the configuration. Remember that in Chapter 2 I introduced CDI stereotypes. The @javax.enterprise.inject.Modelis the perfect stereotype to use on backing beans as it is @Named and @RequestScoped (as shown in Listing 11-4). So you can rewrite the BookController showed in Listing 11-3, replace the annotations with @Model (Listing 11-5), and get the same behavior.

Listing 11-4.  The Built-in CDI @Model Stereotype

@Named
@RequestScoped
@Documented
@Stereotype
@Target({ TYPE, METHOD, FIELD })
@Retention(RUNTIME)
public @interface Model {
}

Listing 11-5.  The BookController Using the @Model Stereotype

@Model
public class BookController {
 
  private Book book = new Book();
 
  public String doCreateBook() {
    createBook(book);
    return "listBooks.xhtml";
  }
 
  // Constructors, getters, setters
}

The presence of the @javax.inject.Named annotation on a class allows expression language to use it in a page. @Named can also specify a different name for the backing bean (which by default is the name of the class starting with a lowercase letter). UI components are bound to backing bean properties; changing the default name has an impact on how you invoke a property or a method. The code in Listing 11-6 renames the backing bean to myBean.

Listing 11-6.  A Renamed Backing Bean

@Named(" myBean ")
@RequestScoped
public class BookController06 {
 
  private Book book = new Book();
 
  public String doCreateBook() {
    createBook(book);
    return "listBooks.xhtml";
  }
 
  // Constructors, getters, setters
}

To invoke attributes or methods of this backing bean in your pages, you must use the overridden name as follows:

<h:outputText value="#{ myBean .book.isbn}"/>
<h:form>
  <h:commandLink action="#{ myBean .doCreateBook}">Create a new book</h:commandLink>
</h:form>

@Named
@ApplicationScoped
public class InitController {
 
  private Book defaultBook;
 
  @PostConstruct
  private void init() {
    defaultBook = new Book("default title", 0F, "default description");
  }
 
  // Constructors, getters, setters
}

Handling Exceptions and Messages

Backing beans process business logic, call EJBs, persist and retrieve data from databases, and so on, and sometimes things can go wrong. In this case, the user has to be informed through a message to take action. Messages can be split into two categories: application errors (involving business logic, database, or network connection) and user input errors (invalid ISBN or empty fields). Application errors can generate a completely different page asking the user to retry in a few moments, for example, or call a hotline service. Input errors can be displayed on the same page, with text describing the error, and messages can be informational, such as one indicating that a book was successfully added to the database.

In Chapter 10, you saw tags that are used to display messages on pages (<h:message> and <h:messages>). To produce these messages, JSF allows you to queue messages by calling the facesContext.addMessage() method in your backing beans. The signature of the method is as follows:

void addMessage(String clientId , FacesMessage message)

This method appends a FacesMessage to the set of messages to be displayed. The first parameter of this method specifies a client identifier. This parameter refers to the Document Object Model (DOM) location of the UI component that the message is registered to (e.g., bookForm:isbn refers to the UI component that has the isbn identifier within the bookForm form). If clientId is null, the message doesn’t refer to any special component and is said to be global to the whole page. A message consists of a summary text, a detailed text, and a severity level (fatal, error, warning, and info). Messages can also be internationalized using message bundles.

FacesMessage (Severity severity, String summary, String detail)

The code in Listing 11-8 is a snippet of a backing bean that creates a book. If the creation succeeds, a global informational message is queued (the FacesMessage with a SEVERITY_INFO). If an exception is caught, an error message is added to the messages queue to be displayed. Note that both messages are global because the clientId is null. On the other hand, when we validate the ISBN and book title entered by the user, we want to display the warning messages (SEVERITY_WARN) related to the UI component (e.g., bookForm:title is the DOM identifier of the text field title located under the bookForm form).

Listing 11-8.  Adding Different Severity Messages

@Named
@RequestScoped
public class BookController {
 
  @Inject
  private BookEJB bookEJB;
  private Book book = new Book();
 
  public String doCreateBook() {
    FacesContext ctx = FacesContext.getCurrentInstance();
 
    if (book.getIsbn() == null || "".equals(book.getIsbn())) {
      ctx. addMessage ( "bookForm:isbn" , new FacesMessage (FacesMessage. SEVERITY_WARN , →
              "Wrong isbn", "You should enter an ISBN number"));
    }
    if (book.getTitle() == null || "".equals(book.getTitle())) {
      ctx. addMessage ( "bookForm:title" , new FacesMessage(FacesMessage.SEVERITY_WARN, →
              "Wrong title", "You should enter a title for the book"));
    }
 
    if ( ctx.getMessageList().size() != 0)
      return null;
 
    try {
      book = bookEJB.createBook(book);
      ctx.addMessage( null , new FacesMessage(FacesMessage. SEVERITY_INFO , "Book created", →
              "The book" + book.getTitle() + " has been created with id=" + book.getId()));
 
    } catch (Exception e) {
      ctx.addMessage(null, new FacesMessage(FacesMessage. SEVERITY_ERROR , →
              "Book hasn't been created", e.getMessage()));
    }
    return null;
  }
 
  // Constructors, getters, setters
}

The FacesContext is available in the page and so is the FacesMessage. The page can then display the global messages (with clientId equals to null) using a single <h:messages> tag. When we want to display a message at a specific place on the page for a specific component (as is usually the case with validation or conversion errors), we use <h:message>. Figure 11-4 shows a page with messages specifically aimed at the ISBN and title input fields.

The page will have an input text field with an identifier (id="isbn"), and the <h:message> tag will refer to that component (for="isbn"). The result will be that this specific message will only be displayed for this component.

<h: messages infoStyle="color:blue" warnStyle="color:orange" errorStyle="color:red"/>
<h:form id=" bookForm ">
  <h:inputText id="isbn" value="#{bookController.book.isbn}"/>
  <h:message for="isbn" />
</h:form>

If the ISBN field has not been filled, a warning message appears next to the ISBN input text field. JSF uses this messaging mechanism for converters, validators, and Bean Validation. Note that the <h:messages> tag can have different styles per severity (here errors are red and warnings orange).

Bringing JSF and EJBs Together

Until now all the binding and business invocation has been made through backing beans. As you’ll soon see, backing beans also deal with navigation. So when you want to do some processing and then take the user to a different page, having a backing bean makes sense. But sometimes you just need to access an EJB to get a list of books to fill a datatable, for example. You could still go through a backing bean, but it would mostly delegate the call to the EJB. So why not directly call the EJB from the page?

One goal of CDI is to bring JSF and EJBs together. What do you need to do? Not much, just add a @Named annotation to your EJB and you can invoke it using expression language. Listing 11-9 shows a stateless EJB that uses JPA to get the list of all of the books from the database. It has a CDI @Named annotation and therefore can be invoked in a JSF page.

Listing 11-9.  A Stateless EJB with a CDI @Named Annotation

@Named
@Stateless
public class BookEJB {
 
  @Inject
  private EntityManager em;
 
  public List<Book> findAllBooks() {
    return em.createNamedQuery("findAllBooks", Book.class).getResultList();
  }
}

The findAllBooks() method in Listing 11-9 returns a list of books. To fill a datatable with this list, there is no need to use a backing bean. The page can directly invoke the bookEJB.findAllBooks() in the <h:dataTable> component using EL.

<h:dataTable value=" #{bookEJB.findAllBooks()} " var="book">
  <h:column>
    <h:outputText value="#{book.title}"/>
  </h:column>
</h:dataTable>

Navigation

Web applications are made of multiple pages that you need to navigate through. Depending on the application, you can have various levels of navigation with page flows that are more or less sophisticated. You can think of wizards, where you can go back to the previous or initial page, business cases where you go to a particular page depending on a certain rule, and so on. JSF has multiple options for navigation and allows you to control the flow, based on single pages or globally for the entire application.

<h:link value="Back to creating a new book" outcome="newBook.xhtml" />

<h:commandButton value="Create a book" action="#{bookController.doCreateBook} ">

@Named
@RequestScoped
public class BookController {
 
  @Inject
  private BookEJB bookEJB;
  private Book book = new Book();
  private List<Book> bookList = new ArrayList<>();
 
  public String doCreateBook () {
    book = bookEJB.createBook(book);
    bookList = bookEJB.findBooks();
    return " listBooks.xhtml ";
  }
 
  // Constructors, getters, setters
}

@Named
@RequestScoped
public class BookController {
  // ...
 
  public String doCreateBook () {
    book = bookEJB.createBook(book);
    bookList = bookEJB.findBooks();
    return " success ";
  }
 
  // Constructors, getters, setters
}

<?xml version='1.0' encoding='UTF-8'?>
<faces-config xmlns=" http://xmlns.jcp.org/xml/ns/javaee "
              xmlns:xsi=" http://www.w3.org/2001/XMLSchema-instance "
              xsi:schemaLocation=" http://xmlns.jcp.org/xml/ns/javaee →
              http://xmlns.jcp.org/xml/ns/javaee/web-facesconfig_2_2.xsd "
              version="2.2">
 
  <navigation-rule>
    <from-view-id> newBook.xhtml </from-view-id>
    <navigation-case>
      <from-outcome> success </from-outcome>
      <to-view-id> listBooks.xhtml </to-view-id>
    </navigation-case>
  </navigation-rule>
 
</faces-config>

<navigation-rule>
  <from-view-id> * </from-view-id>
  <navigation-case>
    <from-outcome> logout </from-outcome>
    <to-view-id> logout.xhtml </to-view-id>
  </navigation-case>
</navigation-rule>

public String doCreateBook() {
  book = bookEJB.createBook(book);
  bookList = bookEJB.findBooks();
  switch (value) {
    case 1: return " page1.xhtml "; break;
    case 2: return " page2.xhtml "; break;
    default: return null ; break;
  }
}

<navigation-rule>
    <from-view-id>*</from-view-id>
    <navigation-case>
        <from-outcome>logout</from-outcome>
        <to-view-id>logout_admin.xhtml</to-view-id>
        <if>#{userController.isAdmin}</if>
    </navigation-case>
</navigation-rule>

<f:metadata>
  <f: viewParam name="id" value="#{bookController.book.id}"/>
</f:metadata>

<f:metadata>
  <f:viewParam name="id" value="#{bookController.book.id}"/>
  <f: viewAction action="#{bookController.doFindBookById}"/>
</f:metadata>

Converters

When a form is displayed on a browser, the end user fills the input fields and hits a button, resulting in transporting the data to the server in an HTTP request using String formats. Before updating the model on the backing bean, these data have to be converted from Strings to the target objects (Float, Integer, BigDecimal, etc.). The reverse action will take place when the data have to be sent back to the client in the response and be rendered in the browser.

JSF ships with converters for common types like dates and numbers. In cases where the backing bean property is a primitive type (Integer, int, Float, float, etc.), JSF will automatically convert the UI component value to the correct type and back. When the property is some other datatype, you need to provide your own converter. Table 11-3 lists all the standard converters that are in the javax.faces.convert package.

JSF will automatically convert input values to numbers when the backing bean property is some primitive numeric type and to date or time when the property is some date type. If automatic conversion doesn’t suit you, you can explicitly control it through the standard convertNumber and convertDateTime tags. To use these tags, you need to nest the converter inside any of the input or output tags. The converter will be called by JSF during the life cycle.

The convertNumber tag has attributes that allow conversion of the input value to a number (default), a currency, or a percentage. You can specify a currency symbol or a number of decimal digits, as well as a formatting pattern, determining how the number should be formatted and parsed.

<h:inputText value="#{bookController.book.price}">
  <f: convertNumber currencySymbol="$" type="currency"/>
</h:inputText>

The convertDateTime tag can convert dates in various formats (date, time, or both). It has several attributes that control the date conversion and time zones. A pattern attribute allows identification of the pattern of the date String that will be converted.

<h:inputText value="#{bookController.book.publishedDate}">
    <f: convertDateTime pattern="MM/dd/yy"/>
</h:inputText>

Custom Converters

Sometimes converting numbers, dates, enums, and so on is insufficient, and you may require custom conversion. It is easy to develop your own converters and use them in pages with JSF. You simply have to write a class that implements the javax.faces.convert.Converter interface and register it with metadata. This interface has two methods.

Object getAsObject (FacesContext ctx, UIComponent component, String value)
String getAsString (FacesContext ctx, UIComponent component, Object value)

The getAsObject() method converts the String value of a UI component into the corresponding supported type and returns the new instance. This method throws a ConverterException if the conversion fails. Conversely, the getAsString() method converts the provided type to a String, to be rendered in markup language (such as XHTML).

Once you develop the custom converter, it must be registered to allow it to be used in the web application. One method is by declaring the converter in the faces-config.xml file; the other is to use the @FacesConverter annotation.

Listing 11-13 shows how to write a custom converter that converts a price from dollars to euros. It starts by associating this converter with the name euroConverter using the @FacesConverter("euroConverter") annotation, and implements the Converter interface. This example only overrides the getAsString() method, which returns a String representation of a given price in euros.

Listing 11-13.  A Euro Converter

@FacesConverter("euroConverter")
public class EuroConverter implements Converter {
 
  @Override
  public Object getAsObject (FacesContext context, UIComponent component, String value) {
    return value;
  }
 
  @Override
  public String getAsString (FacesContext ctx, UIComponent component, Object value ) {
    float amountInDollars = Float.parseFloat( value .toString());
    double ammountInEuros = amountInDollars * 0.8;
    DecimalFormat df = new DecimalFormat("###,##0.##");
    return df.format(ammountInEuros);
  }
}

To use this converter, use either the converter attribute of the <h:outputText> tag or the <f:converter> tag. In both cases, you must pass the name of the custom converter defined in the @FacesConverter annotation (euroConverter). The following code displays two output texts, one representing the price in dollars and the other converting this price to euros:

<h:outputText value="#{book.price}"/> // in dollar
<h:outputText value="#{book.price}">  // converted in euro
  < f:converter converterId=" euroConverter "/>
</h:outputText>

Or you can use the converter attribute of the outputText tag.

<h:outputText value="#{book.price}" converter="euroConverter" />

Validators

When working with web applications, the accuracy of user-entered data must be ensured. Accurate data entry can be enforced on the client side using JavaScript or on the server side using validators and Bean Validation. JSF simplifies data validation through the use of standard and custom server-side validators. Validators act as a first level of control by validating the value of UI components before being processed by the backing bean.

UI components generally handle simple validation, such as whether or not a value is required. For example, the following tag would require that a value in the text field be entered:

<h:inputText value="#{bookController.book.title}" required="true" />

If you do not enter a value, JSF returns the page with a message indicating that a value should be entered (the page must have a <h:messages> tag). This uses the same message mechanism that I described before. But JSF comes with a set of richer validators that can be used (described in Table 11-4), which are defined in the javax.faces.validator package.

These validators are useful for generic cases like the length of a field or a number range and can be easily associated within a component, in the same way as converters are (both can be used on the same component). The following code ensures the book’s title is between 2 and 20 characters in length and its price is from $1 to $500:

<h:inputText value="#{bookController.book.title}" required="true">
  <f: validateLength minimum="2" maximum="20"/>
</h:inputText>
<h:inputText value="#{bookController.book.price}">
  <f: validateLongRange minimum="1" maximum="500"/>
</h:inputText>

Custom Validators

Perhaps the standard JSF validators might not suit your needs; you may have data that have to follow certain business formats such as a ZIP code, a state, or an e-mail address. You must create your own custom validator to address these cases. Like converters, a validator is a class that needs to implement an interface and override some method. In the case of a validator, the interface is javax.faces.validator.Validator, which has a single validate() method:

void validate (FacesContext context, UIComponent component, Object value)

In this method, the value argument is the one that has to be checked, based on some business logic. If it passes the validation check, you can simply return from the method, and the life cycle of the page will continue. If not, you can throw a ValidatorException and include a FacesMessage with a summary and a detail message describing the validation error. You must register the validator either in the faces-config.xml or by using the @FacesValidator annotation.

As an example, create an ISBN validator that ensures the ISBN entered by the user for the book follows a certain format (using a regular expression). Listing 11-14 shows the code for the IsbnValidator.

Listing 11-14.  An ISBN Validator

@FacesValidator("isbnValidator")
public class IsbnValidator implements Validator {
 
  private Pattern pattern;
  private Matcher matcher;
 
  @Override
  public void validate (FacesContext context, UIComponent component, →
                       Object value) throws ValidatorException {
 
    String componentValue = value.toString();
 
    pattern = Pattern.compile("(?=[-0-9xX]{13}$)");
    matcher = pattern.matcher(componentValue);
 
    if (!matcher.find()) {
      String message = MessageFormat.format("{0} not a valid isbn format", componentValue);
      FacesMessage facesMessage = new FacesMessage(FacesMessage.SEVERITY_ERROR, msg, msg);
      throw new ValidatorException (facesMessage);
    }
  }
}

The code in Listing 11-14 starts by associating the validator with the name isbnValidator, to allow it to be used in a page. It implements the Validator interface and adds the validation logic in the validate() method. It checks, with a regular expression, that the ISBN has the right format. If not, it adds a message to the context and throws an exception. JSF will automatically resume the life cycle of the page, recall the page, and display the error message. You can employ this custom validator in your pages using the validator attribute or embedding a <f:validator> tag.

<h:inputText value="#{bookController.book.isbn}" validator ="isbnValidator"/>
// or
<h:inputText value="#{bookController.book.isbn}">
  <f: validator validatorId="isbnValidator" />
</h:inputText>

Integration with Bean Validation

Since JSF 2.0, the support for Bean Validation has been made mandatory (i.e., a JSF implementation must support it). The way it works is pretty simple. If a JSF page has several text fields and each text field is bound to a backing bean property that has at least one Bean Validation constraint annotation, the javax.validation.Validator.validate() method is called during the validation phase. Bean Validation is therefore invoked automatically without the developer doing anything on the JSF page or calling any Bean Validation method in the backing bean. The JSF runtime also ensures that every ConstraintViolation that resulted in attempting to validate the model data is wrapped in a FacesMessage and added to the FacesContext as is normal with every other kind of validator. So a simple <h:messages> in a page will display the list of messages of the violated ConstraintViolation.

In Chapter 3, I presented validation groups. If in your page you need to validate certain components for a certain group, you can use the <f:validateBean> tag. The code that follows validates the title and the price of a book for the Delivery group only:

<f:validateBean validationGroups ="org.agoncal.book.javaee7.Delivery">
  <h:inputText value="#{bookController.book.title}"/>
  <h:inputText value="#{bookController.book.price}"/>
</f:validateBean>

General Concepts

The term “Ajax” was coined in 2005 as a set of alternative techniques for loading asynchronous data into web pages. Back in 1999, Microsoft created the XMLHttpRequest object as an ActiveX control in Internet Explorer 5. In 2006, the World Wide Web Consortium (W3C) released the first specification draft for the XMLHttpRequest object, which is now supported by most browsers. At the same time, several companies brainstormed about how to ensure that Ajax could be the industry standard for a rich application platform based on open technologies. The result of this work was the creation of the OpenAjax Alliance, which consists of vendors, open source projects, and companies using Ajax-based technologies.

As shown in Figure 11-7, in traditional web applications, the browser has to ask for the full HTML documents from the server. The user clicks a button to send or get the information, waits for the server to respond, and then receives the entire page that the browser loads. Ajax, on the other hand, uses asynchronous data transfer (HTTP requests) between the browser and the server, allowing web pages to request small bits of information (JSON or XML data) from the server instead of whole pages. The user stays on the same page while a piece of JavaScript requests or sends data to a server asynchronously, and only portions of the page are actually updated, making web application faster and more user friendly.

In principle, Ajax is based on the following:

• XHTML and CSS for presentation.
• DOM for dynamic display and interaction with data.
• XML and XSLT for the interchange, manipulation, and display of XML data.
• The XMLHttpRequest object for asynchronous communication.
• JavaScript to bring these technologies together on the browser.

XMLHttpRequest is an important part of Ajax, as it’s a DOM API used by JavaScript to transfer XML from the browser to the server. The data returned have to be fetched on the client side to update portions of the page dynamically with JavaScript. The data can have several formats such as XHTML, JSON, or even plain text.

Since JSF 2.0, Ajax is supported natively, so you don’t have to develop JavaScript to handle the XMLHttpRequest, but you do need to use a JavaScript library that has been specified and shipped with JSF implementations.

Support in JSF

Previous versions of JSF offered no native Ajax solution, so third-party libraries had to be used to fill the gap. Sometimes this increased the complexity of the code at the expense of performance. Since JSF 2.0, things are much easier, as Ajax support has been specified and is built into any JSF implementation.

First of all, there is a specified JavaScript library (jsf.js) for performing Ajax interaction, which means you don’t have to develop your own scripts or manipulate the XMLHttpRequest objects directly. Without developing any JavaScript, you can use a set of standardized functions to send asynchronous requests and receive data. In order to use this library in your pages, you need to add the jsf.js resource with the following line of code:

<h:outputScript name=" jsf.js " library=" javax.faces " target="head"/>

The <h:outputScript> tag renders a <script> markup element referring to the jsf.js JavaScript file in the javax.faces library (which follows the new resource management of JSF, meaning that the jsf.js file is under the META-INF/resources/javax/faces directory). Note that the top-level javax namespace is registered within the OpenAjax Alliance. This JavaScript API is used to initiate client-side interactions with JSF including partial tree traversal and partial page update. The function that we will be directly using in our pages is the request function, as it is responsible for sending an Ajax request to the server. Its signature is as follows:

jsf.ajax.request(ELEMENT, |event|, { |OPTIONS| });

ELEMENT is any JSF component or XHTML element from which you trigger the event. Typically, for submitting a form, the element would be a button. EVENT is any JavaScript event supported by that element, such as onmousedown, onclick, onblur, and so forth. The OPTIONS argument is an array that may contain the following name/value pairs:

• execute:'<space-separated list of UI component IDs>': Sends the list of component IDs to the server in order to be processed during the execute phase of the request.
• render:'<space-separated list of UI component IDs>': Renders the list of component IDs that have been processed during the render phase of the request.

As an example, the following code shows a button that calls asynchronously the doCreateBook method passing all the parameters of a book form. The button calls the jsf.ajax.request function when the user clicks it (onclick event). The this argument refers to the element itself (the button), and the options refer to components IDs (isbn, title, price . . .):

<h:commandButton value="Create a book" onclick =" jsf.ajax.request ( this , event,
         { execute :'isbn title price description nbOfPage illustrations',
          render :'booklist'}); return false;"
         actionListener="#{bookController.doCreateBook}" />

When the client makes an Ajax request, the page life cycle on the server side stays the same (it goes through the same six phases). The key benefit is that the response is simply the return of a small chunk of data rather than a large HTML page to the browser. The Apply request phase determines whether the current request is a “partial request” or not, and the PartialViewContext object is used throughout the page’s life cycle. It contains methods and properties that pertain to partial request processing and partial response rendering. At the end of the life cycle, the Ajax response (or, strictly speaking, the partial response) is sent to the client during the Render response phase. It usually consists of XHTML, XML, or JSON that the client-side JavaScript will parse.

JSF 2 also includes a declarative approach that is intended to be more convenient and easier to use. This approach leverages the new <f:ajax> tag. Instead of manually coding the JavaScript for the Ajax request call, you can declaratively specify the same behavior without requiring any JavaScript code.

<h:commandButton value="Create a book" action="#{bookController.doCreateBook}">
    <f:ajax execute="@form" render=":booklist"/>
</h:commandButton>

In this example, render points to the component id we want to render back (the booklist component). The execute attribute refers to all the components that belong to the form. Table 11-5 shows all the possible values that the render and execute attribute can take.

Writing the Book Entity

I will not go into too much detail about Listing 11-15, as you should by now understand the code of the Book entity. Despite the JPA mapping and Bean Validation annotations, notice the named query, findAllBooks, that retrieves books from the database ordered by title.

Listing 11-15.  A Book Entity with a Named Query and Bean Validation Annotations

@Entity
@NamedQuery (name = " findAllBooks ", query = "SELECT b FROM Book b ORDER BY b.title DESC")
public class Book {
 
  @Id @GeneratedValue
  private Long id;
  @NotNull @Size(min = 4, max = 50)
  @Column(nullable = false)
  private String title;
  private Float price;
  @Column(length = 2000)
  private String description;
  private Integer nbOfPage;
  private Boolean illustrations;
 
  // Constructors, getters, setters
}

As you know, this entity also has to be packaged with a persistence.xml file, but in the interests of simplicity I won’t show it here (refer to Chapter 4).

Writing the BookEJB

Listing 11-16 represents a stateless session bean that exposes a no-interface view. This means that the client (i.e., the backing bean) doesn’t need an interface (local or remote) and can directly invoke the EJB. This EJB gets injected with a reference to an entity manager using @Inject. For that it needs a CDI DatabaseProducer similar to Listing 8-13 (not shown here, refer to Chapter 8). With this EntityManager it persists a Book entity (createBook() method), retrieves all the books from the database (using the findAllBooks named query), and finds a book by its identifier. Notice that the EJB is @Named, so it can be invoked from a JSF page (more on that later) and it defines a Datasource with the @DataSourceDefinition annotation. This EJB doesn’t need any deployment descriptor.

Listing 11-16.  A Stateless EJB That Creates and Retrieves Books

@Named
@Stateless
@DataSourceDefinition (name = "java:global/jdbc/lab11DS",
        className = "org.apache.derby.jdbc.EmbeddedDriver",
        url = "jdbc:derby:memory:lab11DB;create=true;user=app;password=app"
)
public class BookEJB {
 
  @Inject
  private EntityManager em;
 
  public Book createBook (Book book) {
    em.persist(book);
    return book;
  }
 
  public List<Book> findAllBooks () {
    return em.createNamedQuery("findAllBooks", Book.class).getResultList();
  }
 
  public Book findBookById (Long id) {
    return em.find(Book.class, id);
  }
}

Writing the BookController Backing Bean

One of the roles of a backing bean is to interact with other layers of the application (e.g., the EJB layer) or perform validation. The BookController in Listing 11-17 is annotated with @Named; therefore it can be used in the JSF pages. The second annotation, @RequestScoped, defines the life duration of the bean; it lasts for the duration of the request. This backing bean contains one attribute book that will be used by the pages. book is the object that will get mapped to the form (newBook.xhtml page), displayed in viewBook.xhtml and persisted to the database.

Listing 11-17.  The BookController Backing Bean Invoking the EJB

@Named
@RequestScoped
public class BookController {
 
  @Inject
  private BookEJB bookEJB;
  private Book book = new Book();
 
  public String doCreateBook () {
    bookEJB .createBook( book );
 
    FacesContext.getCurrentInstance().addMessage(null, ➥
            new FacesMessage(FacesMessage.SEVERITY_INFO, "Book created", ➥
            "The book" + book.getTitle() + " has been created with id=" + book.getId()));
 
    return " newBook.xhtml ";
  }
 
  public void doFindBookById () {
    book = bookEJB .findBookById(book.getId());
  }
 
  // Getters, setters
}

All the business processing (creating and retrieving books) is done through the BookEJB. The backing bean is injected with a reference to the EJB using the @Inject annotation and has two methods that will be invoked by the pages.

• doCreateBook(): This method allows book creation by invoking the stateless EJB and passing the book attribute. If the persist succeeds, an INFO message is displayed on the page. Then the method returns the name of the page it needs to navigate to.
• doFindBookById(): This method is used by the viewBook.xhtml page to retrieve a book by its identifier using the stateless EJB.

Listing 11-17 shows the BookController backing bean. All the getters and setters in this snippet of code have been omitted for better readability but are required for the attribute book.

Writing the layout.xhtml Template

Both pages newBook.xhtml and viewBook.xhtml use the same template (layout.xhtml defined in Listing 11-18). As you can see in Figure 11-8 the template has a title, a header with a <h:link> Create a book to navigate to the newBook.xhtml, and a <h:messages> tag to display error and informational messages, as well as a footer.

Listing 11-18.  The layout.xhtml Template Used by Both Pages

<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
        " http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd ">
<html xmlns=" http://www.w3.org/1999/xhtml "
      xmlns:ui=" http://xmlns.jcp.org/jsf/facelets "
      xmlns:h=" http://xmlns.jcp.org/jsf/html ">
 
<h:head>
  <title> <ui:insert name="title"> Default title</ui:insert></title>
</h:head>
<h:body>
  <h:link value="Create a book" outcome="newBook.xhtml"/>
 
  <h1> <ui:insert name="title"> Default title</ui:insert></h1>
  <hr/>
 
  < h:messages id=" errors " infoStyle="color:blue" warnStyle="color:orange" →
                                                 errorStyle="color:red"/>
 
  <ui:insert name="content"> Default content</ui:insert>
 
  <hr/>
  <h:outputText value="APress - Beginning Java EE 7" style="font-style: italic"/>
</h:body>
</html>

Writing the newBook.xhtml Page

The newBook.xhtml page is a single page that has a form at the top to enter the book data (title, price, description, number of pages, and illustrations), and a list of books at the bottom (see Figure 11-8). Each time a new book is created by clicking the button, the list is refreshed, showing the newly created book. Once the form is submitted, only the list portion of the page needs to be refreshed. For that we use Ajax.

The code in Listing 11-19 shows the top part of the page that represents the form. The bookController variable refers to the BookController backing bean responsible for all the business logic (see Listing 11-17). Book is the entity, and its attributes are accessed using expression language (#{bookController.book.title} binds to the title).

Listing 11-19.  The Top Part of the newBook.xhtml Page

<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
        " http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd ">
<html xmlns=" http://www.w3.org/1999/xhtml "
      xmlns:h=" http://xmlns.jcp.org/jsf/html "
      xmlns:ui=" http://xmlns.jcp.org/jsf/facelets "
      xmlns:f=" http://xmlns.jcp.org/jsf/core ">
 
<ui:composition template="layout.xhtml" >
 
  <ui:define name="title"> Create a new book</ui:define>
 
  <ui:define name="content">
 
    <h:form id="bookForm">
 
      <h:panelGrid columns="2">
        <h:outputLabel value="Title : "/>
        <h:inputText value=" #{bookController.book.title} "/>
 
        <h:outputLabel value="Price : "/>
        <h:inputText value="#{bookController.book.price}"/>
 
        <h:outputLabel value="Description : "/>
        <h:inputTextarea value="#{bookController.book.description}" cols="16" rows="3"/>
 
        <h:outputLabel value="Number of pages : "/>
        <h:inputText value="#{bookController.book.nbOfPage}"/>
 
        <h:outputLabel value="Illustrations : "/>
        <h:selectBooleanCheckbox value="#{bookController.book.illustrations}"/>
      </h:panelGrid>
 
      < h:commandButton value="Create a book" action=" #{bookController.doCreateBook} ">
        <f:ajax execute="@form" render=":booklist :errors"/>
      </h:commandButton>
 
    </h:form>
    ...

The <h:commandButton> tag represents the button where the Ajax call is made. When the user clicks, the <f:ajax> tag passes all the form parameters using the @form shortcut (instead, it could have passed a list of all the components identifiers). The values of all the UI components that make up the form are then posted to the server. The doCreateBook() method of the backing bean is invoked, the new book is persisted, and the list of books is retrieved. If no exception is thrown, the name of the page to navigate to is returned: newBook.xhtml so the user stays on the same page. The rendering of this list on the client side is made asynchronously thanks to Ajax. The render element refers to the booklist ID as the identifier of the data table displaying all the books (see Listing 11-20) but also the errors ID which is defined in the layout.xhtml page (see Listing 11-18) in case a message needs to be displayed.

Listing 11-20.  The Bottom Part of the newBook.xhtml Page

    ...
    <hr/>
    <h1>List of books</h1>
 
    <h:dataTable id=" booklist " value=" #{bookEJB.findAllBooks()} " var="bk" border="1">
 
      <h:column>
        <f:facet name="header">
          <h:outputText value="Title"/>
        </f:facet>
        <h:link outcome="viewBook.xhtml?id=#{bk.id}" value="#{bk.title}"/>
      </h:column>
 
      <h:column>
        <f:facet name="header">
          <h:outputText value="Price"/>
        </f:facet>
        <h:outputText value="#{bk.price}"/>
      </h:column>
 
    </h:dataTable>
  </ui:define>
 
</ui:composition>
</html>

Listing 11-20 shows the bottom part of the page. To display the list of all books, the page uses a <h:dataTable> whose values come straight from the BookEJB (instead of the BookController) thanks to the @Named annotation (see Listing11-16). The <h:dataTable> tag binds to the bookEJB.findAllBooks() method that returns a List<Book> and declares the variable bk to iterate through the list. Then, inside the <h:dataTable> tag, you can use expressions such as #{bk.price} to get the price attribute of a book and display. The <h:link> tag creates an HTML link that, when clicked, navigates to the viewBook.xhtml passing the identifier of the book (viewBook.xhtml?id=#{bk.id}).

Writing the viewBook.xhtml Page

The viewBook.xhtml page allows you to view the details of a book (title, price, description, number of pages, and illustrations). It uses the bookmarkability functionality of JSF 2, meaning that you can access any book detail just by changing the URL with an HTTP GET, thanks to ViewAction.

You can see in Listing 11-21 that the page binds the id parameter (e.g., viewBook.xhtml?id=123) to the #{bookController.book.id} attribute. Once the identifier is bound, the action #{bookController.doFindBookById} is invoked. The BookController.doFindBookById method (Listing 11-17) calls the EJB and gets the book from the database, and then the page can bind the book attributes (e.g., #{bookController.book.title}) to output text components.

Listing 11-21.  The viewBook.xhtml Page

<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
        " http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd ">
<html xmlns=" http://www.w3.org/1999/xhtml "
      xmlns:h=" http://xmlns.jcp.org/jsf/html "
      xmlns:ui=" http://xmlns.jcp.org/jsf/facelets "
      xmlns:f=" http://xmlns.jcp.org/jsf/core ">
 
<ui:composition template="layout.xhtml" >
 
  <f:metadata>
    <f:viewParam name="id" value="#{bookController.book.id}"/>
    <f:viewAction action="#{bookController.doFindBookById}"/>
  </f:metadata>
 
  <ui:define name="title"> View a book</ui:define>
 
  <ui:define name="content">
 
    <h:panelGrid columns="2">
      <h:outputLabel value="Title : "/>
      <h:outputText value=" #{bookController.book.title} "/>
 
      <h:outputLabel value="Price : "/>
      <h:outputText value="#{bookController.book.price}"/>
 
      <h:outputLabel value="Description : "/>
      <h:outputText value="#{bookController.book.description}" cols="16" rows="3"/>
 
      <h:outputLabel value="Number of pages : "/>
      <h:outputText value="#{bookController.book.nbOfPage}"/>
 
      <h:outputLabel value="Illustrations : "/>
      <h:selectBooleanCheckbox value="#{bookController.book.illustrations}"/>
    </h:panelGrid>
 
  </ui:define>
 
</ui:composition>
</html>

Compiling and Packaging with Maven

The web application needs to be compiled and packaged in a war file (<packaging>war</packaging>). The pom.xml shown in Listing 11-22 declares all the dependencies necessary for compiling code (glassfish-embedded-all) and uses version 1.7 of the JDK.

Listing 11-22.  Maven pom.xml File for Compiling and Packaging the Web Application

<?xml version="1.0" encoding="UTF-8"?>
<project xmlns=" http://maven.apache.org/POM/4.0.0 " →
         xmlns:xsi=" http://www.w3.org/2001/XMLSchema-instance " →
         xsi:schemaLocation=" http://maven.apache.org/POM/4.0.0 →
         http://maven.apache.org/xsd/maven-4.0.0.xsd ">
  <modelVersion>4.0.0</modelVersion>
 
  <parent>
    <artifactId>chapter11</artifactId>
    <groupId>org.agoncal.book.javaee7</groupId>
    <version>1.0</version>
  </parent>
 
  <groupId>org.agoncal.book.javaee7.chapter11</groupId>
  <artifactId>chapter11</artifactId>
  <version>1.0</version>
  <packaging>war</packaging>
 
  <dependencies>
    <dependency>
      <groupId>org.glassfish.main.extras</groupId>
      <artifactId> glassfish-embedded-all </artifactId>
      <version>4.0</version>
      <scope>provided</scope>
    </dependency>
  </dependencies>
 
  <build>
    <plugins>
      <plugin>
        <artifactId>maven-compiler-plugin</artifactId>
        <version>2.5.1</version>
        <configuration>
          <source> 1.7 </source>
          <target>1.7</target>
        </configuration>
      </plugin>
      <plugin>
        <artifactId>maven-war-plugin</artifactId>
        <version>2.2</version>
        <configuration>
          <failOnMissingWebXml>false</failOnMissingWebXml>
        </configuration>
      </plugin>
    </plugins>
  </build>
</project>

To compile and package the classes, open a command-line interpreter in the directory that contains the pom.xml file and enter the following Maven command:

$ mvn package

Go to the target directory to find the chapter11-1.0.war file. Open it, and you will see that it contains the Book entity, the BookEJB, the BookController backing bean, the three deployment descriptors (persistence.xml, faces-config.xml, and beans.xml), and the two web pages (newBook.xhtml and viewBook.xhtml).

Deploying on GlassFish

Once you have packaged the web application, it needs to be deployed into GlassFish. Ensure GlassFish is up and running. Open a command line, go to the target directory where the chapter11-1.0.war file is located, and enter the following:

$ asadmin deploy chapter11-1.0.war

If the deployment is successful, the following command should return the name of the deployed application and its type. There are two types: web, because it’s a web application, and ejb, because the application contains an EJB.

$ asadmin list-components
chapter11-1.0 <ejb, web>

Running the Example

Now that the application is deployed, open your browser and go to the following URL:

http://localhost:8080/chapter11-1.0/newBook.faces

The browser is pointing to newBook.faces, not newBook.xhtml, because of the default mapping of the FacesServlet. With the .faces extension, JSF knows it has to process the page before rendering it. Once the newBook page shows up, enter some data, and click the submit button. The book is persisted in the database and appears in the list at the bottom of the page.

If you take a web developer tool to check what happens on the network between the browser and GlassFish, you’ll see Ajax in action. The rendering is a partial XML response instead of the entire HTML page. The partial response from the server contains the XHTML portion of the page to be updated. The JavaScript looks for the errors and booklist elements of the page and applies the changes needed (updating the DOM). The partial response on Listing 11-23 is self-explanatory; it specifies that an update has to be made to the components identified by errors and booklist (<update id="booklist">). The body of the <update> element is the fragment of XHTML that has to override the actual data table. Of course, this XML is handled automatically by the JSF Ajax handlers—the developer doesn’t need to do anything with it manually.

Listing 11-23.  The Partial Response Received by the Browser

<?xml version='1.0' encoding='UTF-8'?>
<partial-response>
  <changes>
    <update id="errors">
      <![CDATA[
      <ul id="errors"><li style="color:blue">Book created</li></ul>
      ]]>
    </update>
    <update id="booklist">
      <![CDATA[
      <table id="booklist" border="1">
        <thead>
          <tr>
            <th scope="col">Title</th>
            <th scope="col">Price</th>
          </tr>
        </thead>
        <tbody>
          <tr>
            <td><a href="/chapter11-1.0/viewBook.faces?id=54">Java EE 6</a></td>
            <td>31.49</td>
          </tr>
          <tr>
            <td><a href="/chapter11-1.0/viewBook.faces?id=1">Harry Potter </a></td>
            <td>19.79</td>
          </tr>
          <tr>
            <td><a href="/chapter11-1.0/viewBook.faces?id=51">H2G2</a></td>
            <td>23.99</td>
          </tr>
        </tbody>
      </table>
      ]]>
    </update>
  </changes>
</partial-response>