Migrating Struts Apps to Struts 2

Most people are familiar with Struts, whether it is from direct experience or from reading articles or books. In this series of articles we will cover the features of Struts2 from a Struts perspective - by migrating a simple application.

Before we start the migration process, a little background to Struts2 is needed. The first part of this article will introduce Struts2, along with some of the core architectural differences that will help to conceptually put everything together. The second part will cover migrating the back-end - an in-depth look at the differences between actions; action related framework features; and action configuration. The final part of this article will address the user interface. We'll cover the architecture; talk about UI components, themes and tags; and put a new face on our application.

It is not my intent to cover every migration scenario available, but rather to introduce the concepts and new features available in Struts2 by starting from a common starting point. Armed with this knowledge, migrating an application of any size should be a piece of cake!

Introduction / History

The first version of Struts was released in June 2001. It was born out of the idea that JSPs and servlets could be used together to provide a clean separation between the view and the business or application logic of a web application. Before Struts, the most common options were to add business and application logic to the JSP, or to render the view from servlets using println() statements.

Since its release, Struts has become the de-facto standard for web application. With this popularity have come enhancements and changes - both to keep up with the ever-changing requirements for a web application framework, but also to match features with the ever-increasing number of competing frameworks available.

To that end, there have been several proposals for the next generation of Struts. The two alternatives that have become the most cohesive in the past year are Shale and Struts Ti. Shale is a component based framework, and just recently has become its own top-level Apache project, where Struts Ti continues the front controller or model-view-controller pattern that has made Struts so successful.

The WebWork project was started as a Struts revolution - as a fork of the Struts code to introduce new ideas, concepts and functionality that may not be compatible with the original Struts code - and it was first released in March 2002. WebWork is a mature framework, having undergone several minor and major releases.

In December 2005 it was announced that WebWork and the Struts Ti would join forces. Since that time, Struts Ti has become Struts Action Framework 2.0, and the successor to Struts.

Finally, it should be noted that neither the Struts nor WebWork projects are going away. While interest is high, and willing developers are available, both of these projects will continue - all the while having bugs fixed, and adding enhancements and new features.

A Request Walk-through

Before we start looking at the low level details of how to convert an application from Struts to Struts2, let's take a look at what the new architecture looks like by walking through the request processing.

As we walk through the request lifecycle you should notice one important fact - Struts2 is still a front controller framework. All of the concepts that you are familiar with will still apply.

This means:

• Actions will still be invoked via URL's
Data is still sent to the server via the URL request parameters and form parameters
•  
All those Servlet objects (request, response, session, etc.) are all still available to the Action

From a high-level overview, this is how the request is processed:

The processing of a request can be broken into these 6 steps:

1. A request is made and processed by the framework - the framework matches the request to a configuration so that the interceptors, action class and results to use are known.
2. The request passes through a series of interceptors - interceptors, and interceptor stacks, can be configured at a number of different levels for the request. They provide pre-processing for the request as well as cross-cutting application features. This is similar to the Struts RequestProcessor class which uses the Jakarta Commons Chain component.
3. The Action is invoked - a new instance of the action class is created and the method that is providing the logic for this request is invoked. We will discuss this in more detail in the second part of this series; however, in Struts2 the configuration of the action can specify the method of the action class to be invoked for this request.
4. The Result is invoked - the result class that matches the return from processing the actions' method is obtained, a new instance created and invoked. One possible outcome of the result being processed is rendering of a UI template (but not the only one) to produce HTML. If this is the case, then Struts2 tags in the template can reach back into the action to obtain values to be rendered.
5. The request returns through the Interceptors - the request passes back through the interceptors in reverse order, allowing any clean-up or additional processing to be performed.
6. The response is returned to the user - the last step is to return control back to the servlet engine. The most common outcome is that HTML is rendered to the user, but it may also be that specific HTTP headers are returned or a HTTP redirect is invoked.

As you may have noticed, there are some differences. The most obvious one is that Struts2 is a pull-MVC architecture. What does this mean? From a developers perspective it means that data that needs to be displayed to the user can be pulled from the Action. This differs from Struts, where data is expected to be present in beans in either the HTTP page, request or session scopes. There are other places that data can be pulled from, and we'll talk about those as the scenarios come up.

Configuring the framework

The first, and most important configuration, is the one that enables the web application framework within the servlet containers web.xml file.

The configuration that everyone should be familiar with for Struts is:

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

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

