Document Information


Part I Introduction

1.  Overview

2.  Using the Tutorial Examples

Part II The Web Tier

3.  Getting Started with Web Applications

4.  JavaServer Faces Technology

5.  Introduction to Facelets

6.  Expression Language

7.  Using JavaServer Faces Technology in Web Pages

8.  Using Converters, Listeners, and Validators

9.  Developing with JavaServer Faces Technology

10.  JavaServer Faces Technology: Advanced Concepts

11.  Using Ajax with JavaServer Faces Technology

12.  Composite Components: Advanced Topics and Example

13.  Creating Custom UI Components and Other Custom Objects

14.  Configuring JavaServer Faces Applications

15.  Java Servlet Technology

16.  Uploading Files with Java Servlet Technology

17.  Internationalizing and Localizing Web Applications

Part III Web Services

18.  Introduction to Web Services

19.  Building Web Services with JAX-WS

20.  Building RESTful Web Services with JAX-RS

21.  JAX-RS: Advanced Topics and Example

Part IV Enterprise Beans

22.  Enterprise Beans

23.  Getting Started with Enterprise Beans

24.  Running the Enterprise Bean Examples

25.  A Message-Driven Bean Example

26.  Using the Embedded Enterprise Bean Container

27.  Using Asynchronous Method Invocation in Session Beans

Part V Contexts and Dependency Injection for the Java EE Platform

28.  Introduction to Contexts and Dependency Injection for the Java EE Platform

29.  Running the Basic Contexts and Dependency Injection Examples

30.  Contexts and Dependency Injection for the Java EE Platform: Advanced Topics

31.  Running the Advanced Contexts and Dependency Injection Examples

Part VI Persistence

32.  Introduction to the Java Persistence API

33.  Running the Persistence Examples

The order Application

Entity Relationships in the order Application

Self-Referential Relationships

One-to-One Relationships

One-to-Many Relationship Mapped to Overlapping Primary and Foreign Keys

Unidirectional Relationships

Primary Keys in the order Application

Generated Primary Keys

Compound Primary Keys

Entity Mapped to More Than One Database Table

Cascade Operations in the order Application

BLOB and CLOB Database Types in the order Application

Temporal Types in the order Application

Managing the order Application's Entities

Creating Entities

Finding Entities

Setting Entity Relationships

Using Queries

Removing Entities

Running the order Example

To Run the order Example Using NetBeans IDE

To Run the order Example Using Ant

The all Task

The roster Application

Relationships in the roster Application

The Many-To-Many Relationship in roster

Entity Inheritance in the roster Application

Criteria Queries in the roster Application

Metamodel Classes in the roster Application

Obtaining a CriteriaBuilder Instance in RequestBean

Creating Criteria Queries in RequestBean's Business Methods

Automatic Table Generation in the roster Application

Running the roster Example

To Run the roster Example Using NetBeans IDE

To Run the roster Example Using Ant

The all Task

34.  The Java Persistence Query Language

35.  Using the Criteria API to Create Queries

36.  Creating and Using String-Based Criteria Queries

37.  Controlling Concurrent Access to Entity Data with Locking

38.  Using a Second-Level Cache with Java Persistence API Applications

Part VII Security

39.  Introduction to Security in the Java EE Platform

40.  Getting Started Securing Web Applications

41.  Getting Started Securing Enterprise Applications

42.  Java EE Security: Advanced Topics

Part VIII Java EE Supporting Technologies

43.  Introduction to Java EE Supporting Technologies

44.  Transactions

45.  Resources and Resource Adapters

46.  The Resource Adapter Example

47.  Java Message Service Concepts

48.  Java Message Service Examples

49.  Bean Validation: Advanced Topics

50.  Using Java EE Interceptors

Part IX Case Studies

51.  Duke's Bookstore Case Study Example

52.  Duke's Tutoring Case Study Example

53.  Duke's Forest Case Study Example



The address-book Application

The address-book example application is a simple web application that stores contact data. It uses a single entity class, Contact, that uses the Java API for JavaBeans Validation (Bean Validation) to validate the data stored in the persistent attributes of the entity, as described in Validating Persistent Fields and Properties.

Bean Validation Constraints in address-book

The Contact entity uses the @NotNull, @Pattern, and @Past constraints on the persistent attributes.

The @NotNull constraint marks the attribute as a required field. The attribute must be set to a non-null value before the entity can be persisted or modified. Bean Validation will throw a validation error if the attribute is null when the entity is persisted or modified.

