Getting Started with Visual Web JSF Application Development

This tutorial gives you a whirlwind tour of Visual Web JSF application development in NetBeans IDE 6.0 or 6.1. The tutorial shows you how to use Visual Web JSF Application functionality and JavaServer Faces 1.2 (Woodstock) components to perform the typical phases of web application development.

The tutorial is designed so that you do not need to go through it in any particular order. You might want to skim over it quickly and then return to each section as time allows. If you prefer a step by step tutorial, you might want to first try Developing a JSF Web Application.

Note: This document uses the NetBeans IDE 6.0 or 6.1 Release. If you are using NetBeans IDE 6.5, see Getting Started with Visual Web JSF Application Development.

Contents

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

* To take advantage of NetBeans IDE's Java EE 5 capabilities, use an application server that is fully compliant with the Java EE 5 specification, such as the GlassFish Application Server V2 UR2. If you are using a different server, consult the Release Notes and FAQs for known problems and workarounds. For detailed information about the supported servers and Java EE platform, see the Release Notes.

Note for NetBeans IDE 6.1 users:

Starting a Project

A project is the equivalent of your working environment for a web application. When you create a Visual Web JSF Application project and you have specified GlassFish V2 or later as an application server in the NetBeans IDE, the IDE can create a web application based on Java EE 5 that uses JavaServer Faces 1.2 components. By default, the web application is created in a directory structure that conforms to the Java BluePrints project conventions for web applications.

Try It

Start the IDE by using the appropriate step from the following list:

Windows, Solaris and Linux. Double-click the NetBeans desktop icon. Mac. On MacOS, the executable is installed into the /Applications/NetBeans/ directory. Double-click the NetBeans icon in this folder.

Create a Visual Web JSF Application project:

Choose File > New Project from the main menu. In the New Project wizard, select the Web category and the Web Application project type, and click Next. Name the project GettingStarted. Note the default project location. Browse and select a different location if you like.

Note for NetBeans IDE 6.1 users: Creating a project in NetBeans 6.1 includes new options which can be left at the default. For example, the Use Dedicated Folder for Storing Libraries checkbox may be left unselected.

Choose a server and Java EE version.

For example, the default server is GlassFish V2, and Java EE 5 is the default Java EE Version. Click Next. In the Frameworks panel, select the Visual Web JavaServer Faces framework Click Finish to create the new project in the default location or the location chosen in step c.

The IDE creates the project directory in the selected (or default) project folder and gives it the same name as your project.

Explore the Projects window. As shown in the following figure, the Projects window groups items by category. Expand each of the nodes to see what type goes in each category.

Under the Web Pages node is the Page1.jsp node. The IDE creates this page by default and makes it the start page. The arrow badge  next to the node identifies the page as the start page. If you want to use a different page for the start page, right-click that page's node and choose Set as Start Page from the pop-up menu.

Click the Files tab, or choose Window > Files from the main menu, to bring the Files window to the front. This window organizes the items by their physical storage. Expand the nodes to see the structure. Notice the badge  that appears next to the ApplicationBean1.java node and several other nodes below it, such as Page1.java. This badge indicates that the file needs to be compiled. The IDE compiles the files automatically when you build the project.

In the figure above, notice the GettingStarted > src > java > gettingstarted > Page1.java node. This Java class is the backing bean for the Page1.jsp file. Whenever you add a page to the project, the IDE creates both a .jsp file and a .java file for the page. You learn more about .jsp and .java files in the next section.

For More Information

Creating Web Pages

With Visual Web JSF applications, you use JavaServer Pages (JSP) technology and page beans (also known as backing beans) instead of HTML pages. The JSP page is a template from which the server generates the HTML response to be displayed in the browser (the client). The page bean contains the logic that the server executes both when it generates the HTML response and after a user submits the page.

When you add a web page in a Visual Web JSF application, the IDE creates both a JSP file and a Java source file for you. You mostly use the Visual Designer and the Properties window to develop the web page. The IDE modifies the JSP code and Java code to implement what you design. Most of your work can be done from the Visual Designer and the Properties window.