For Struts2 there are very few changes. The most significant is that the dispatcher has been changed from a servlet to a servlet filter. The configuration is just as easy as for a servlet, and shown here:

    <filter>
	<filter-name>webwork</filter-name>
	<filter-class>
	    org.apache.struts.action2.dispatcher.FilterDispatcher
	</filter-class>
    </filter>

    <filter-mapping>
	<filter-name>webwork</filter-name>
	<url-pattern>/*</url-pattern>
    </filter-mapping>

Similar to the servlet configuration, the filter configuration defines a name (for reference) and the class of the filter. A filter mapping links the name with the URI pattern that will invoke the filter. By default, the extension is ".action". This is defined in the default.properties file (within the Struts2 JAR file) as the "struts.action.extension" property.

SIDEBAR: The "default.properties" file is the place that many configuration options are defined. By including a file with the name "struts.properties" in the classpath of your web application, with different values for the properties, you can override the default configuration.

For Struts, the servlet configuration provides an init-param tag that defines the names of the files used to configure Struts. Struts2 does not have such a configuration parameter. Instead, the default configuration file for Struts2 has the name "struts.xml" and needs to be on the classpath of the web application.

SIDEBAR/TIP: Since there is a namespace separation between the Struts actions (with a ".do" extension) and the Struts2 actions (with a ".action") extension, there is no reason why they cannot co-exist within the same web application. This is a great way to start the migration process - add the necessary configuration, and start developing all new functionality in Struts2. As time and resources permit, the remaining actions can be converted. Or, the two frameworks can co-exist peacefully forever, since there is no reason that the existing action ever needs to be migrated. Another migration strategy is to update only the actions by changing the Struts2 extension to ".do". This allows the existing JSP's to remain the same and be re-used.

Deconstructing the Actions

In the request walk-through we spoke about some of the differences between Struts and Struts2 from a high level. Let's take it a step deeper now, and look at the differences between the structures of the actions in each framework.

Let's first review the general structure of the Struts action. The general form of the Struts action looks like this:

public class MyAction extends Action {
    public ActionForward execute(ActionMapping mapping,
                                 ActionForm form,
                                 HttpServletRequest request,
                                 HttpServletResponse response)
            throws Exception {
        // do the work
        return (mapping.findForward("success"));
    }
}

When implementing a Struts action, you need to be aware of the following items:

1. All actions have to extend the Action base class.
2. All actions have to be thread-safe, as only a single action instance is created.
3. Because the actions have to be thread-safe, all the objects that may be needed in the processing of the action are passed in the method signature.
4. The name of the method that is invoked for the processing of the action is "execute" (there is a DispatchAction class available in Struts which can re-route the method to be executed to another method in the same action, however the initial entry point from the framework into the action is still the "execute" method).
5. An ActionForward result is returned using a method from the ActionMapping class, most commonly via the "findForward" method call.

In contrast, the Struts2 action provides a much simpler implementation. Here's what it looks like:

public class MyAction {
   public String execute() throws Exception {
        // do the work
        return "success";
   }
}

The first thing you may have noticed is that the action doesn't extend any classes or interfaces. In fact, it goes further than this. By convention, the method invoked in the processing of an action is the "execute" method - but it doesn't have to be. Any method that follows the method signature public String methodName() can be invoked through configuration.

Next, the return object is a String. If you don't like the idea of string literals in your code, there is a helper interface Action available that provides the common results of "success", "none", "error", "input" and "login" as constants.

Finally, and perhaps the most revolutionary difference from the original Struts implementation, is that the method invoked in the processing of an action (the "execute" method) has no parameter. So how do you get access to the objects that you need to work with? The answer lies in the "inversion of control" or "dependency injection" pattern (for more information Martin Fowler has an informative article at http://www.martinfowler.com/articles/injection.html). The Spring Framework has popularized this pattern, however, the predecessor to Struts2 (WebWork) started using the pattern around the same time.

To understand the inversion of control better, let's look at an example where the processing of the action requires access to the current requests HttpServerRequest object.

The dependency injection mechanism used in this example is interface injection. As the name implies, with interface injection there is an interface that needs to be implemented. This interface contains setters, which in turn are used to provide data to the action. In our example we are using the ServletRequestAware interface, here it is:

public interface ServletRequestAware {
    public void setServletRequest(HttpServletRequest request);
}

When we implement this interface, our simple action from above becomes a little more complex - but now we have a HttpServerRequest object to use.

public class MyAction implements ServletRequestAware {
   private HttpServletRequest request;
   public void setServletRequest(HttpServletRequest request) {
        this.request = request;
   }
   public String execute() throws Exception {
        // do the work using the request
        return Action.SUCCESS;
   }
}

At this point, some alarm bells are probably going off. There are now class level attributes in the action - which, although not thread-safe, is actually okay. In Struts2, an action instance is created for each request. It's not shared and it's discarded after the request has been completed.

There is one last step left, and that is to associate the ServletConfigInterceptor interceptor with this action. This interceptor provides the functionality to obtain the HttpServletRequest and inject it into actions that implement the ServletRequestAware interface. For the moment, don't worry about the details of the configuration - we'll go into much more detail in the next article. The important thing at the moment is to understand that the interceptor and the interface work hand-in-hand to provide the dependency injection to the action.

The benefit to this design is that the action is completely de-coupled from the framework. The action becomes a simple POJO that can also be used outside of the framework. And for those that encourage unit testing, testing a Struts2 action is going to be significantly easier than wrestling to get a Struts action into a StrutsTestCase or a MockStrutsTestCase unit test.

Conclusion / Wrap-Up

By now you should be familiar with the basics of Struts2 - the high level architecture and basic request workflow. You should be able to configure Struts2 in a servlet container, and know the differences between the action for Struts and Struts2.

In the next article we will introduce the example application that will be migrated, as well as building on the knowledge attained here to migrate the example applications' actions from Struts to Struts2. What we'll end up with is a working application using JSTL, JSP and Struts2. We'll also further investigate the differences between actions; configuration of actions and other framework elements; and talk more about the action related framework features.

About the author

Ian Roughley is a speaker, writer and independent consultant based out of Boston, MA. For over 10 years he has been providing architecture, development, process improvement and mentoring services to clients ranging in size from fortune 10 companies to start-ups. Focused on a pragmatic and results-based approach, he is a proponent for open source, as well as process and quality improvements through agile development techniques.