• The NetBeans IDE Java Bundle also includes the GlassFish v3 application server, which you require for this tutorial.
• For the solution project to this tutorial, download ConsultingAgencyJSF20.zip.

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

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

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 ( ) 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.
   
   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.

   <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.0, the file extension is inferred due to implicit navigation.)
   
   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.

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_v2.sql) is included in the Consulting Agency Database zip file which you can download from the 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.
   
   Either right-click in the editor and choose Run Statement, or click the Run SQL ( ) button. You can see the result of the script execution in the Output window.
3. Restart GlassFish. 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 tab in the Output window (The GlassFish tab displays the server log.), then click the Restart Server ( ) button in the left margin. The GlassFish server stops, then restarts.
4. Run the project again and click the 'Show All Consultant Items' link. You'll see that the list is no longer empty.
   
   
   

   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.

   

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

   Double-click inside table cells to perform inline modifications to data. Click the Commit Records ( ) icon to commit changes to the database.
   
   The graphical view provides much more functionality. See Database Support Improvements in NetBeans IDE 6.5 for more information.

   
   

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.

   <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.
   
   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.
   
   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 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.
   
   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:

   <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.
   
9. Move your cursor to prepareCreate and press Ctrl-Space. Code completion lists methods contained in the ConsultantController managed bean.
   
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.
    
11. Click the link and view the prepareCreate() method (displayed below).

    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.0, the file extension is inferred due to implicit navigation.)

Exploring Database Integrity with Field Validation

1. From the 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
   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.
   
   Why did this happen? Reexamine the entity-relationship diagram for the Consulting Agency database. As stated in the 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).

   
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 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.

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).

       <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.
   
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.
   

   Click the web browser ( ) 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 Step 1 above.
5. Press Ctrl (⌘ on Mac), then hover your mouse over findAll(). A pop-up appears, displaying the method signature.
   
   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 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.

   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.

   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.