Introduction to the Struts Web Framework

This document takes you through the basics of using NetBeans IDE to develop web applications
using the Struts web framework. Struts is an open source framework that extends the Java
Servlet API and employs a Model, View, Controller (MVC) architecture. It enables you to create maintainable, extensible,
and flexible web applications based on standard technologies, such as JSP pages, JavaBeans,
resource bundles, and XML.

This tutorial teaches you how to build a simple MVC application that displays a login page
and returns a success page upon submitting data that passes validation. You learn several
basic features provided by Struts, as well as how these features are implemented using the
IDE. Specifically, you use Struts tags in JSP pages, maintain user data with a Struts ActionForm
bean, and implement forwarding logic using a Struts Action object. You are also
shown how to implement simple validation to your application, including setting up warning
message for a failed login attempt.

For a more fine-grained introduction to Struts, see How
does Struts work? on the official Struts website.
Also, make use of the IDE's Javadoc Index Search (Help > Javadoc Index Search) to view
the Struts Framework API, which
is packaged with the Struts libraries.

The Java installation enables you to optionally install the GlassFish server
and the Apache Tomcat servlet container. You must install one of
these (or register a different server in the IDE) to work through this tutorial.

Overview of the Application

When you use Struts, the framework provides you with a controller servlet, ActionServlet,
which is defined in the Struts libraries that are included in the IDE, and which is automatically
registered in the web.xml deployment descriptor as shown
below. The controller servlet uses a struts-config.xml file to map incoming
requests to Struts Action objects, and instantiate any ActionForm objects
associated with the action to temporarily store form data. The Action object processes
requests using its execute method, while making use of any data stored in the form
bean. Once the Action object processes a request, it stores any new data (i.e., in
the form bean, or in a separate result bean), and forwards the results to the appropriate
view.

Developing a Struts application is similar to developing any other kind of web application
in NetBeans IDE. However, you complement your web development toolkit by taking advantage
of the Struts support provided by the IDE. For example, you use templates in the IDE to create
Struts Action objects and ActionForm beans. Upon creation, the IDE
automatically registers these classes in the struts-config.xml file and lets
you extend this file very easily using menu items in the Source Editor's right-click menu.
Because many web applications use JSP pages for the view, Struts also provides custom tag
libraries which facilitate interaction with HTML forms. Within the IDE's Source Editor, you
can invoke code completion and Javadoc support that helps you to work efficiently with these
libraries.

The following steps demonstrate how to create a simple form that collects user data, performs
simple validation, and outputs the data on a success page.

Setting Up a Struts Application

In the IDE, a Struts application is nothing more than a normal web application accompanied
by the Struts libraries and configuration files. You create a Struts application in the same
way as you create any other web application in the IDE - using the New Web Application wizard,
with the additional step of indicating that you want the Struts libraries and configuration
files to be included in your application.

Choose File > New Project (Ctrl-Shift-N; ⌘-Shift-N on Mac) from the main menu.
Select Java Web in the list of Categories and then select Web
Application in the list of Projects. Click Next.

In the Name and Location panel, enter MyStrutsApp for Project Name and click
Next.

In the Server and Settings panel, select the server to which you want to deploy your
application. Only servers that are registered with the IDE are listed. (To register a
server, click Add next to the Server drop-down list.) Also, note that the Context Path
to your deployed application becomes /MyStrutsApp. Click Next.

Select Struts in the Frameworks panel.

For purposes of this tutorial, do not change any of the configuration values in the lower
region of this panel. The wizard displays the following configuration options.

Action Servlet Name: The name of the Struts action servlet used
in the application. The web.xml deployment descriptor contains an entry
for the action servlet and specifies the appropriate Struts-specific parameters, such
as the path to the servlet class within the Struts library and to the struts-config.xml
configuration file within the application.

Action URL Pattern: Specifies the patterns of incoming requests
which are mapped to the Struts action controller. This generates a mapping entry
in the deployment descriptor. By default, only the *.do pattern is mapped.

Application Resource: Lets you specify the resource bundle which
will be used in the struts-config.xml file for localizing messages. By
default, this is com.myapp.struts.ApplicationResource.

Add Struts TLDs: Lets you generate tag library descriptors for
the Struts tag libraries. A tag library descriptor is an XML document which contains
additional information about the entire tag library as well as each individual
tag. In general this is not necessary, because you can refer to on-line URIs
rather than local TLD files.

Click Finish. The IDE creates the project folder in your file system. As with any web
application in the IDE, the project folder contains all of your sources and the IDE's
project metadata, such as the Ant build script. However, your web application in addition
has all of the Struts libraries on its classpath. Not only are they on the application's
classpath, but they are included in the project and will be packaged with it later when
you build the project.

