Step 1: Getting StartedR. Kevin ColeMarch 12, 2007

This tutorial is a multipart introduction to the development of a Create, Read, Update and Delete (CRUD) application using the Struts-2 framework. The application is a simple address-book.

Developers new to Struts 2 are the target of this tutorial. It is assumed that the reader is familiar with a web framework such as Struts 1, J2EE technologies such as JDBC, and is comfortable working with the Apache ant build tool. It was written by the author as a first exercise in developing a Struts-2 web application.

In this first part of the tutorial, the following subjects are covered.

The Client-side Address-Form An address data entry form with some minimal css decorating is created along with a corresponding action and address bean to move address-data between the address-view and the server.

Deploy and Test the Application Tests are run to verify that data is collected from the address form on the client page and that an address bean is created and successfully populated on the server.

The source code directory is split into two parts. The main code that runs the website and the test code that implements the unit tests. Create a directory tree like the one shown on the left. The ant build file expects this type of structure but ant is quite flexible should you want to do things in another manner; just be certain to change build.xml to reflect your directory structure.

The lib directory holds the jar files to be deployed with the web application in a war file. For step 1 of this tutorial, the lib directory is a copy of the jar files found in the struts-blank.war demonstration application in its WEB-INF/lib directory.

A second directory lib.test will hold jar files that are required for unit testing the application. The jar files in lib.test are not deployed in the war file to the application server. The jar files in lib.test are not included in the struts-blank.war and will have to be downloaded separately.

The struts configuration files for the CRUD application are created in the src/main/resources directory. The basic struts.xml configuration does little more than include this tutorial's configuration file crud.xml

The required libraries for the JUnit and JWebUnit unit testing frameworks are installed in lib.test. (It's a good idea not to mix libraries that you will deploy in your war file with development-only libraries). The following jar files will need to be installed into lib.test.

Container-Independent Test - AddressBookActionTest

The first test class, AddressBookActionTest, tests the Struts action outside the servlet container. The method testAddressBookAction verifies that the AddressBookAction returns SUCCESS when it is executed and checks that we can get and populate an Address bean.

/** Test that the action is created and the default message is set. */ public void testAddressBookAction() throws Exception { AddressBookAction addressBook = new AddressBookAction(); String result = addressBook.execute(); assertTrue("Expected a success result!", ActionSupport.SUCCESS.equals(result)); assertTrue("Expected the default message!", addressBook.getText(AddressBookAction.MESSAGE).equals(addressBook.getMessage())); }

/** When the setAddress message is called on the AddressBookAction, the getAddress method * should return that address. */ public void testAddress() throws Exception { AddressBookAction addressBook = new AddressBookAction(); addressBook.setAddress( TEST_ADDRESS );

/** When the reset method is called, the address bean is set to null and the default message * should be set. */ public void testReset() throws Exception { AddressBookAction addressBook = new AddressBookAction(); addressBook.setAddress( TEST_ADDRESS ); addressBook.reset();

In-Container Test - AddressBookWebTest

The second test, AddressBookWebTest, checks that the address-form is present on the page and that it has the correct fields and default values. This test is run inside the servlet container. It is a live test of the running website.

Neither of the above tests will run at this point. They won't even compile until we create the action and the bean. The tests provide us with an initial contract that will govern the behavior of the classes that produced in the next section.

There are two java classes and an XML validator used to process our address entry form. A struts action called AddressBookAction will handle the setup and processing of the address-form and an address information holder bean called Address will handle the transfer of the address-form data. The validation of the data contained within the Address bean is defined in AddressBookAction-validator.xml

The AddressBookAction includes two methods that are called when buttons are pressed in the address-form. These are reset() and udpate(). Each button in the address-form will be assigned a method in this class. In this step, the update() method sets a message for display by the address-form.

Since all fields in our address form are required, a field-validator of requiredstring is attached to each. The zipcode field gets an additional validation to ensure that it is exactly 5 digits. A server-side field validator is attached to the state field to ensure that it is exactly two upper-case characters in the range of A-Z.

In this example, the name=address.name attribute in the field validator informs the Struts-2 framework that the string to be validated is acquired by making the following call on an instance of AddressBookAction: addressBookAction.getAddress().getName()

The address entry form will have five fields and a status-bar. To meet our test requirements, the fields will be called:

address.name

address.address

address.city

address.state

address.zipcode

The status-bar at the base of the form is populated using the Struts UI property tag.This writes the value returned by a call to AddressBookAction.getMessage() into the status line.

Note about themes: Struts-2 provides a mechanism for decorating forms by the declaring a theme. For instance, the default theme will wrap labels and fields on a form within a table making it remarkably simple to layout a form. This can cause problems with simple things like adding a row of buttons at the base of a form (the default theme wants to lay them out in a column). For that reason, the address-form in this example declares the theme as simple; meaning - don't auto-format the form. The address-form handles its own layout.

Here is the address entry form (with an applied style found in skin.css).

This completes step 1 in the Struts CRUD Tutorial. In this step a simple address book user interface was constructed that accepts address data entered in a browser and sends the data to a Struts-2 action where the data receives some cursory validation.

In step 2, the state textfield on the address-form will be replaced with a drop-down select/options box. This will give us exact control over the contents of the state field. A collection representing the 50 U.S. States will be injected, using Spring's Inversion of Control mechanism, into the AddressBookAction class.