The @Pattern constraint defines a regular expression that the value of the attribute must match before the entity can be persisted or modified. This constraint has two different uses in address-book.

  • The regular expression declared in the @Pattern annotation on the email field matches email addresses of the form name@domain level domain, allowing only valid characters for email addresses. For example, will pass validation, as will However, firstname,, which contains an illegal comma character in the local name, will fail validation.

  • The mobilePhone and homePhone fields are annotated with a @Pattern constraint that defines a regular expression to match phone numbers of the form (xxx) xxxxxxx.

The @Past constraint is applied to the birthday field, which must be a java.util.Date in the past.

Here are the relevant parts of the Contact entity class:

public class Contact implements Serializable {
    private static final long serialVersionUID = 1L;
    @GeneratedValue(strategy = GenerationType.AUTO)
    private Long id;
    protected String firstName;
    protected String lastName;
    protected String email;
    @Pattern(regexp="^\\(?(\\d{3})\\)?[- ]?(\\d{3})[- ]?(\\d{4})$",
    protected String mobilePhone;
    @Pattern(regexp="^\\(?(\\d{3})\\)?[- ]?(\\d{3})[- ]?(\\d{4})$",
    protected String homePhone;
    protected Date birthday;

Specifying Error Messages for Constraints in address-book

Some of the constraints in the Contact entity specify an optional message:

@Pattern(regexp="^\\(?(\\d{3})\\)?[- ]?(\\d{3})[- ]?(\\d{4})$",
    protected String homePhone;

The optional message element in the @Pattern constraint overrides the default validation message. The message can be specified directly:

@Pattern(regexp="^\\(?(\\d{3})\\)?[- ]?(\\d{3})[- ]?(\\d{4})$",
             message="Invalid phone number!")
    protected String homePhone;

The constraints in Contact, however, are strings in the resource bundle tut-install/examples/persistence/address-book/src/java/ This allows the validation messages to be located in one single properties file and the messages to be easily localized. Overridden Bean Validation messages must be placed in a resource bundle properties file named in the default package, with localized resource bundles taking the form For example, is the resource bundle used in Spanish speaking locales.

Validating Contact Input from a JavaServer Faces Application

The address-book application uses a JavaServer Faces web front end to allow users to enter contacts. While JavaServer Faces has a form input validation mechanism using tags in Facelets XHTML files, address-book doesn’t use these validation tags. Bean Validation constraints in JavaServer Faces managed beans, in this case in the Contact entity, automatically trigger validation when the forms are submitted.

The following code snippet from the Create.xhtml Facelets file shows some of the input form for creating new Contact instances:

    <table columns="3" role="presentation">
            <td><h:outputLabel value="#{bundle.CreateContactLabel_firstName}" 
                               for="firstName" /></td>
            <td><h:inputText id="firstName" 
                             title="#{bundle.CreateContactTitle_firstName}" /></td>
            <td><h:message for="firstName" /></td>
            <td><h:outputLabel value="#{bundle.CreateContactLabel_lastName}" 
                               for="lastName" /></td>
            <td><h:inputText id="lastName" 
                             title="#{bundle.CreateContactTitle_lastName}" /></td>
            <td><h:message for="lastName" /></td>

The <h:inputText> tags firstName and lastName are bound to the attributes in the Contact entity instance selected in the ContactController stateless session bean. Each <h:inputText> tag has an associated <h:message> tag that will display validation error messages. The form doesn’t require any JavaServer Faces validation tags, however.

Running the address-book Example

You can use either NetBeans IDE or Ant to build, package, deploy, and run the address-book application.

To Run the address-book Example Using NetBeans IDE

  1. From the File menu, choose Open Project.
  2. In the Open Project dialog, navigate to:
  3. Select the address-book folder.
  4. Select the Open as Main Project and Open Required Projects check boxes.
  5. Click Open Project.
  6. In the Projects tab, right-click the address-book project and select Run.

    After the application has been deployed, a web browser window appears at the following URL:

  7. Click Show All Contact Items, then Create New Contact. Type values in the form fields; then click Save.

    If any of the values entered violate the constraints in Contact, an error message will appear in red beside the form field with the incorrect values.

To Run the address-book Example Using Ant

  1. In a terminal window, go to:
  2. Type the following command:

    This will compile and assemble the address-book application.

  3. Type the following command:
    ant deploy

    This will deploy the application to GlassFish Server.

  4. Open a web browser window and type the following URL:

    Tip - As a convenience, the all task will build, package, deploy, and run the application. To do this, type the following command:

    ant all

  5. Click Show All Contact Items, then Create New Contact. Type values in the form fields; then click Save.

    If any of the values entered violate the constraints in Contact, an error message will appear in red beside the form field with the incorrect values.