The project opens in the IDE. The Projects window is the main entry point to your project
sources. It shows a logical view of important project contents. For example, if you expand
several nodes within the new project, it may appear as follows:

Note: Use the Files window (Window > Files) to see all of
your project contents in a directory-based view.

The Struts-specific configuration files, as well as the application's
deployment descriptor, are conveniently placed within the Configuration Files folder. Open
the deployment descriptor (double-click the web.xml file node to have it display
in the Source Editor). In order to handle Struts processing, a mapping is provided for the
Struts controller servlet.

Above, the Struts controller servlet is named action and is defined in the Struts
library (org.apache.struts.action.ActionServlet). It is set to handle all requests
that satisfy the *.do mapping. In addition, initialization parameters for the servlet
are specified by means of the struts-config.xml file, also contained in the WEB-INF
folder.

Creating JSP Pages

Begin by creating two JSP pages for the application. The first displays a form. The second
is the view returned when login is successful.

Many web applications use JSP pages for views in the MVC paradigm, so Struts provides
custom tag libraries which facilitate interaction with HTML forms. These can be easily
applied to a JSP file using the IDE's support for code completion. When you type
in the Source Editor, the IDE provides you with code completion for Struts tags,
as well as the Struts Javadoc. You can also invoke code completion manually by pressing
Ctrl-Space:

The bean taglib
provides you with numerous tags that are helpful when associating a form bean (i.e.,
an ActionForm bean) with the data collected from the form. The
html taglib
offers an interface between the view and other components necessary to a web application.
For example, below you replace common html form tags with Struts' <html:form>
tags. One benefit this provides is that it causes the server to locate or create
a bean object that corresponds to the value provided for html:form's action
element.

Whenever you finish typing in the Source Editor, you can tidy
up the code by right-clicking and choosing Format (Alt-Shift-F).

In the Palette (Window > Palette) in the right region of the IDE, drag a Table
item from the HTML category to a point just above the <html:submit value="Login"
/> line. The Insert Table dialog box displays. Set the rows to 3,
columns to 2, and leave all other settings at 0. Later in the
tutorial, you will attach a stylesheet to affect the table
display.
Click OK, then optionally reformat the code (Alt-Shift-F).
The form in login.jsp now looks as follows:

The html:text element enables you to match the input fields from the form
with properties in the form bean that will be created in the next step. So for example,
the value of property must match a field declared in the form bean associated
with this form.

Move the <html:submit value="Login" /> element into
the second column of the third table row, so that the third table row
appears as follows (changes in bold):

Creating a Success Page

Right-click the MyStrutsApp project node, choose New > JSP, and name
the new file success. In the Folder field, click the adjacent Browse button
and select WEB-INF from the dialog that displays. Click Select Folder to
enter WEB-INF in the Folder field. Any files contained in the WEB-INF folder are
not directly accessible to client requests. In order for success.jsp to
be properly displayed, it must contain processed data. Click Finish.

In the Source Editor, change the content of the newly created page to the following:

By employing the <bean:write> tags, you make use of the bean taglib
to locate the ActionForm bean you are about to create, and display the user
data saved for name and email.

Creating an ActionForm Bean

A Struts ActionForm bean is used to persist data between requests. For example, if
a user submits a form, the data is temporarily stored in the form bean so that it can either
be redisplayed in the form page (if the data is in an invalid format or if login fails) or
displayed in a login success page (if data passes validation).

Type in LoginForm for the Class Name. Then select com.myapp.struts
in the Package drop-down list and click Finish.

The IDE creates the LoginForm bean and opens it in the Source Editor. By default,
the IDE provides it with a String called name and an int called
number. Both fields have accessor methods defined for them. Also, the IDE adds
a bean declaration to the struts-config.xml file. If you open the struts-config.xml
file in the Source Editor, you can see the following declaration, which was added by
the wizard:

The IDE provides navigation support in the struts-config.xml file. Hold down
the Ctrl key and hover your mouse over the LoginForm bean's
fully qualified class name. The name becomes a link, enabling you to navigate directly
to the class in the Source Editor:

In the LoginForm bean in the Source Editor, create fields and accompanying
accessor methods that correspond to the name and email text input fields
that you created in login.jsp. Because name has already been created
in the LoginForm skeleton, you only need to implement email.

Add the following declaration beneath name (changes in bold):

private String name;
private String email;

To create accessor methods, place your cursor on email and press Alt-Insert.

Select Getter and Setter, then in the dialog that displays, select email : String
and click Generate. Accessor methods are generated for the email field.

Note: You can delete the declaration and accessor methods
for number, as it is not used in this tutorial.

Creating an Action Class

The Action class contains the business logic in the application. When form data is
received, it is the execute method of an Action object that processes the
data and determines which view to forward the processed data to. Because the Action
class is integral to the Struts framework, NetBeans IDE provides you with a wizard.

