// 
//     Licensed to the Apache Software Foundation (ASF) under one
//     or more contributor license agreements.  See the NOTICE file
//     distributed with this work for additional information
//     regarding copyright ownership.  The ASF licenses this file
//     to you under the Apache License, Version 2.0 (the
//     "License"); you may not use this file except in compliance
//     with the License.  You may obtain a copy of the License at
// 
//       http://www.apache.org/licenses/LICENSE-2.0
// 
//     Unless required by applicable law or agreed to in writing,
//     software distributed under the License is distributed on an
//     "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
//     KIND, either express or implied.  See the License for the
//     specific language governing permissions and limitations
//     under the License.
//

= Generating a JavaServer Faces 2.x CRUD Application from a Database
:jbake-type: tutorial
:jbake-tags: tutorials 
:jbake-status: published
:icons: font
:syntax: true
:source-highlighter: pygments
:toc: left
:toc-title:
:description: Generating a JavaServer Faces 2.x CRUD Application from a Database - Apache NetBeans
:keywords: Apache NetBeans, Tutorials, Generating a JavaServer Faces 2.x CRUD Application from a Database

In this tutorial, you will use the NetBeans IDE to create a web application that interacts with a back-end database. The application provides you with the ability to view and modify data contained in the database - otherwise referred to as _CRUD_ (Create, Read, Update, Delete) functionality. The application that you will develop relies on the following technologies.

* *JavaServer Faces (JSF) 2.x* for front-end web pages, validation handling, and management of the request-response cycle.
* *Java Persistence API (JPA) 2.0* using EclipseLink to generate entity classes from the database, and manage transactions. (EclipseLink is the reference implementation for JPA, and is the default persistence provider for the GlassFish server.)
* *Enterprise JavaBeans (EJB) 3.1*, which provides you with stateless EJBs that access the entity classes, and contain the business logic for the application.

The IDE provides two wizards which generate all of the code for the application. The first is the <<generateEntity,Entity Classes from Database wizard>> which enables you to generate entity classes from the provided database. After you create entity classes, you use the <<jsfPagesEntityClasses,JSF Pages from Entity Classes wizard>> to create JSF managed beans and EJBs for the entity classes, as well as a set of Facelets pages to handle the views for entity class data. The final section of the tutorial, <<explore,Exploring the Application>>, is optional, and provides numerous exercises to help you to better understand the application and become more familiar with the IDE.

image::images/netbeans-stamp-80-74-73.png[title="Content on this page applies to the NetBeans IDE 7.2, 7.3, 7.4 and 8.0"]


==== Contents

* <<createDB,Creating the Database>>
* <<examineDB,Examining the Database Structure>>
* <<createProject,Creating the Web Application Project>>
* <<generateEntity,Generating the Entity Classes from the Database>>
* <<jsfPagesEntityClasses,Generating JSF Pages From Entity Classes>>
* <<explore,Exploring the Application>>
* <<completedProject,Examining the Completed Project>>
* <<populateDB,Populating the Database with an SQL Script>>
* <<editorSupport,Exploring Editor Support in Facelets Pages>>
* <<dbIntegrity,Exploring Database Integrity with Field Validation>>
* <<editEntity,Editing Entity Classes>>
* <<troubleshooting,Troubleshooting>>
* <<seeAlso,See Also>>

To complete this tutorial, you need the following software and resources.

|===
|Software or Resource |Version Required 

|link:https://netbeans.org/downloads/index.html[+NetBeans IDE+] |7.2, 7.3, 7.4, 8.0, Java EE bundle 

|link:http://www.oracle.com/technetwork/java/javase/downloads/index.html[+Java Development Kit (JDK)+] |7 or 8 

|link:http://glassfish.dev.java.net/[+GlassFish Server Open Source Edition+] |3.x, 4.x 

|link:https://netbeans.org/projects/samples/downloads/download/Samples%252FJavaEE%252Fmysql-consult.zip[+mysql-consult.zip+] (MySQL) 
_or_
link:https://netbeans.org/projects/samples/downloads/download/Samples%252FJavaEE%252Fjavadb-consult.zip[+javadb-consult.zip+] (JavaDB) |n/a 
|===

*Notes:*

* The NetBeans IDE Java EE bundle also includes the GlassFish server, a Java EE-compliant server, which you require for this tutorial.
* For the solution project to this tutorial, download link:https://netbeans.org/projects/samples/downloads/download/Samples%252FJavaEE%252FConsultingAgencyJSF20.zip[+ConsultingAgencyJSF20.zip+].


[[createDB]]
== Creating the Database

This tutorial uses a consulting agency database called `consult`. The database is not included when you install the IDE so you need to first create the database to follow this tutorial.

The `consult` database was designed to demonstrate the scope of IDE support for handling a variety of database structures. The database is thus not intended as an example of recommended database design or best-practice. Instead, it attempts to incorporate many of the relevant features that are potentially found in a database design. For example, the `consult` database contains all possible relationship types, composite primary keys, and many different data types. See the tables below for a more detailed overview of the database structure.

*Notes:*

* This tutorial uses the MySQL database server but you can also complete the tutorial using the JavaDB database server. To create the database in JavaDB, download and extract the link:https://netbeans.org/projects/samples/downloads/download/Samples%252FJavaEE%252Fjavadb-consult.zip[+javadb-consult.zip+] archive. The archive contains SQL scripts for creating, dropping, and populating the `consult` database.
* For more information on configuring the IDE to work with MySQL, see the link:../ide/mysql.html[+Connecting to a MySQL Database+] tutorial.
* For more information on configuring the IDE to work with JavaDB, see the link:../ide/java-db.html[+Working with the Java DB (Derby) Database+] tutorial.