Note: The JSP pages that the IDE generates are JSP documents. A JSP document is an XML document and, therefore, must be well-formed. While most JSP elements comply with XML syntax, there are some elements that are not XML compliant, such as comments, declarations, directives, expressions, and scriptlets. See the JavaServer Pages Syntax Reference for JSP document syntax.

Try It

Note: NetBeans IDE 6.1 features on-demand binding. Where components require Java coding, you must now manually add the binding attribute to components in a Visual Web JSF application. To do so, right-click each component and choose Add Binding Attribute. For more information, see the On-demand Binding Attribute Wiki.

In the Projects window, right-click the Web Pages node and choose New > Visual Web JSF Page, as shown in the following figure.

Accept the default name of Page2 and click Finish. The IDE opens Page2 in the Visual Designer, which is in the editing area, as shown in the following figure.

Click the Java button in the editing toolbar to see the source code for the page bean, as shown in the following figure. When the editing area shows the Java source, the Navigator window lists all the member fields and methods. Notice that the page's source code has methods to access the Application Bean, Session Bean, and Request Bean. See the Storing and Passing Data section in this tutorial for an explanation of these three types of beans.

The source also has methods that get invoked during certain lifecycle events between the time the page is requested and the time the page rendering is complete.

Tip: Double-clicking a member in the Navigator window opens the source code editor and positions the cursor at that member's declaration. You can also click in the Navigator window and start typing the first few characters of a member's name to open a Quick Search dialog box. Continue typing until the IDE highlights the desired entry in the list, as shown in the following figure. You can then press Enter to open the source code editor and position it at the matching member's declaration.

Click the JSP button in the editing toolbar to see the JSP code for the page, as shown in the following figure. Notice how the JSP page uses JSP document syntax.

Note: NetBeans IDE 6.1 features on-demand binding. Where components require Java coding, you must now manually add the binding attribute to components in a Visual Web JSF application. To do so, right-click each component and choose Add Binding Attribute. For more information, see the On-demand Binding Attribute Wiki.

Clicking the Design button in the editing toolbar switches to the Visual Designer and displays the representation of the page in the Navigator window. If you open the nodes under the Page2 node, you can see the nodes shown in the following figure. Note how the tags in the JSP file are represented as nodes in the Navigator window.

For More Information

Adding Components to a Web Page

You design a web page by dragging components from the Palette window and dropping them on the web page in the Visual Designer. The following figure shows Page2 with the Button, Text Field, Message, Drop Down List, and Radio Button Group components. All these components are available from the Basic section of the Palette. These components have been customized by changing their properties. You learn about properties later in this section.

Note: NetBeans IDE 6.1 features on-demand binding. Where components require Java coding, you must now manually add the binding attribute to components in a Visual Web JSF application. To do so, right-click each component and choose Add Binding Attribute. For more information, see the On-demand Binding Attribute Wiki.

Note: The components that are available from the Palette are JavaServer Faces (JSF) components that have been enhanced according to the Design Time API to make their properties available for the Visual Designer and the Properties window. You can use other components in the web applications that you build by using the IDE, but you will not be able to use the interactive design-time features of the IDE on these components unless they have been customized according to requirements of the Design Time API. If the Java EE version is set to Java EE 5, the Palette offers JSF 1.2 components. If, when you create the project, you set the Java EE version to 1.3 or 1.4, the Palette offers JSF 1.1 components.

Most of the components that you use are in the Woodstock Basic, Woodstock Layout, and Woodstock Composite sections of the Palette window. The following tables show some of the most commonly used components grouped according to functionality.

Table 1: Input Components

Table 2: Display Components

Table 3: Grouping Components

Table 4: Action Components

You use the component's property sheet in the Properties window to change the appearance and behavior of the component, to bind the component to data, and to associate the component with event handlers.

The following figure shows the properties for a Listbox component.

Try It

Open Page2 that you created by following the Try It suggestions in the Creating Web Pages section, or create it if necessary.

Drag various components from the Basic section and the Layout section of the Palette window and play around with their properties. For example, try the following steps:

Note: NetBeans IDE 6.1 features on-demand binding. Where components require Java coding, you must now manually add the binding attribute to components in a Visual Web JSF application. To do so, right-click each component and choose Add Binding Attribute. For more information, see the On-demand Binding Attribute Wiki.

For More Information

Getting Help

