Stepping through Jakarta Struts

Stepping
through
Jakarta Struts

Page 1 of 16
Stepping through Jakarta Struts

1.What is Struts?
Struts, from the Jakarta Project, is a development framework for Java servlet
applications based upon the Model-View-Controller (MVC) design paradigm. The
purpose of this article is to give you a quick intro to Struts, covering the necessary
details to make it possible to build a simple one-page example containing an HTML
form. Then I'll refine this example to show you additional features of Struts. I'll
assume that you are familiar with Java servlet programming and the MVC
architecture.

- Figure 1: The MVC architecture -

Struts is comprised of a controller servlet, beans and other Java classes,
configuration files, and tag libraries. This means that when you have downloaded
Struts (and I'll come back to how this is done) you have available:
• a controller for your application (the Struts servlet acts as a common
controller for the whole application)
• a collection of Java beans and other helper classes that you use in the "Model"
part of your application
• a collection of tag libraries used in your jsp-pages
To glue these things together Struts uses a set of configuration files. Together this
gives you the skeleton that you can use to "strut" your application.
Struts has been designed to give you modularity and loose couplings in your
application. If you're building a simple, small application you might find it
complicated to have to create and handle so many files. You might even be tempted
to put all your code in a single jsp-file. My advice to you is: don't do it! I'm sure you
can build a single-page application faster using only one jsp-page, but if we're
talking about more complex applications, the extra effort put in by using a modular
framework will soon be rewarded.
If you hang on I'll guide you through the complete Struts application setup and
hopefully show you how each piece fits in.

Page 2 of 16
Stepping through Jakarta Struts

2.Our first Struts application

Our first small application will be a page with an HTML form containing all the well-
known controls. As you can see I have not tried to make the GUI look nice - we're
architects now - not graphical designers:

- Figure 2: The first, simple application -

When we submit this page it should redisplay itself without loosing the data that we
have entered. Such an application is always a good first exercise if you want to learn
about new tools or technologies.
But before we start building the application we need to download and install Struts.
2.1.Step 0: Downloading and installing Struts
Struts is downloaded from the Jakarta Project at http://jakarta.apache.org/struts/. The
download address for the current version - 1.0.2 - is
http://jakarta.apache.org/builds/jakarta-struts/release/v1.0.2. The simplest way to install
Struts is to copy a small Struts application, packed in "struts-blank.war", from the
download file to your Servlet container. If you're using Tomcat and many other servlet
containers you place the war-file in the "webapps" folder and you now only need to
restart your server and you'll have "struts-blank" running. On Tomcat you can check
your installation with this URL: http://localhost:8080/struts-blank/index.jsp. The
download contains an "install" file which contains installation tips for several
containers.
This should emphasize that Struts can be seen as the core of a normal servlet
application - it's not a modification to your servlet container or anything like that.
While picking up the struts-blank application you might as well take and install the
"struts-documentation.war" application, which contains a lot of Struts documentation
- for example the User Guide.
2.2.Step 1: The directories and files of a Struts application
You'll need to know the directory structure of a Struts application, and what's put in
the directories. The "struts-blank" application is well-suited for this presentation,
since it contains a minimum number of files:

Page 3 of 16
Stepping through Jakarta Struts

- Figure 3: The Struts directory structure -

File or Directory name Purpose

META-INF Contains meta information. Used by

utilities etc.

WEB-INF/classes This is where you place you own Java

classes.

WEB- Contains the messages (fixed texts) of

INF/classes/ApplicationResources.properties the application. Error messages are also
put here.

WEB-INF/lib/struts.jar Contains the Struts servlet, helper

classes, taglib code etc.

WEB-INF/*.tld The Struts tag libraries.

WEB-INF/struts-config.xml A Struts configuration file. More on this

later.

WEB-INF/web.xml The usual configuration file for the servlet

container. More on this later.

index.jsp The jsp-files (and html-files) may be

placed in the root of the application
directory. "struts-blank" contains this
single jsp-file.

- Table 1: The files and directories in a Struts application -

Page 4 of 16
Stepping through Jakarta Struts

2.3.Step 2: Starting on a new Struts application

The easiest way to start on a new Struts application is to take an existing one--for
example "struts-blank"--and make a copy of it in the "webapps" directory. When you
get more experienced with Struts you'll probably add your own standard classes and
files to your setup, and you'd then start taking a copy of this directory structure. For
our first application we simply copy all files and directories in the folder "struts-
blank" and rename the folder to "myproject". The contents of some of the files must
now be edited.

2.4.Step 3: The web.xml file

The web.xml file is where servlets and other stuff are defined to the servlet
container. We'll remove some unnecessary things from the web.xml file so it looks
like this:

<?xml version="1.0" encoding="ISO-8859-1"?>

<!DOCTYPE web-app
PUBLIC "-//Sun Microsystems, Inc.//DTD Web Application 2.2//EN"
"http://java.sun.com/j2ee/dtds/web-app_2_2.dtd">

<web-app>

<!-- Standard Action Servlet Configuration (with debugging) -->

<servlet>
<servlet-name>action</servlet-name>
<servlet-class>
org.apache.struts.action.ActionServlet
</servlet-class>
<init-param>
<param-name>application</param-name>
<param-value>ApplicationResources</param-value>
</init-param>
<init-param>
<param-name>config</param-name>
<param-value>/WEB-INF/struts-config.xml</param-value>
</init-param>
<init-param>
<param-name>debug</param-name>
<param-value>2</param-value>
</init-param>
<init-param>
<param-name>detail</param-name>
<param-value>2</param-value>
</init-param>
<init-param>
<param-name>validate</param-name>
<param-value>true</param-value>
</init-param>
<load-on-startup>2</load-on-startup>
</servlet>

Page 5 of 16
Stepping through Jakarta Struts

<!-- Standard Action Servlet Mapping -->

<servlet-mapping>
<servlet-name>action</servlet-name>
<url-pattern>*.do</url-pattern>
</servlet-mapping>

<!-- Struts Tag Library Descriptors -->

<taglib>
<taglib-uri>/WEB-INF/struts-bean.tld</taglib-uri>
<taglib-location>/WEB-INF/struts-bean.tld</taglib-location>
</taglib>

<taglib>
<taglib-uri>/WEB-INF/struts-html.tld</taglib-uri>
<taglib-location>/WEB-INF/struts-html.tld</taglib-location>
</taglib>

<taglib>
<taglib-uri>/WEB-INF/struts-logic.tld</taglib-uri>
<taglib-location>/WEB-INF/struts-logic.tld</taglib-location>
</taglib>

</web-app>

- Figure 4: The web.xml file -

The file contains three sections:

• the definition of the Struts servlet named "ActionServlet"

• the URL mapping for the calls to this servlet
• the definitions of the Struts tag libraries

You'll see that the servlet will be called if our browser requests a file called <some-
name>.do. So when we submit the form in our one-page application we'll decide to
use the action-name "submit.do". How the Struts servlet knows what to do with this
request we'll discover next.

2.5.Step 4: The struts-config.xml file

Up to now it has been simple and straightforward, right? Now I'll need to explain a
few things. First I'll tell you what services the servlet offers to us, and then we'll see
how we give it the instructions for a specific request. If you look at figure 1--the
MVC architecture--you'll notice the arrows marked "2" and "3". This is the interaction
between the servlet controller and the model, including the business logic. When you
use Struts then part of this interaction is as follows:

• First of all the Struts servlet will automatically transfer the data from your
form into a JavaBean that you should supply. This bean is called the
ActionForm bean, because your bean must extend the Struts "ActionForm"
class. You may think of this bean as a buffer between the browser and your

Page 6 of 16
Stepping through Jakarta Struts

database. The ActionForm bean may also be used to initialize form controls
and to validate the data entered by the user.
• Secondly the Struts servlet will call a class which you specify and it is referred
to as the Action class. This class may use the data in the ActionForm bean.
The Action class is where your application coding starts. When your class
finishes it returns control to the Struts servlet.

- Figure 5: The Action and ActionForm classes -

The mapping of the request (remember: <some-name>.do) to a specific Action and

ActionForm class is done in the struts-config.xml file. I have edited the file from
"struts-blank" to suit our one-page application:

<?xml version="1.0" encoding="ISO-8859-1" ?>

<!DOCTYPE struts-config PUBLIC

"-//Apache Software Foundation//DTD Struts Configuration 1.0//EN"
"http://jakarta.apache.org/struts/dtds/struts-config_1_0.dtd">

<struts-config>

<!-- ========== Form Bean Definitions ================= -->

<form-beans>

<form-bean name="submitForm"
type="hansen.playground.SubmitForm"/>

</form-beans>

<!-- ========== Action Mapping Definitions ============ -->

<action-mappings>

<action path="/submit"
type="hansen.playground.SubmitAction"
name="submitForm"
input="/submit.jsp"
scope="request">
<forward name="success" path="/submit.jsp"/>
<forward name="failure" path="/submit.jsp"/>
</action>

Page 7 of 16
Stepping through Jakarta Struts

</action-mappings>

</struts-config>

- Figure 6: The struts-config.xml file -

As you can see the file contains two sections: the form-beans section that lists the
ActionForm beans, and the action-mappings.

In the form-beans section you give the bean a logical name (referred to in the
action-mapping) and specify the path for the class file.

The action-mappings are the most interesting. The attributes given are these:

path - name of the request: "submit.do". You don't enter the ".do"-part here.
type - the path for the Action class file
name - is the logical name of the form bean (from the form-bean section)
input - validation errors should be shown on this page
scope - specifies how long the form bean should live. You may specify "session"
instead.

The forward tag tells the servlet where to go if it receives either "success" or "failure"
from the Action class. We'll return to this feature. In our simple case we always
return to the same page.

It's wise to standardize on class names. I've used these simple conventions:

Class Actual name

ActionForm <action>Form, where <action> is the action-path-name
Action <action>Action

We're now ready to code the ActionForm and the Action classes--and the jsp view.

2.6.Step 5: Building the jsp-page

In order for the ActionForm bean to work, you must use Struts' own tags for creating
the HTML form and the controls in it. I'll not go into details about these tags - they're
clearly modeled after the "real" HTML-tags. The form page from figure 2, which we
call submit.jsp, contains this HTML:

<%@ page language="java" %>

<%@ taglib uri="/WEB-INF/struts-bean.tld" prefix="bean" %>
<%@ taglib uri="/WEB-INF/struts-html.tld" prefix="html" %>
<%@ taglib uri="/WEB-INF/struts-logic.tld" prefix="logic" %>

<html>
<head><title>Submit example</title></head>
<body>

<h3>Example Submit Page</h3>

Page 8 of 16
Stepping through Jakarta Struts

<html:errors/>

<html:form action="submit.do">
Last Name: <html:text property="lastName"/><br>
Address: <html:textarea property="address"/><br>
Sex: <html:radio property="sex" value="M"/>Male
<html:radio property="sex" value="F"/>Female<br>
Married: <html:checkbox property="married"/><br>
Age: <html:select property="age">
<html:option value="a">0-19</html:option>
<html:option value="b">20-49</html:option>
<html:option value="c">50-</html:option>
</html:select><br>
<html:submit/>
</html:form>

</body>
</html>

- Figure 7: The submit.jsp file -

The 3 taglib lines define the Struts tag libraries. In this jsp-file we only use the html-
library.

The html:errors section is used to display validation errors. We'll return to that.

Most of the well-known HTML-attributes for the controls (for example events) can
also be used with Struts tags. Note that Struts insists on using the word "property"
instead of the more familiar "name".

2.7.Step 6: Coding the ActionForm class

This class must extend the Struts ActionForm, and must have setters and getters for
all the form controls in the jsp-page (5 in our example). Optionally it may have a
validation method, which I'll demonstrate later in this article. Note that I've entered
a default value for the "lastName" text field.

package hansen.playground;

import javax.servlet.http.HttpServletRequest;
import org.apache.struts.action.*;

public final class SubmitForm extends ActionForm {

/* Last Name */
private String lastName = "Hansen"; // default value
public String getLastName () {
return (this.lastName);
}
public void setLastName (String lastName) {
this.lastName = lastName;
}

Page 9 of 16
Stepping through Jakarta Struts

/* Address */
private String address = null;
public String getAddress () {
return (this. address);
}
public void setAddress (String address) {
this.address = address;
}

/* Sex */
private String sex = null;
public String getSex () {
return (this.sex);
}
public void setSex (String sex) {
this.sex = sex;
}

/* Married status */
private String married = null;
public String getMarried () {
return (this.married);
}
public void setMarried (String married) {
this.married = married;
}

/* Age */
private String age = null;
public String getAge () {
return (this.age);
}
public void setAge (String age) {
this.age = age;
}

This class is placed in the WEB-INF/classes/hansen/playground directory.

2.8.Step 7: Coding the Action class

The Action class is--seen from the application programmer's perspective--the heart
of the application. This is where you must decide how you'll separate your own
application code. Most often the Action class should be kept as "thin" as possible,
placing business logic in other beans or even EJB's on other servers.

The implementation of the Action class must contain a "perform" method, which
receives the request and response objects, the instance of the ActionForm bean and
the action mapping information from the configuration file. A very simple Action
class, which simply lets the request pass unaltered, is given as follows:

package hansen.playground;

Page 10 of 16
Stepping through Jakarta Struts

import javax.servlet.http.*;
import org.apache.struts.action.*;

public final class SubmitAction extends Action {

public ActionForward perform (ActionMapping mapping,

ActionForm form,
HttpServletRequest request,
HttpServletResponse response) {

SubmitForm f = (SubmitForm) form; // get the form bean

// and take the last name value
String lastName = f.getLastName ();
// Translate the name to upper case
//and save it in the request object
request.setAttribute ("lastName", lastName.toUpperCase ());

// Forward control to the specified success target

return (mapping.findForward ("success"));
}
}

The manipulation of the "last name" value is only done to show how to access the
form bean and how you may store data for use by other components, e.g. the jsp-
file.

You may recall that the target of "success", which was specified in the Struts config
file, was the submit.jsp file.

This class is also placed in the WEB-INF/classes/hansen/playground directory.

An important thing to remember is that Struts only creates a single instance of the
Action class, shared amongst all users of the application. You should therefore not
use member variables, but only local variables.

2.9.Step 8: Testing your application

First restart your servlet container. Normally you'll have to do this whenever you
modify a config file or update a Java class.

To test our example, enter this URL in the browser:

http://localhost:8080/myproject/submit.jsp. If your application works, you'll see that
"Last Name" is filled with "Hansen" (which means that Struts has already created an
instance of the ActionForm bean, and extracted the data from it). Now enter data in
all the controls and press "Submit". Note that the URL changes to "submit.do", and
that all data stays unchanged in the form.

You might also want to try to enter some "problematic" characters like single and
double quotes, or the "<" and ">" characters in the text fields to see that Struts is
perfectly capable of handling them correctly. Use the browsers "view source" to see
how Struts does it.

Page 11 of 16
Stepping through Jakarta Struts

3. Using the tag libraries

In step 7 you saw how we stored the users last name in uppercase in the request
object. To give you an idea of how some of the other Struts tags work, I'll show how
to display this name--with a greeting to the user.

At the bottom of the submit.jsp file we add these tags:

<logic:present name="lastName" scope="request">

Hello
<logic:equal name="submitForm" property="age" value="a">
young
</logic:equal>
<logic:equal name="submitForm" property="age" value="c">
old
</logic:equal>
<bean:write name="lastName" scope="request"/>
</logic:present>

The tags have this meaning:

Tags Purpose
<logic:present Only if the name "lastName" is present in the
name="lastName" scope="request"> request object we'll evaluate what's inside the
... opening and closing tags. Therefore nothing will
</logic:present> show up until the "perform" method is called.
<logic:equal name="submitForm" If the property "age" in the ActionForm bean has
property="age" the value "a" (age 0-19) the text "young" is send
value="a"> to the browser.
young
</logic:equal>
<bean:write name="lastName" Sends the value of the "lastName" attribute in the
scope="request"/> request object to the browser.

With these extra lines the page could display like this in the browser:

Page 12 of 16
Stepping through Jakarta Struts

- Figure 8: Output from Struts tags -

4. Validating your input

I'll finish this introduction to Struts by showing you how to make some simple
validations. Let's assume that the user of our form must enter his or her last name,
address, sex and age. The simplest way to implement validation is in the ActionForm
bean, but you can also do it in the Action class.

Step a: Code the "validate" method in ActionForm

While we're modifying the code, we also add some log messages so we can check
the data we receive from the form:

public ActionErrors validate (ActionMapping mapping,

HttpServletRequest request) {
// Log the forms data
servlet.log("Lastname:" + lastName);
servlet.log("Address:" + address);
servlet.log("Sex:" + sex);
servlet.log("Married:" + married);
servlet.log("Age:" + age);

// Check for mandatory data

ActionErrors errors = new ActionErrors ();
if (lastName == null || lastName.equals ("")) {
errors.add ("Last Name", new ActionError ("error.lastName"));
}
if (address == null || address.equals ("")) {
errors.add ("Address", new ActionError ("error.address"));
}
if (sex == null || sex.equals ("")) {
errors.add ("Sex", new ActionError ("error.sex"));
}
if (age == null || age.equals ("")) {
errors.add ("Age", new ActionError ("error.age"));
}
return errors;

Page 13 of 16
Stepping through Jakarta Struts

The servlet controller will check if the returned ActionErrors object is empty or not. If
not empty the controller will return to the page specified by the "input" parameter in
the config file. In our example this is the submit.jsp page.

Step b: Define the error message text

The error messages are taken from the ApplicationResources.properties file. The
messages are inserted in the jsp-page by using the Struts tag <html:errors/>. In
order to have a nice formatting of the messages you must also define two keys called
errors.header and errors.footer. This is our ApplicationResources.properties file (note
that HTML tags may be included as you like it):

errors.header=<h4>Validation Error(s)</h4><ul>
errors.footer=</ul><hr>

error.lastName=<li>Enter your last name

error.address=<li>Enter your address
error.sex=<li>Enter your sex
error.age=<li>Enter your age

- Figure 9: The ApplicationResources.properties file -

Now restart the servlet container.

Step c: Test the validations

If we don't enter anything in the form we'll get this answer:

Page 14 of 16
Stepping through Jakarta Struts

- Figure 10: Display of validation errors -

Note that age 0-19 is selected as default according to normal HTML selection list
practice.

5. The total picture

Here's a picture that shows how the Struts components work together:

- Figure 11: The Struts components -

6. Final remarks

There's a lot more to say about Struts, but having kept my example simple I hope
that I have brought forward the basic architecture of Struts. A very important
characteristic of this architecture is the loose coupling between modules. There are
no hardcoded file names or class names in the controller or in the Action or
ActionForm classes.

Another thing is that all text in your pages may be placed in the
ApplicationResources.properties file--you may even implement multi-language
support using these properties-files.

7. Resources

There are a lot of good resources available from the Struts web site. My favorites
are these:

• Introduction to Jakarta Struts Framework by Sue Spielman: article 1 -

article 2 - article 3

Page 15 of 16
Stepping through Jakarta Struts

• Struts Tutorial by Stephan Wiesner

• Using Struts by Larry Maturo (pdf file)
• The Struts Kickstart FAQ
• and of course: The Jakarta Struts User Guide

Page 16 of 16