*MySQL with GlassFish Combination:*

If you are using MySQL, and are using GlassFish v3 or Open Source Edition 3.0.1, you must ensure that your database is password-protected. (For more information, see GlassFish link:https://java.net/jira/browse/GLASSFISH-12221[+Issue 12221+].) If you are using the default MySQL `root` account with an empty password, you can set the password from a command-line prompt. 

For example, to set your password to `_nbuser_`, in a command-line prompt enter the following commands.


[source,java]
----

shell> mysql -u root
mysql> UPDATE mysql.user SET Password = PASSWORD('_nbuser_') WHERE User = 'root';
mysql> FLUSH PRIVILEGES;
----

If you receive a '`mysql: command not found`' error, then the `mysql` command has not been added to your `PATH` environment variable. You can instead call the command by entering the full path to your MySQL installation's `bin` directory. For example, if the `mysql` command is located on your computer at `/usr/local/mysql/bin`, enter the following:


[source,java]
----

shell> /usr/local/mysql/bin/mysql -u root
----

For more information, see the offical MySQL Reference Manual:

* link:http://dev.mysql.com/doc/refman/5.1/en/default-privileges.html[+Securing the Initial MySQL Accounts+]
* link:http://dev.mysql.com/doc/refman/5.1/en/invoking-programs.html[+4.2.1. Invoking MySQL Programs+]
* link:http://dev.mysql.com/doc/refman/5.1/en/setting-environment-variables.html[+4.2.4. Setting Environment Variables+]


Perform the following steps to create a database and connect to it from the IDE.

1. Download link:https://netbeans.org/projects/samples/downloads/download/Samples%252FJavaEE%252Fmysql-consult.zip[+mysql-consult.zip+] and extract the archive to your local system. When you extract the archive you will see the SQL scripts for creating and populating the database. The archive also has scripts for dropping tables.
2. In the Services window, expand the Databases node, right-click the MySQL node and choose Start Server.
3. Right-click the MySQL Server node and choose Create Database.
4. Type *consult* as the Database Name in the Create MySQL Database dialog. Click OK. A new node appears under the Databases node (`jdbc:mysql://localhost:3306/consult [root on Default schema]`).
5. Right-click the new node and choose Connect.
6. Choose File > Open File from the main menu and navigate to the extracted file `mysql_create_consult.sql`. Click Open. The file automatically opens in the SQL editor. 
image::images/run-sql-script.png[title="Open SQL files in the IDE's editor"]
7. Make sure that the `consult` database is selected in the Connection drop-down list in the SQL editor toolbar, then click the Run SQL ( image::images/run-sql-btn.png[] ) button.

When you click Run SQL, the following output appears in the Output window.

image::images/run-sql-output.png[title="Output window provides information on SQL execution"]


[[examineDB]]
== Examining the Database Structure

To confirm that the tables were created correctly, expand the Tables node under the database connection node. You can expand a table node to see the table columns, indexes and any foreign keys. You can right-click a column and choose Properties to view additional information about the column.

image::images/services-window-tables.png[title="Services window displays database connections, tables, table columns, indexes, and foreign keys"]

*Note:* If you do not see any tables under the Tables node, right-click the Tables node and choose Refresh.

Looking at the structure of the `consult` database, you can see that the database contains tables that have a variety of relationships and various field types. When creating entity classes from a database, the IDE automatically generates the appropriate code for the various field types.

image::images/diagram_consult.png[title="Entity-relationship diagram of consult database"]

The following table describes the tables found in the `consult` database.

|===
|Database Table |Description |Design Features 

|CLIENT |A client of the consulting agency |Non-generated, composite primary key (whose fields do not constitute a foreign key) 

|CONSULTANT |An employee of the consulting agency whom clients can hire on a contract basis |Includes a resume field of type LONG VARCHAR 

|CONSULTANT_STATUS |A consultant's status with the consulting agency (for example, Active and Inactive are possible statuses) |Non-generated primary key of type CHAR 

|RECRUITER |An employee of the consulting agency responsible for connecting clients and consultants |  

|PROJECT |A project that a client staffs with consultants of the consulting agency |Non-generated, composite primary key that includes two fields constituting a foreign key to the CLIENT table 

|BILLABLE |A set of hours worked by a consultant on a project, for which the consulting agency bills the relevant client |Includes an artifact field of type CLOB 

|ADDRESS |A client's billing address |  

|PROJECT_CONSULTANT |Join table indicating which consultants are currently assigned to which projects |Cross-references PROJECT and CONSULTANT, the former having a composite primary key 
|===


The `consult` database includes a variety of relationships. When creating entity classes from a database, the IDE automatically generates the properties of the appropriate Java type based on the SQL type of the columns. The following table describes the entity relationships for the `consult` database. (Inverse relationships are not shown.)

|===
|Entity |Related Entity |Relationship Information |Description 

|CLIENT |RECRUITER |nullable one-to-one with manual editing; nullable one-to-many if not edited |CLIENT has many RECRUITERs and RECRUITER has zero or one CLIENT (if not manually edited) 

|CLIENT |ADDRESS |non-nullable one-to-one |CLIENT has one ADDRESS and ADDRESS has zero or one CLIENT 

|CLIENT |PROJECT |non-nullable one-to-many; in a Project entity, the value of the client field is part of the Project's primary key |CLIENT has many PROJECTs and PROJECT has one CLIENT 

|CONSULTANT |PROJECT |many-to-many |CONSULTANT has many PROJECTs and PROJECT has many CONSULTANTs 

|CONSULTANT |BILLABLE |non-nullable one-to-many |CONSULTANT has many BILLABLEs and BILLABLE has one CONSULTANT 

|CONSULTANT_STATUS |CONSULTANT |non-nullable one-to-many |CONSULTANT_STATUS has many CONSULTANTs and CONSULTANT has one CONSULTANT_STATUS 

|CONSULTANT |RECRUITER |nullable one-to-many |CONSULTANT has zero or one RECRUITER and RECRUITER has many CONSULTANTs 

|BILLABLE |PROJECT |non-nullable one-to-many |BILLABLE has one PROJECT and PROJECT has many BILLABLEs 
|===

Now that the database is created, you can create the web application and use the Entity Classes from Database wizard to generate entity classes based on the database tables.


[[createProject]]
== Creating the Web Application Project

In this exercise you create a web project and add the JavaServer Faces framework to the project. When you create the project, you will select JavaServer Faces in the Frameworks panel of the New Project wizard.

1. Choose File > New Project (Ctrl-Shift-N; ⌘-Shift-N on Mac) from the main menu.
2. Select Web Application from the Java Web category. Click Next.
3. Type `ConsultingAgency` for the project name and set the project location. Click Next.
4. Set the server to GlassFish and set the Java EE Version to Java EE 6 Web or Java EE 7 Web. Click Next.
5. In the Frameworks panel, select the JavaServer Faces option. Click Finish.

When you click Finish, the IDE generates the web application project and opens `index.xhtml` in the editor.


[[generateEntity]]
== Generating the Entity Classes from the Database

After connecting to a database in the IDE, you can use the Entity Classes from Database wizard to quickly generate entity classes based on the tables in the database. The IDE can generate entity classes for each table that you select, and can also generate any necessary entity classes for related tables.

1. In the Projects window, right-click the `ConsultingAgency` project node, and choose New > Entity Classes from Database. (If this option is not listed, choose Other. Then, in the File wizard, select the Persistence category, then Entity Classes from Database.)
2. Select New Data Source from the Data Source drop-down list to open the Create Data Source dialog.
3. Type `jdbc/consult` as the JNDI Name and select the `jdbc:mysql://localhost:3306/consult` connection as the Database Connection. 
image::images/create-datasource.png[title="Specify a JNDI name and database connection to create a datasource"]
4. Click OK to close the dialog box and return to the wizard. The tables in the `consult` database appear in the Available Tables listbox.
5. Click the Add All button to select all tables contained in the database. Click Next. 
image::images/new-entities-wizard.png[]
6. Type `jpa.entities` as the Package name.
7. Confirm that the checkboxes to generate named queries and create a persistence unit are selected. Click Finish.

When you click Finish, the IDE generates the entity classes in the `jpa.entities` package of the project.

When using the wizard to create entity classes from a database, the IDE examines the relationships between database tables. In the Projects window, if you expand the `jpa.entities` package node, you can see that the IDE generated an entity class for each table except for the `PROJECT_CONSULTANT` table. The IDE did not create an entity class for `PROJECT_CONSULTANT` because the table is a join table.

image::images/projects-window-entities.png[title="screenshot of Projects window showing generated entity classes"]

The IDE also generated two additional classes for the tables with composite primary keys: `CLIENT` and `PROJECT`. The primary key classes for these tables (`ClientPK.java` and `ProjectPK.java`) have `PK` appended to the name.

If you look at the generated code for the entity classes you can see that the wizard added `@GeneratedValue` annotations to the auto-generated ID fields and `@Basic(optional = "false")` annotations to some of the fields in the entity classes. Based on the `@Basic(optional = "false")` annotations, the JSF Pages from Entity Classes wizard can generate code that includes checks to prevent non-nullable column violations for those fields.


[[jsfPagesEntityClasses]]
== Generating JSF Pages From Entity Classes

Now that the entity classes are created, you can create the web interface for displaying and modifying the data. You will use the JSF Pages from Entity Classes wizard to generate JavaServer Faces pages. The code generated by the wizard is based on persistence annotations contained in the entity classes.

For each entity class the wizard generates the following files.

* a stateless session bean that extends  ``AbstractFacade.java`` 
* a JSF session-scoped, managed bean
* a directory containing four Facelets files for CRUD capabilities (`Create.xhtml`, `Edit.xhtml`, `List.xhtml`, and `View.xhtml`)

The wizard also generates the following files.

* the  ``AbstractFacade.java``  class that contains the business logic for creation, retrieval, modification and removal of entity instances
* utility classes used by the JSF managed beans (`JsfUtil`, `PaginationHelper`)
* a properties bundle for localized messages, and a corresponding entry in the project's Faces configuration file (A `faces-config.xml` file is created if one does not already exist.)
* auxiliary web files, including a default stylesheet for rendered components, and a Facelets template file

To generate the JSF pages:

1. In the Projects window, right-click the project node and choose New > JSF Pages from Entity Classes to open the wizard. (If this option is not listed, choose Other. Then, in the File wizard, select the JavaServer Faces category, then JSF Pages from Entity Classes.)

The Available Entity Classes box lists the seven entity classes contained in the project. The box does not list the embeddable classes (`ClientPK.java` and `ProjectPK.java`).

2. Click Add All to move all the classes to the Selected Entity Classes box. 
image::images/newjsf-wizard.png[title="New JSF Pages from Entity Classes wizard displays all entity classes contained in project"] 
Click Next.
3. In Step 3 of the wizard, Generate JSF Pages and Classes, type `jpa.session` for the JPA Session Bean Package.
4. Type `jsf` for the JSF Classes Package.
5. Enter '`/resources/Bundle`' into the Localization Bundle Name field. This will generate a package named `resources` which the `Bundle.properties` file will reside in. (If you leave this blank, the properties bundle will be created in the project's default package.) 
image::images/newjsf-wizard2.png[title="Specify package and folder names for generated files"]

To let the IDE better accommodate your project conventions, you can customize any files generated by the wizard. Click the Customize Template link to modify the file templates used by the wizard. 
image::images/customize-template.png[title="Customize templates for files generated by the wizard"] 
In general, you can access and make changes to all templates maintained by the IDE using the Template Manager (Tools > Templates).

6. Click Finish. The IDE generates the stateless session beans in the `jpa.session` package, and the JSF session-scoped, managed beans in the `jsf` package. Each stateless session bean handles the operations for the corresponding entity class, including creating, editing, and destroying instances of the entity class via the Java Persistence API. Each JSF managed bean implements the `javax.faces.convert.Converter` interface and performs the work of converting instances of the corresponding entity class to `String` objects and vice versa.

If you expand the Web Pages node, you can see that the IDE generated a folder for each of the entity classes. Each folder contains the files `Create.xhtml`, `Edit.xhtml`, `List.xhtml` and `View.xhtml`. The IDE also modified the `index.xhtml` file by inserting links to each of the `List.xhtml` pages.

image::images/projects-jsfpages.png[title="Facelets pages for each entity class are generated by the wizard"]

Each JSF managed bean is specific to the four corresponding Facelets files and includes code that invokes methods in the appropriate session bean.

Expand the `resources` folder node to locate the default `jsfcrud.css` stylesheet that was generated by the wizard. If you open the application welcome page (`index.xhtml`) or the Facelets template file (`template.xhtml`) in the editor, you will see that it contains a reference to the stylesheet.


[source,java]
----

<h:outputStylesheet name="css/jsfcrud.css"/>
----

The Facelets template file is used by each of the four Facelets files for each entity class.

If you expand the Source Packages node you can see the session beans, JSF managed beans, utility classes, and properties bundle that the wizard generated.

image::images/projects-generated-classes70.png[title="screenshot of Source Packages directory in Projects window showing classes generated by wizard"]

The wizard also generated a Faces Configuration file (`faces-config.xml`) in order to register the location of the properties bundle. If you expand the Configuration Files node and open `faces-config.xml` in the XML editor, you can see that the following entry is included.


[source,xml]
----

<application>
    <resource-bundle>
        <base-name>/resources/Bundle</base-name>
        <var>bundle</var>
    </resource-bundle>
</application>
----

Also, if you expand the new `resources` package, you'll find the `Bundle.properties` file that contains messages for the client's default language. The messages have been derived from the entity class properties.

To add a new property bundle, right-click the `Bundle.properties` file and choose Customize. The Customizer dialog enables you to add new locales to your application.


[[explore]]
== Exploring the Application

Now that your project contains entity classes, EJB session beans to control the entity classes, and a JSF-powered front-end to display and modify database, try running the project to see the results.

The following is a series of short, optional exercises that help you to become familiar with the application, as well as the features and functionality offered to you by the IDE.

* <<completedProject,Examining the Completed Project>>
* <<populateDB,Populating the Database with an SQL Script>>
* <<editorSupport,Exploring Editor Support in Facelets Pages>>
* <<dbIntegrity,Exploring Database Integrity with Field Validation>>
* <<editEntity,Editing Entity Classes>>


[[completedProject]]
=== Examining the Completed Project

1. To run the project, either right-click the project node in the Projects window and choose Run, or click the Run Project ( image::images/run-project-btn.png[] ) button in the main toolbar.

When the application's welcome page displays, you are provided with a list of links enabling you to view entries contained in each database table.

image::images/welcome-page-links.png[title="Links to display database contents for each table"]

The links were added to the welcome page (`index.xhtml`) when you completed the JSF Pages from Entity Classes wizard. They are provided as entry points into the Facelets pages that provide CRUD functionality on the Consulting Agency database.


[source,xml]
----

<h:body>
    Hello from Facelets
    <h:form>
        <h:commandLink action="/address/List" value="Show All Address Items"/>
    </h:form>
    <h:form>
        <h:commandLink action="/billable/List" value="Show All Billable Items"/>
    </h:form>
    <h:form>
        <h:commandLink action="/client/List" value="Show All Client Items"/>
    </h:form>
    <h:form>
        <h:commandLink action="/consultant/List" value="Show All Consultant Items"/>
    </h:form>
    <h:form>
        <h:commandLink action="/consultantStatus/List" value="Show All ConsultantStatus Items"/>
    </h:form>
    <h:form>
        <h:commandLink action="/project/List" value="Show All Project Items"/>
    </h:form>
    <h:form>
        <h:commandLink action="/recruiter/List" value="Show All Recruiter Items"/>
    </h:form>
</h:body>
----
2. Click the '`Show All Consultant Items`' link. Looking at the code above, you can see that the target page is `/consultant/List.xhtml`. (In JSF 2.x, the file extension is inferred due to implicit navigation.) 
image::images/empty-consultants-list.png[title="Consultants table is currently empty"] 
The database currently doesn't contain any sample data. You can add data manually by clicking the '`Create New Consultant`' link and using the provided web form. This triggers the `/consultant/Create.xhtml` page to display. You can also run an SQL script in the IDE to populate tables with sample data. The following sub-sections explore both options.

You can click the index link to return to the links listed in the welcome page. The links provide you with a view of the data held in each database table and trigger the `List.xhtml` file for each entity folder to display. As is later demonstrated, after you add data to the tables, other links will display for each entry enabling you to view (`View.xhtml`), edit (`Edit.xhmtl`), and destroy data for a single table record.

*Note.* If the application fails to deploy, see the <<troubleshooting,troubleshooting section>> below. (Also see the troubleshooting section of link:mysql-webapp.html#troubleshoot[+Creating a Simple Web Application Using a MySQL Database+].)


[[populateDB]]
=== Populating the Database with an SQL Script

Run the provided script, which generates sample data for the database tables. The script (`mysql_insert_data_consult.sql`) is included in the Consulting Agency Database zip file which you can download from the <<requiredSoftware,required software table>>.

Depending on the database server you are working with (MySQL or JavaDB), you can run the provided script, which generates sample data for the database tables. For MySQL, this is the `mysql_insert_data_consult.sql` script. For JavaDB, this is the `javadb_insert_data_consult.sql` script. Both scripts are included in their respective archives, which can be downloaded from the <<requiredSoftware,required software table>>.

1. Choose File > Open File from the main menu, then navigate to the location of the script on your computer. Click Open. The file automatically opens in the IDE's SQL editor.
2. Make sure that the `consult` database is selected in the Connection drop-down list in the SQL editor toolbar. 
image::images/run-sql-insert.png[title="Open the script in the IDE's SQL editor"]

Either right-click in the editor and choose Run Statement, or click the Run SQL ( image::images/run-sql-btn.png[] ) button. You can see the result of the script execution in the Output window.

3. Restart the GlassFish server. This is a necessary step to enable the server to reload and cache the new data contained in the `consult` database. To do so, click the GlassFish server tab in the Output window (The GlassFish server tab displays the server log.), then click the Restart Server ( image::images/glassfish-restart.png[] ) button in the left margin. The server stops, then restarts.
4. Run the project again and click the '`Show All Consultant Items`' link. You will see that the list is no longer empty. 
[.feature]
--
image::images/consultants-list-small.png[role="left", link="images/consultants-list.png"]
--


=== NetBeans Database Support

You can use the IDE's database table viewer to display and modify table data maintained directly in the database. For example, right-click the `consultant` table in the Services window, and choose View Data.

image::images/view-data.png[title="Choose View Data from the right-click menu of database tables"]

The SQL query used to perform the action displays in the upper portion of the editor, and a graphical view of the table displays beneath.

[.feature]
--
image::images/view-data-table-small.png[role="left", link="images/view-data-table.png"]
--

Double-click inside table cells to perform inline modifications to data. Click the Commit Records ( image::images/commit-records-icon.png[] ) icon to commit changes to the database.

The graphical view provides much more functionality. See link:../../docs/ide/database-improvements-screencast.html[+Database Support in NetBeans IDE+] for more information.


[[editorSupport]]
=== Exploring Editor Support in Facelets Pages

1. Open the `/consultant/List.xhtml` page in the editor. Line 8 indicates that the page relies on the Facelets `template.xhtml` file to render.

[source,java]
----

<ui:composition template="/template.xhtml">
----

To display line numbers, right-click in the editor's left margin and choose Show Line Numbers.

2. Use the IDE's Go to File dialog to open `template.xhtml`. Press Alt-Shift-O (Ctrl-Shift-O on Mac), then begin typing `template`. 
image::images/go-to-file.png[title="Use the Go to File dialog to quickly open project files"]

Click OK (or press Enter).

3. The template applies the `<ui:insert>` tags to insert content from other files into its title and body. Place your cursor on the `<ui:insert>` tag, then press Ctrl-Space to invoke a documentation popup window. 
image::images/doc-popup.png[title="Press Ctrl-Space to invoke a documentation popup on Facelets tags"]

You can press Ctrl-Space on JSF tags and their attributes to invoke a documentation pop-up. The documentation you see is taken from the descriptions provided in the official link:http://javaserverfaces.java.net/nonav/docs/2.1/vdldocs/facelets/index.html[+JSF Tag Library Documentation+].

4. Switch back to the `List.xhtml` file (press Ctrl-Tab). The `<ui:define>` tags are used to define the content that will be applied to the template's title and body. This pattern is used for all four Facelets files (`Create.xhtml`, `Edit.xhtml`, `List.xhtml`, and `View.xhtml`) generated for each entity class.
5. Place your cursor on any of the EL expressions used for localized messages contained in the `Bundle.properties` file. Press Ctrl-Space to view the localized message. 
[.feature]
--
image::images/localized-messages-small.png[role="left", link="images/localized-messages.png"]
--

In the above image, you can see that the EL expression resolves to '`List`', which is applied to the template title and can be verified from the page rendered in the browser.

6. Scroll to the bottom of the file and locate the code for the `Create New Consultant` link (Line 92). This is as follows:

[source,java]
----

<h:commandLink action="#{consultantController.prepareCreate}" value="#{bundle.ListConsultantCreateLink}"/>
----
7. Press Ctrl-Space on the `commandLink`'s `action` attribute to invoke the documentation pop-up. 

The `action` attribute indicates the method that handles the request when the link is clicked in the browser. The following documentation is provided: 

_MethodExpression representing the application action to invoke when this component is activated by the user. The expression must evaluate to a public method that takes no parameters, and returns an Object (the toString() of which is called to derive the logical outcome) which is passed to the NavigationHandler for this application._
In other words, the `action` value typically refers to a method in a JSF managed bean that evaluates to a `String`. The string is then used by JSF's `NavigationHandler` to forward the request to the appropriate view. You verify this in the following steps.
8. Place your cursor on `consultantController` and press Ctrl-Space. The editor's code completion indicates that `consultantController` is a JSF managed bean. 
image::images/code-completion-managed-bean.png[title="Code completion is provided for JSF managed beans"]
9. Move your cursor to `prepareCreate` and press Ctrl-Space. Code completion lists methods contained in the `ConsultantController` managed bean. 
image::images/code-completion-properties.png[title="Code completion is provided for class methods"]
10. Press Ctrl (⌘ on Mac), then hover your mouse over `prepareCreate`. A link is formed, enabling you to navigate directly to the `prepareCreate()` method in the `ConsultantController` managed bean. 
image::images/editor-navigation.png[title="Use editor navigation to quickly navigate source code"]
11. Click the link and view the `prepareCreate()` method (displayed below).

[source,java]
----

public String prepareCreate() {
    current = new Consultant();
    selectedItemIndex = -1;
    return "Create";
}
----
The method returns `Create`. The `NavigationHandler` gathers information behind the scenes, and applies the `Create` string to the path which targets the view sent in response to the request: `/consultant/*Create*.xhtml`. (In JSF 2.x, the file extension is inferred due to implicit navigation.)


[[dbIntegrity]]
=== Exploring Database Integrity with Field Validation

1. From the <<consultantsList,Consultants List page>> in the browser, click the '`Create New Consultant`' link. As demonstrated in the previous sub-section, this triggers the `/consultant/Create.xhtml` page to render.
2. Enter the following details into the form. For the time being, leave both `RecruiterId` and `StatusId` fields blank. 

|===
|Field |Value 

|ConsultantId |2 

|Email |jack.smart@jsfcrudconsultants.com 

|Password |jack.smart 

|HourlyRate |75 

|BillableHourlyRate |110 

|HireDate |07/22/2008 

|Resume |I'm a great consultant. Hire me - You won't be disappointed! 

|RecruiterId |--- 

|StatusId |--- 
|===
3. Click Save. When you do so, a validation error is flagged for the `StatusId` field. 
image::images/create-new-consultant.png[title="Enter sample data into the form"] 
Why did this happen? Reexamine the <<er-diagram,entity-relationship diagram for the Consulting Agency database>>. As stated in the <<relationships,relationships table>> above, the `CONSULTANT` and `CONSULTANT_STATUS` tables share a non-nullable, one-to-many relationship. Therefore, every entry in the `CONSULTANT` table must contain a reference to an entry in the `CONSULTANT_STATUS` table. This is denoted by the `consultant_fk_consultant_status` foreign key that links the two tables.

You can view foreign keys held by tables by expanding a table's Foreign Keys node in the Services window (Ctrl-5; ⌘-5 on Mac).

image::images/consultant-fk.png[title="Examine foreign key attributes in the Services window"]
4. To overcome the validation error, select `entity.ConsultantStatus[statusId=A]` from the `StatusId` drop-down list. 

*Note: *You can leave the `RecruiterId` field blank. As indicated in the <<er-diagram,database entity-relationship diagram>>, there is a nullable, one-to-many relationship between the `CONSULTANT` and `RECRUITER` tables, meaning that entries in `CONSULTANT` do not need to be associated with a `RECRUITER` entry.
5. Click Save. A message displays, indicating that the consultant entry was successfully saved. If you click `Show All Consultant Items`, you'll see the new entry listed in the table.

In general, the generated Facelets pages provide errors for user input that introduces:

* empty fields for non-nullable table cells.
* modifications to data that cannot be altered (e.g., primary keys).
* insertion of data that is not of the correct type.
* modifications to data when a user's view is no longer synchronized with the database.


[[editEntity]]
=== Editing Entity Classes

In the previous sub-section, you saw how the `StatusId` drop-down list provided you with the not-so-user-friendly `entity.ConsultantStatus[statusId=A]` option. You may already be aware that the text displayed for each item in this drop-down is a string representation for each `ConsultantStatus` entity encountered (i.e., The entity class' `toString()` method is called).

This sub-section demonstrates how you can use the editor's code completion, documentation, and navigation support to make this conclusion. It also has you prepare a more user-friendly message for the drop-down list.

1. Open the `/consultant/Create.xhtml` file in the editor. This is the Create New Consultant form which you just viewed in the browser. Scroll down to the code for the `StatusId` drop-down (shown in *bold* below).

[source,xml]
----

    <h:outputLabel value="#{bundle.CreateConsultantLabel_resume}" for="resume" />
    <h:inputTextarea rows="4" cols="30" id="resume" value="#{consultantController.selected.resume}" title="#{bundle.CreateConsultantTitle_resume}" />
    *<h:outputLabel value="#{bundle.CreateConsultantLabel_statusId}" for="statusId" />
    <h:selectOneMenu id="statusId" value="#{consultantController.selected.statusId}" title="#{bundle.CreateConsultantTitle_statusId}" required="true" requiredMessage="#{bundle.CreateConsultantRequiredMessage_statusId}">
        <f:selectItems value="#{consultantStatusController.itemsAvailableSelectOne}"/>
    </h:selectOneMenu>*
    <h:outputLabel value="#{bundle.CreateConsultantLabel_recruiterId}" for="recruiterId" />
    <h:selectOneMenu id="recruiterId" value="#{consultantController.selected.recruiterId}" title="#{bundle.CreateConsultantTitle_recruiterId}" >
        <f:selectItems value="#{recruiterController.itemsAvailableSelectOne}"/>
    </h:selectOneMenu>
</h:panelGrid>
----
2. Examine the `value` applied to the `<f:selectItems>` tag. The `value` attribute determines the text that displays for each item in the drop-down list. 

Press Ctrl-Space on `itemsAvailableSelectOne`. The editor's code completion indicates that the `ConsultantStatusController`'s `getItemsAvailableSelectOne()` method returns an array of `SelectItem` objects. 
image::images/code-completion-returned-object.png[title="Code completion displays returned classes for methods"]
3. Press Ctrl (⌘ on Mac), then hover your mouse over `itemsAvailableSelectOne`. A link is formed, enabling you to navigate directly to the `getItemsAvailableSelectOne()` method in the `ConsultantStatus` entity's source code. Click this link.
4. Place your cursor on the `SelectItem[]` return value in the method signature, and press Ctrl-Space to invoke the documentation pop-up. 
image::images/documentation-select-item.png[title="Press Ctrl-Space to invoke documentation support"]

Click the web browser ( image::images/web-browser-icon.png[] ) icon in the documentation window to open the Javadoc in an external web browser.

As you can see, the `SelectItem` class belongs to the JSF framework. The `UISelectOne` component, as mentioned in the documentation, is represented by the `<h:selectOneMenu>` tag from the markup which you examined in <<markup,Step 1>> above.
5. Press Ctrl (⌘ on Mac), then hover your mouse over `findAll()`. A pop-up appears, displaying the method signature. 
image::images/method-signature.png[title="View pop-ups of method signatures in the editor"] 
You can see that here `ejbFacade.findAll()` returns a `List` of `ConsultantStatus` objects.
6. Navigate to `JsfUtil.getSelectItems`. Hover your mouse over `getSelectItems` and press Ctrl (⌘ on Mac), then click the link that displays. 

*Note: *Recall that `JsfUtil` is one of the utility classes that was generated when you completed the <<jsfPagesEntityClasses,JSF Pages from Entity Classes wizard>>. 

The method loops through the list of entities (i.e, the `List` of `ConsultantStatus` objects), creating a `SelectItem` for each. As indicated in *bold* below, each `SelectItem` is created using the entity object and a _label_ for the object.

[source,java]
----

public static SelectItem[] getSelectItems(List<?> entities, boolean selectOne) {
    int size = selectOne ? entities.size() + 1 : entities.size();
    SelectItem[] items = new SelectItem[size];
    int i = 0;
    if (selectOne) {
        items[0] = new SelectItem("", "---");
        i++;
    }
    *for (Object x : entities) {
        items[i++] = new SelectItem(x, x.toString());
    }*
    return items;
}
----

The label is created using the entity's `toString()` method, and is the representation of the object when rendered in the response. (See the Javadoc definition for the `SelectItem(java.lang.Object value, java.lang.String label)` constructor.)

Now that you have verified that the entity `toString()` method is what is rendered in the browser when you view items in a drop-down list, modify the `ConsultantStatus` `toString()` method.

7. Open the `ConsultantStatus` entity class in the editor. Modify the `toString` method to return the `statusId` and `description`. These are entity properties which correspond to the two columns of the `CONSULTANT_STATUS` table.

[source,java]
----

public String toString() {
    return *statusId + ", " + description;*
}
----
8. Run the project again. When the browser displays the welcome page, click the `Show All Consultant Items` link, then click `Create New Consultant`.

Inspect the `StatusId` drop-down. You'll see that it now displays the status ID and description for the one record contained in the database's `CONSULTANT_STATUS` table.

image::images/drop-down.png[title="StatusId drop-down displays items according to ConsultantStatus entity's toString() method"]


[[troubleshooting]]
== Troubleshooting

Depending on your configuration, deploying the application to the server can fail and you might see the following message in the Output window.


[source,java]
----

GlassFish Server 4 is running.
In-place deployment at /MyDocuments/ConsultingAgency/build/web
GlassFish Server 4, deploy, null, false
/MyDocuments/ConsultingAgency/nbproject/build-impl.xml:1045: The module has not been deployed.
See the server log for details.
----

The most common cause for the failure is a problem when generating the JDBC resources on the server. If this is the case, you will probably see a message similar to the following in the server log tab in the Output window.


[source,java]
----

Severe:   Exception while preparing the app : Invalid resource : jdbc/consult__pm
com.sun.appserv.connectors.internal.api.ConnectorRuntimeException: Invalid resource : jdbc/consult__pm
----

If the server log tab is not open you can open the tab by right-clicking the GlassFish Server node in the Services window and choosing View Domain Server Log.

This application requires two JDBC resources:

* JDBC Resource or Datasource. The application uses JNDI lookup to locate the JDBC resource. If you look in the persistence unit (`persistence.xml`) you can see that the JNDI name for the JTA data source for this application is `jdbc/consult`.

The JDBC resource identifies the connection pool that is currently used by the application.

* JDBC Connection Pool. The connection pool specifies the connection details for the database, including the location, user name, password. The connection pool that is used for this application is `consultPool`.

The JDBC resource and connection pool are specified in the `glassfish-resources.xml` file. You can open `glassfish-resources.xml` in the editor by expanding the Server Resources node in the Projects window and double-clicking the file. The file will look similar to the following.


[source,xml]
----

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE resources PUBLIC "-//GlassFish.org//DTD GlassFish Application Server 3.1 Resource Definitions//EN" "http://glassfish.org/dtds/glassfish-resources_1_5.dtd">
<resources>
  <jdbc-connection-pool allow-non-component-callers="false" associate-with-thread="false" connection-creation-retry-attempts="0" connection-creation-retry-interval-in-seconds="10" connection-leak-reclaim="false" connection-leak-timeout-in-seconds="0" connection-validation-method="auto-commit" datasource-classname="com.mysql.jdbc.jdbc2.optional.MysqlDataSource" fail-all-connections="false" idle-timeout-in-seconds="300" is-connection-validation-required="false" is-isolation-level-guaranteed="true" lazy-connection-association="false" lazy-connection-enlistment="false" match-connections="false" max-connection-usage-count="0" max-pool-size="32" max-wait-time-in-millis="60000" name="consultPool" non-transactional-connections="false" ping="false" pool-resize-quantity="2" pooling="true" res-type="javax.sql.DataSource" statement-cache-size="0" statement-leak-reclaim="false" statement-leak-timeout-in-seconds="0" statement-timeout-in-seconds="-1" steady-pool-size="8" validate-atmost-once-period-in-seconds="0" wrap-jdbc-objects="false">
    <property name="serverName" value="localhost"/>
    <property name="portNumber" value="3306"/>
    <property name="databaseName" value="consult"/>
    <property name="User" value="root"/>
    <property name="Password" value="nb"/>
    <property name="URL" value="jdbc:mysql://localhost:3306/consult?zeroDateTimeBehavior=convertToNull"/>
    <property name="driverClass" value="com.mysql.jdbc.Driver"/>
  /<jdbc-connection-pool>
  <jdbc-resource enabled="true" jndi-name="jdbc/consult" object-type="user" pool-name="consultPool"/>
/<resources>
----

In `glassfish-resources.xml` you can see that the JDBC resource `jdbc/consult` identifies `consultPool` as the name of the connection pool. You can also see the properties for `consultPool`. In this application only one datasource and one connection pool are defined in `glassfish-resources.xml`. In some cases you might want to specify additional resources, for example, to identify a temporary data store that is used only for development or for testing.

If the JDBC resource and connection pool were not generated automatically on the server when you tried to the application, you can perform the following steps to manually create the resources in the GlassFish Admin Console.

1. Open `glassfish-resources.xml` in the editor if it is not already open.

You will use the property values that are specified in `glassfish-resources.xml` when you create the JDBC resource and connection pool.

2. Right-click the GlassFish Server node in the Services window and choose Open Domain Admin Console in the popup menu to open the GlassFish Console in your browser.
3. In the Common Tasks navigation panel of the GlassFish Console, expand the *JDBC* node and the *JDBC Resources* and *JDBC Connection Pools* nodes. 
[.feature]
--
image::images/gf-admin-console-sm.png[role="left", link="images/gf-admin-console-lg.png"]
--

You can see the JDBC resources that are currently registered with the server. You will need to create `jdbc/consult` and `consultPool` if they are not listed under the JDBC node in the Common Tasks navigation panel. Some JDBC resources were created by default when you installed the server and are displayed as sub-nodes.

4. Click the *JDBC Connection Pools* node and click New in the New JDBC Connection Pool pane. 
image::images/gf-new-jdbc-pool1.png[title="New JDBC Connection Pool pane in the GlassFish Admin Console"]
5. Type *consultPool* as the Pool Name, select *javax.sql.ConnectionPoolDataSource* as the Resource Type and select *MySql* as the Database Driver Vendor. Click Next.
6. In Step 2, locate and specify the values for the *URL*, *username* and *password* properties. Click Finish. 
image::images/gf-new-jdbc-pool2.png[title="New JDBC Connection Pool panel in the GlassFish Admin Console"]

You can find the values for the properties in `glassfish-resources.xml`.

The new connection pool is created on the server when you click Finish and a node for the connection pool is displayed under the JDBC Connection Pools node.

7. Click the *JDBC Resources* node in the Common Tasks navigation panel and click New.
8. Type *jdbc/consult* for the JNDI Name and select *consultPool* in the Pool Name drop-down list. Click OK. 
image::images/gf-new-jdbc-resource.png[title="New JDBC Resource pane in the GlassFish Admin Console"]

The new JDBC resource is created on the server when you click OK and a node for the resource is displayed under the JDBC Resources node.

In the Service window of the IDE, you can expand the Resources node under the GlassFish Server and see that IDE added the new resources. You might need to refresh the view (right-click Resources and choose Refresh) to view the changes.

image::images/gf-services-jdbc-resources.png[title="JDBC Resources displayed in the Services window of the IDE"]

For more tips on troubleshooting problems when using MySQL and the IDE, see the following documents:

* link:../ide/mysql.html[+Connecting to a MySQL Database+] tutorial.
* The troubleshooting section of link:mysql-webapp.html#troubleshoot[+Creating a Simple Web Application Using a MySQL Database+]
link:/about/contact_form.html?to=3&subject=Feedback:%20Creating%20a%20JSF%202.0%20CRUD%20Application[+Send Feedback on This Tutorial+]


[[seealso]]
== See Also

For more information about JSF 2.x, see the following resources.


=== NetBeans Articles and Tutorials

* link:jsf20-intro.html[+Introduction to JavaServer Faces 2.x in NetBeans IDE+]
* link:jsf20-support.html[+JSF 2.x Support in NetBeans IDE+]
* link:../../samples/scrum-toys.html[+Scrum Toys - The JSF 2.0 Complete Sample Application+]
* link:../javaee/javaee-gettingstarted.html[+Getting Started with Java EE Applications+]
* link:../../trails/java-ee.html[+Java EE &amp; Java Web Learning Trail+]


=== External Resources

* link:http://www.oracle.com/technetwork/java/javaee/javaserverfaces-139869.html[+JavaServer Faces Technology+] (Official homepage)
* link:http://jcp.org/aboutJava/communityprocess/final/jsr314/index.html[+JSR 314 Specification for JavaServer Faces 2.0+]
* link:http://docs.oracle.com/javaee/7/tutorial/doc/jsf-intro.htm[+JavaServer Faces Technology+] chapter in the Java EE 7 Tutorial
* link:http://javaserverfaces.dev.java.net/[+GlassFish Project Mojarra+] (Official reference implementation for JSF 2.x)
* link:http://forums.oracle.com/forums/forum.jspa?forumID=982[+OTN Discussion Forums : JavaServer Faces+]
* link:http://www.jsfcentral.com/[+JSF Central+]


=== Blogs

* link:http://www.java.net/blogs/edburns/[+Ed Burns+]
* link:http://www.java.net/blogs/driscoll/[+Jim Driscoll+]