The IDE provides a Help Viewer, which contains help topics about the IDE. Also, when you press F1 on a window, dialog box, or Palette component, the Help viewer appears and displays information about that item. To access the Visual Web JSF Pack help topics, including help about the components, you can also choose Help > Help Contents from the main menu and scroll to Web Applications.

Try It

Building and Testing a Web Application

When you are ready to test a project, press F6 or choose Run > Run Main Project from the main menu. The IDE takes the following actions:

Saves any files that need saving.

Compiles any files that need to be compiled.

If there are complications, the IDE displays the related error messages in the Output window (shown below) and does not continue with the build-and-run process. Click the link in the error message to go to the source code that caused the compilation error. Starts the application server if it is not already started.

Deploys the application to the application server.

If there are any complications, the IDE displays the related error messages in the Output window and does not continue with the build-and-run process.

Opens a browser and sends the URL for the deployed application to the browser which, in turn, displays the start page.

Note: If you added components to a page other than the start page, at this point in the tutorial you will not see them in the web browser. See the Try It section below for a way to set up navigation from the start page to another page in your application.

If you have made a lot of changes or deleted several items, or if you are seeing some unexpected behavior, you can choose Build > Clean and Build Main Project from the main menu. The IDE cleans out the project's build directory and dist directory, undeploys the web application, and then builds and deploys the application.

Try It

If your project has fewer than two pages, create a new one by right-clicking the Web Pages node in the Projects window and choosing New > Visual Web JSF Page. Open the start page (the page with the arrow badge ) in the Visual Designer. Drag a Hyperlink component onto the page, type Next Page, and press Enter. In the Properties window for the Hyperlink component, click the ellipsis button for the url property, select a different page in the project, and click OK. Notice how the IDE sets the url property to /faces/page-name.jsp. Press F6 to build and run the web application. Watch the messages that appear in the Output window during the build process. Also notice that output from the server's log appears in the server's tab. Note the URL that the IDE sends to the browser. When the start page appears in the browser, click the Next Page link.

Return to the IDE, and, in the Services window, expand Servers and expand the server's node, and then expand Applications > Web Applications and note that there is a node for your project, as shown in the following figure.

For More Information

Connecting Web Pages and Handling User Actions

When a user types a URL, clicks a link, or clicks a button, the browser sends a request to the server. The server maps the request to a JSP page and uses that JSP page and its associated page bean to render a response.

You can specify page navigation in one of two ways:

To access the Page Flow editor, right-click the page background in the Visual Designer and choose Page Navigation.

The Page Flow editor shows page icons for all the pages in the project. When you click the + element of a page icon in the Page Flow editor, the icon expands and shows all its action components, components that have an action property, such as a Button, a Hyperlink, or a Tab. Next to each component is a connector port. In the image below the hyperlink's connector port resembles a chain and the button's shows an arrow. You drag from the connector port to a page icon to create the mapping between that action's request and the page to be rendered as a response to the request. When you release the mouse, the IDE adds a visual representation of that connection, as shown in the connection labeled nextPage in the following figure.

Note: When a page is submitted, the web application performs conversions and validations before it executes action methods. If a conversion or validation fails, the action methods do not get called. You should put Message Group components on a page during development so that you can catch any unexpected conversion or validation error that might prevent an action method from being invoked.

Try It

Note: NetBeans IDE 6.1 features on-demand binding. Where components require Java coding, you must now manually add the binding attribute to components in a Visual Web JSF application. To do so, right-click each component and choose Add Binding Attribute. For more information, see the On-demand Binding Attribute Wiki.

For More Information

Editing Java Code

The IDE's Java editor is packed full of features to facilitate the programming process, many more than can be discussed in this introductory tutorial. If you click inside a Java editor window and press F1, you can get help on most of the features of this editor.

The following descriptions cover a few of the more useful editing features.

Code Completion. Code completion enables you to type a few characters and then choose from a list of possible classes, methods, variables, and so on to automatically complete the expression. To display the code completion box, press Ctrl-Space. The code completion box also appears when you pause after typing a period that follows a package name, a variable, or a method call, as shown in the following figure.

