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-INF/classes/ApplicationResources.properties

Contains the messages (fixed texts) of 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>

  <!-- Standard Action Servlet Mapping -->

Page 5 of 16

Stepping through Jakarta Struts

<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 database. The ActionForm bean may also be used to initialize form controls and to validate the data entered by the user.

Page 6 of 16

Stepping through Jakarta Struts

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>

</action-mappings>

Page 7 of 16

Stepping through Jakarta Struts

</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 filename - is the logical name of the form bean (from the form-bean section)input - validation errors should be shown on this pagescope - 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>

Page 8 of 16

Stepping through Jakarta Struts

<h3>Example Submit Page</h3>

<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 name="lastName" scope="request"> . . . </logic:present>

Only if the name "lastName" is present in the request object we'll evaluate what's inside the opening and closing tags. Therefore nothing will show up until the "perform" method is called.

<logic:equal name="submitForm" property="age" value="a"> young</logic:equal>

If the property "age" in the ActionForm bean has the value "a" (age 0-19) the text "young" is send to the browser.

<bean:write name="lastName" scope="request"/> Sends the value of the "lastName" attribute in the

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 nameerror.address=<li>Enter your addresserror.sex=<li>Enter your sexerror.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:

Page 15 of 16

Stepping through Jakarta Struts

- 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

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