In the Projects window, right-click the MyStrutsApp project node and choose
New > Other. From the Struts category choose Struts Action and click Next.

In the Name and Location panel, change the name to LoginAction.

Select com.myapp.struts in the Package drop-down list.

Type /login in Action Path. This value must match the value you set for
the action attribute of the <html:form> tags in login.jsp.
Make sure settings appear as in the screenshot below, then click Next.

In the third step of the wizard, you are given the opportunity to associate the Action
class with a form bean. Notice that the LoginForm bean you previously created
is listed as an option for ActionForm Bean Name. Make the following adjustments to the
panel:

Delete the forward slash for the Input Resource field

Set Scope to Request (Session is the default scope setting in Struts.)

Deselect the Validate ActionForm Bean option

Click Finish. The LoginAction class is generated, and the file opens in the
Source Editor. Also note that the following action entry is added to the struts-config.xml
file:

The name and scope attributes apply to the form bean that is associated
with the action. Specifically, when an incoming request matches /login, the
Struts framework automatically instantiates a LoginForm object and populates
it with the form data sent in the request. The default value of validate is
set to true. This tells the framework to call the validate method of
the form bean. You deselected this option in the wizard however because you will hand-code
simple validation in the next step, which does not require the validate method.

Implementing Validation

In the Source Editor, browse through the LoginAction class and look at the execute
method:

Currently, the mapping.findForward method is set to unconditionally forward any request
to an output view called success. This is not really desirable; you want to first
perform some sort of validation on the incoming data to determine whether to send the success
view, or any different view.

Using the above logic, the execute method forwards the request to the success
view if the user provides an entry for both name and email fields,
and the email entered contains an '@' sign. Otherwise, the failure view is forwarded.
As will be demonstrated below in Adding forward Entries to struts-config.xml,
you can set the failure view to point back to the form page, so that the user
has another chance to enter data in the correct format.

Setting Up an Error Message

If the login form is returned, it would be good to inform the user that validation failed.
You can accomplish this by adding an error field in the form bean, and an appropriate
<bean:write> tag to the form in login.jsp. Finally, in the Action
object, set the error message to be displayed in the event that the failure
view is chosen.

Adding forward Entries to struts-config.xml

In order for the application to match JSP pages with forwarding conditions returned by LoginAction's
execute method, you need to add forward entries to the struts-config.xml
file.

Open struts-config.xml in the Source Editor, right-click anywhere in the action
entry for LoginForm, and choose Struts > Add Forward.

In the Add Forward dialog box, type success in Forward Name.
Enter the path to success.jsp in the Resource File field (i.e.,
/WEB-INF/success.jsp). The dialog box should now look as follows:
Click Add. Note that the following forward entry was added to struts-config.xml
(changes in bold):

Configuring and Running the Application

The IDE uses an Ant build script to build and run your web application. The IDE generated
the build script when you created the project, basing it on the options you entered in the
New Project wizard. Before you build and run the application, you need to set the application's
default entry point to login.jsp. Optionally, you can also add a simple stylesheet
to the project.

Setting the Welcome Page

In the Projects window, double-click the web.xml deployment descriptor. The
tabs listed along the top of the Source Editor provide you with an interface to the
web.xml file. Click on the Pages tab. In the Welcome Files field, enter login.jsp.
Now click on the Source tab to view the file. Note that login.jsp is now listed
in the welcome-file entry:

<welcome-file>login.jsp</welcome-file>

Attaching a Stylesheet

Add a simple stylesheet to the project. One easy way to do this is by saving
this
sample stylesheet to your computer. Copy the file (Ctrl-C), then
in the IDE, select the Web Pages node in the Projects window and press Ctrl-V).
The file is added to your project.

Link the stylesheet to your JSP pages by adding a reference between the <head>
tags of both login.jsp and success.jsp:

<link rel="stylesheet" type="text/css" href="stylesheet.css">

Running the Application

In the Projects window, right-click the project node and choose Run. The IDE builds the
web application and deploys it, using the server you specified when creating the project.
The browser opens and displays the login.jsp page. Type in some data that
should fail validation, i.e., either leave either field blank, or enter an email address
with a missing '@' sign:

When you click Login, the login form page redisplays, containing an error message:

Try entering data that should pass validation. Upon clicking Login, you are presented
with the success page:

See Also

This concludes the Introduction to the Struts Framework in NetBeans IDE. This document demonstrated
how to construct a simple web MVC application in NetBeans IDE using the Struts Framework,
and introduced you to the IDE's interface for developing web applications. You were shown
how to use Struts tags in JSP pages, temporarily store user data in a Struts ActionForm
bean, and implement forwarding logic using a Struts Action object. You are also
shown how to implement simple validation to your application, including setting up warning
message for a failed login attempt.