Javadoc. The code completion feature also displays any related Javadoc. In addition, you can right-click a type, a field, or a method and choose Show Javadoc to see the Javadoc for that item, if the Javadoc is available. To see the available Javadoc, choose Help > Javadoc References. You can also press Shift-F1 to display a Javadoc Index Search tool. Fix Imports. Press Ctrl-Shift-I to add necessary import statements automatically.

Error detection. Red error boxes appear in the left margin of all statements that will not compile. Hover the mouse over the box to see the description of the error, as shown in the following figure. The IDE also displays an error strip on the right margin. This strip represents the whole file, not just the lines of code that are visible. Red lines in the error strip identify errors in the code. Double-click a red line to jump to the erroneous statement. When you compile files, all compilation errors appear in the Output window. Click an error message to display the erroneous code in the Java Editor.

Java Editor Keyboard Shortcuts. You can invoke many common editing tasks with a simple key combination as shown in the following examples. To learn more about the shortcuts, choose Help > Help Contents from the main menu to open the Help viewer, and then in the Contents pane choose IDE Basics > Keyboard Shortcuts > Editor Shortcuts.

Action Shortcut

Format code Alt-Shift-F

Remove current line Ctrl-E

Move insertion point to highlighted matching bracket Ctrl-[

Select the block between a pair of brackets Ctrl-Shift-[

Code Templates . Code Templates are short groups of characters that expand into a full word or phrase when you press the spacebar, as shown in the following examples. To see the full list of code templates, choose Tools > Options on a Microsoft Windows system or NetBeans > Preferences on a Macintosh system, and then choose Basic Options > Editor > Code Templates and click the ellipsis button for the Code Templates property. Some examples:

Code Abbreviation

for (Iterator it = collection.iterator(); it.hasNext();)
{Object elem = (Object) it.next();} forc

for (int i = 0; i < arr.length; i++) {} fori

try {|} catch (Exception ex)
{log("Error Description", ex); } finally {} trycatch

Code Clips. When you have the Java editor open, the Palette window provides many useful code clips that you can drag and drop onto your source file. The code clips do not appear for managed bean source files, such as the source file for an application bean or a request bean.

Note: If you click JSP in the toolbar to open the JSP editor, you see JavaScript tooltips in the Palette window that you can use in the JSP file. Quick Search. If you click in the Navigator window and start typing the name of a method or a field, a Quick Search dialog box appears and the IDE highlights the first matching entry in the list. Press Enter to position the Java editor in the source code at that entry's declaration.

Try It

Note: The following exercises have you type code in the destroy method. The code that you type is meant to illustrate the editing features. You would not normally put code like this in this method. After you complete the steps, you should remove the code.

For More Information

Handling User Input

The IDE provides validator and converter objects to facilitate input checking and formatting. These objects can be found in their respective sections in the Palette.

You bind a validator to an input component, such as a Text Field component, by dropping the validator onto the input component. For example, after you add a Text Field component to a page in the Visual Designer, you can drag a Length Validator from the Validators section in the Palette and drop it on the Text Field.

Alternatively, you can drop the validator onto the page and set the input component's validator property to that validator object. For example, you can drop a Long Range Validator on a blank spot on the page, which adds longRangeValidator1 to the Navigator window. You can then select an input component in the Visual Designer, such as the Text Field component, and choose longRangeValidator1 from its validatorExpression property's drop-down list. You can use the same validator for more than one component.

The mechanisms are similar for converters. You can also associate converters with output components, such as the Static Text component. Note that when you bind a component to a data provider field, the conversions are done automatically. You learn about binding to data providers in the Connecting to Databases section.

You use the validator's Properties window to set the validation rules, such as the minimum and maximum value or the minimum and maximum length. Similarly, you use the converter's Properties window to set the conversion rules, such as the pattern that the value should match or the method to call to do the validation. The Number converter has a special wizard that appears when you first drop the Number Converter onto the page or onto a visual component.

The Basic section of the Palette provides the Message component and the Message Group component for automatically displaying conversion errors, validation errors, and required-field messages. The Message Group component displays global error messages, runtime errors and, optionally, all the component error messages. A Message component displays only the messages for the component to which it is bound. You bind a Message component to another component by setting the Message component's for property or by pressing Ctrl-Shift on the Message component and dragging the mouse to the component to which you want to bind the Message component.

You can programmatically send custom error messages to the Message Group component using the error, warn, fatal, and info methods in any Page Bean. To learn more about these methods, choose Tools > Javadoc Index Search, type FacesBean in the text field for the drop-down list, and click Find.

Try It

Note: NetBeans IDE 6.1 features on-demand binding. Where components require Java coding, you must now manually add the binding attribute to components in a Visual Web JSF application. To do so, right-click each component and choose Add Binding Attribute. For more information, see the On-demand Binding Attribute Wiki.

Create a page and drag a button onto the page. Set the button's text to Go. Drag a Text Field component onto the page. In the Properties window for the Text Field component, select the required property's checkbox. Drop a Label component above the Text Field component, type Price: and press Enter. In the Properties window for the Label component, select textField1 from the drop-down list for the for property. Note how the label in the Visual Designer shows an asterisk to indicate that input is required for its associated Text Field component.

In the Palette, expand the Validators section. Drag a Double Range Validator and drop it on the Text Field component. In the Navigator window, select the newly created doubleRangeValidator1 node. In the Properties window for the validator, set the maximum to 10.0 and set the minimum to 1.0, as shown in the following figure.

In the Palette, expand the Converters section. Drag a Number Converter and drop it on the Text Field component. A Number Format dialog box appears, as shown in the following figure. Select currency from the Type drop-down list, select English (United States) from the Locale drop-down list, and click OK.

Add a Message component to the page. Press Ctrl-Shift on the component and drag to the Text Field component.

Notice that the IDE sets the Message component's for property to the Text Field component's id. Add a Message Group component to the page.

Make the page the start page and run the application. Try clicking the button with no price entered, with 1.5 entered, with a non-numeric value, and with a price greater than $10.00. Finally, type $1.50 in the text field and click the button.

Notice how the application rejects all values that do not conform to the number format and that do not fall within the specified range. Notice the different messages that appear in the Message and Message Group components. Experiment with setting the showGlobalOnly checkbox for the Message Group component.

For More Information

Storing and Passing Data

You use the Application Bean, the Session Bean, and the Request Bean to store information for use by other pages.

To add a property to the Session Bean:

Use similar steps to add a property to the Request Bean or the Application Bean. For more information see the FAQ How do I add properties to managed beans in NetBeans IDE?

Note: You can also add properties to a page bean (the backing bean that the IDE creates for each page). To add a property to a page bean, open the page's java code and add the propery declaration to the constructor public class Page1 extends AbstractPageBean, and encapsulate the fields as above. Page bean property values last only as long as the page bean is instantiated. For example, when the user clicks a Button component that rerenders the page (that is, the action method returns null), a new instance of that page bean is created, and the page bean's property values are reinitialized. If you want to pass a value to the postback, you can use Hidden Field components.

To associate a component with a bean's property, right-click the component and choose Bind to Data. In the Bind to Data dialog box, select the Bind to Object tab and choose the bean's property, as shown in the following figure.

Note: For most components, the pop-up menu provides two binding actions - Property Bindings and Bind to Data. The Property Bindings dialog box enables you to bind any of the component's properties to a managed bean property or a data provider field. The Bind to Data dialog box is a shortcut for binding the component's value-holding property to a managed bean property or a data provider field. Use the Bind to Data Provider tab to bind to any data provider that you have added to the page or a managed bean. Use the Bind to an Object tab to bind to a page property or a managed bean property.

Try It

For More Information

Connecting to Databases

The Services window includes a Databases node, which shows all the databases that are registered with the IDE, as shown in the following figure. NetBeans IDE provides a sample TRAVEL database which you use in the remainder of this tutorial.

Before you can access a database from a project, you must first connect the IDE to the database. You must do this every time you start the IDE and open a project that is connected to the database.

If a database's badge appears broken  and you cannot expand the database's node, the IDE is not connected to the database. To connect to the TRAVEL database, right-click the database's node in the Services window and choose Connect from the pop-up menu. If the Connect dialog box appears, enter travel for the Password and select Remember Password During This Session.

When you open an existing project, the Visual Designer might show an error screen. Typically, this is because the Visual Designer needs to get information from the database, but the IDE is not connected to the database. Try connecting to the database server and clicking the Continue button in the error screen to resolve the problem.

You can connect a page to a database table by dragging the table from the data sources section and either dropping it on a component or dropping it on the page. When you do this, the IDE adds a data provider to the page and a rowset to the SessionBean1 class, as shown in the following figure.

The rowset object makes the connection to the database, executes the queries, and manages the result set. The data provider object provides a common interface for accessing many types of composite data, from database tables, to ArrayList objects, to Enterprise JavaBeans objects. Typically, the only time that you work with the rowset object is when you need to set query parameters. In most cases, you use the data provider object to access and manipulate the data.

Once you have added a data provider to a project, you can bind a component to the data provider by right-clicking the component and choosing Bind to Data. In the Bind to Data dialog box, click the Bind to Data Provider tab to bring it to the front. The Choose a Data Provider drop-down list shows all the project's data providers from which you can select the data provider to bind to the component. After you select the data provider, choose the appropriate data column to be bound to the component. For some components, such as the Drop Down List component, you must choose both a Value field and a Display field.

To define the SQL query to use to retrieve the data, you use the Query Editor, as shown in the following figure. You access this editor through a rowset object.

For More Information

Debugging a Web Application

The IDE has a built-in debugger to help you troubleshoot your programs, as shown in the following figure. You can use it to set breaks and watches, to step through code, and to run until it reaches the code statement that the cursor is on.

You set a breakpoint by clicking in the left margin of the Java Editor. You set a watch by right-clicking a variable or expression choosing New Watch. To run the debugger, choose either Run > Debug Main Project or Run > Run to Cursor from the main menu.

Tip: Here are some other features that you can use to diagnose and resolve problems:

Try It

Note: NetBeans IDE 6.1 features on-demand binding. Where components require Java coding, you must now manually add the binding attribute to components in a Visual Web JSF application. To do so, right-click each component and choose Add Binding Attribute. For more information, see the On-demand Binding Attribute Wiki.

Create, or reuse, a start page. Add a Static Text component, set its text property to Hello, and set its id property to helloText.

Add a Button component. Double-click the Button component to access its action method (button1_action) and replace the method's body with the following code.

Code Sample 1: button1_action Method

String oldString = (String) this.helloText.getText();
this.helloText.setText("Good Bye");
String newString = (String) this.helloText.getText();
return null;

You can press Alt-Shift-F to reformat the code you just added.

Right-click oldString, choose New Watch, and click OK. Do the same for newString.

You see a Watches tab window open at the bottom of the IDE, and each expression to be watched is listed in the window.

Click in the left margin to set a breakpoint for the first statement in the method's body.

You see a pink box appear where you clicked, and the entire line of code gets a pink background. Choose Run > Debug Main Project from the main menu. When the page displays in the Web Browser, click the button. When the debugger breaks in the button1_action method, click the Watches tab in the Debugger window to see the current value of newString and oldString. Choose Run > Step Over from the main menu or click the Step Over button in the toolbar. Look in the Watches tab. Step over the code two more times and observe the Value column in the Watches tab. Explore the Local Variables and Call Stack tabs. Choose Run > Finish Debugger Session to close the debugger session.

For More Information

Summary

You start building a web application by creating a Visual Web JSF Application project. You add pages by right-clicking the Web Pages node in the Projects window and choosing New> Visual Web JSF Page. To design a page, drag components from the Palette onto the page in the Visual Designer. Click the Run Main Project button in the main toolbar to save, build, deploy, and run the application. Use the Page Flow editor to specify page navigation. You can also add link components to a page and set their url property values. Drop Validator and Converter objects onto a component to specify formatting and validation rules. Use Message components and the Message Group component to display runtime error messages. Use properties in the RequestBean1, SessionBean1, and ApplicationBean1 classes to store and pass values from page to page. To create a data provider object and its associated rowset for a database table, drag a table from the Databases section of the Services window onto the page or onto one of its components. Use the Bind to Data menu action to bind components to data provider fields, and to bind components to bean properties. Open a Query Editor on a rowset to modify the SQL query that is used to fill the rowset object. Use the debugger, the HTTP Monitor, the server log, and the Message Group component to diagnose runtime problems.

See Also