Our sanity-checking application will be as simple as possible. It will consist of only the minimum libraries necessary to get:

The Struts 2 Configuration Browser Plug-in lets us check out what Struts 2 thinks our configuration is. (Believe it or not, we do occasionally make mistakes. And ultimately it's the framework that decides what works, not us!)

Log4J is the ubiquitous logging framework. We'll discuss logging later in the book; however, we will use logging before then. Logging statements in the code can be safely ignored until then. The following is the table listing the minimum jar files to get a Struts 2 application running:

The dependency on the Commons FileUpload package and IO libraries is required, even if we're not uploading files in our application (not having them will cause the application to fail on startup). Note that we can decide to use other file upload libraries.

Struts 2 dispatches requests with a filter (Struts 1 used a servlet). By default, Struts 2 expects to have a look at all requests. This allows Struts 2 to serve static content from the classpath. This includes JavaScript files for Dojo/Ajax support and FreeMarker templates for Struts 2's custom tags.

The default filter configuration defines the filter and its mapping.

<filter>
<filter-name>struts2</filter-name>
<filter-class>
org.apache.struts2.dispatcher.ng.filter.StrutsPrepareAndExecuteFilter

</filter-class>
</filter>
<filter-mapping>
<filter-name>struts2</filter-name>
<url-pattern>/*</url-pattern>
</filter-mapping>

Note that we map the Struts 2 filter to /*, and not to /*.action (the default Struts 2 extension). We can check whether our server and environment are correctly configured or not. If we visit any URL ending with .action, such as /sanity/foo.action, we should see an error message along the lines of: There is no Action mapped for namespace / and action name foo. This lets us know that Struts 2 at least attempted to process our request, but it couldn't.

If we don't see a similar error message, we have to troubleshoot our build and deploy environment. We can place a simple JSP file in our web context root to determine if we're able to process any request, and to determine whether we're processing JSP files correctly. (The URLs shown in the text won't include host or port information, and assume the root context.)

The specifics of troubleshooting are environment, IDE, and server-specific. These won't be covered here. The usual suspects include classpath and deployment issues.

We'll start by writing one of the simplest actions possible:

package com.packt.s2wad.ch02.sanity;
public class VerySimpleAction {
public String execute() {
return "success";
}
}

As could be seen from above, the action doesn't extend or implement anything—it just has a method named execute() that returns a String. The execute() method is the method Struts 2 will call by default (we'll see how to call others a bit later on).

<struts>
<constant name="struts.devMode" value="true"/>
<package name="default" namespace="/" extends="struts-default">
<!-- Action configurations... -->
</package>
</struts>

<action name="verysimple"
class="com.packt.s2wad.ch02.sanity.VerySimpleAction">
<result>/WEB-INF/jsps/verysimple.jsp</result>
</action>

<action name="verysimple"
class="com.packt.s2wad.ch02.sanity.VerySimpleAction">
<result name="success" type="dispatcher">
/WEB-INF/jsps/verysimple.jsp
</result>
</action>

<action name="verysimple">
<result>/WEB-INF/jsps/verysimple.jsp</result>
</action>

package com.packt.s2wad.ch02.sanity;
public class MethodSelectionAction {
public String method1() { return "success"; }
public String method2() { return "success"; }
}

<action name="method1" method="method1"
class="com.packt.s2wad.ch02.sanity.MethodSelectionAction">
<result>/WEB-INF/jsps/method1.jsp</result>
</action>
<action name="method2" method="method2"
class="com.packt.s2wad.ch02.sanity.MethodSelectionAction">
<result>/WEB-INF/jsps/method2.jsp</result>
</action>

Our client is building a recipe swapping website, which allows us to build a shopping list from a set of selected recipes. Even without any further requirements, we know we'll need at least five pages—home, recipe search, recipe list, recipe entry, and shopping list.

The first tool we'll explore for capturing application functionality are user stories. User stories are very short descriptions of functionalities (often captured on index cards) that represent a user experience.

User stories do not contain implementation or specification details. A simple example might be: "A user can search for recipes." This might even be expanded to read: "A user can search for recipes by name, ingredients, and so on." Anything significantly more detailed than that is (usually) better expressed as additional, equally short stories.

At this stage in our application requirements gathering, we have five user stories; a couple of them with some minor reminders of expected functionality:

Obviously, this isn't a complete application specification. However, it is enough to get started on coding the most basic website pages, organizing our development effort, and defining a tangible set of deliverables for the client. Even at this stage, the client might identify some missing functionalities, poor application flow, and so on.

We already know enough to define our action mappings to create skeletons of these pages, although they're a bit heavy considering our simple needs. Struts 2 provides handy wildcard configuration mechanisms making early prototyping really simple.

Wildcard action definitions are a quick way to create the skeleton of an application. The following configuration, along with the required JSP files, is enough:

<action name="*">
<result>/WEB-INF/jsps/{1}.jsp</result>
</action>

The {1} refers to the first (in this case only) wildcard in the action's name attribute. In this case, visiting /foo.action would return the /WEB-INF/jsps/foo.jsp file.

Supplying a JSP page for each story creates an outline of the application. We might use the previously shown wildcard technique and create home.jsp, recipesearch.jsp, recipelist.jsp, recipenew.jsp, and shoppinglist.jsp. Visiting /home.action would give us /WEB-INF/jsps/home.jsp. We're not actually going to do it this way: the URLs are ugly, and we suspect there must be a better way.

We have at least two different major divisions in our application—recipes and shopping lists. In the examples above we had pages such as /recipenew.action, rather than the more natural and hierarchical /recipe/new.action.

One solution would be to use multiple wildcards. Multiple wildcards allow us to map individual portions of the URL to action names, JSPs, directories, and so on. For example, see the following:

<action name="*/*">
<result>/WEB-INF/jsps/{1}/{2}.jsp</result>
</action>

Here, we use the first wildcard as a directory (like /WEB-INF/jsps/recipe). The second defines the page (JSP) to be shown, such as list.jsp, new.jsp, and so on. Now the cleaner /recipe/list.action URL would return /WEB-INF/jsps/recipe/list.jsp.

We can also use wildcards to define action methods and/or action classes. Class names, of course, must still be legal Java class names. If we're using a wildcard to create a Java class name, we'll have mixed-case URLs, and they are case-sensitive. The following definition demonstrates a possible configuration that differentiates between class names and methods within those classes:

<action name="*/*"
class="com.packt.s2wad.ch02.examples.{1}Action"
method="{2}">
<result>/WEB-INF/jsps/{1}/{2}.jsp</result>
</action>

Assume UserAction and GroupAction classes, both with list() and create() methods. Visiting /User/list.action would call the UserAction.list() method then dispatch to /WEB-INF/jsps/User/list.jsp as the result.

Just to reiterate, the case of the word User in the URL is significant. The class name created by appending the wildcard contents to the package name is the class that Struts 2 will attempt to instantiate.

Using wildcards is a flexible way to break up our application. However, for large and complex applications, it can lead to a brittle configuration, bizarre URLs, and more trouble than they're worth. Naturally, there's another way, which can be used alone or in combination with wildcards.

Packages and namespaces help group and classify various configuration elements, delineate areas of responsibility, provide package-specific resources, and so on. In our recipe application, we do not yet have much functionality. However, we can still draw a "line in the sand" between our two obvious sections, recipes and shopping, and intuit that each of these might deserve their own package.

Packages can declare a namespace, which is effectively a portion of the URL. Adding to our original default package, our first look at defining some packages looks like this:

<package name="default" namespace="/" extends="struts-default">
<action name="*">
<result>/WEB-INF/jsps/{1}.jsp</result>
</action>
</package>
<package name="recipe" namespace="/recipe" extends="struts-default">
<action name="*">
<result>/WEB-INF/jsps/recipe/{1}.jsp</result>
</action>
</package>

Visiting /recipe/list.action puts us in the recipe package, whereas visiting /home.action leads us to our default package.

We'll use<jsp:include> tags as our templating mechanism to keep things simple. Our pages will have a navigation bar at the top, and contents underneath.

We'll peek ahead at our first Struts 2 custom tag—<s:url>. This tag is used to create URLs. We could also use JSTL's<c:url> tag, but we'll discover some reasons for sticking with<s:url> in a bit.

Full documentation for the<s:url> tag (and all the other tags) is available on the Struts 2 wiki, which is also exported in the distribution. For now we'll only concern ourselves with the action and the namespace attributes. However, I always encourage people to read the documentation and consider it a necessary resource.

The action attribute specifies the Struts 2 action of the link (without the .action suffix, which is added by the tag). The namespace attribute defines the namespace the action is in. Our simple navigation page, /WEB-INF/jsps/shared/nav.jsp, contains links to each of our story pages:

<%@ taglib prefix="s" uri="/struts-tags" %>
<a href="<s:url namespace="/" action="home"/>">Home</a>
<a href="<s:url namespace="/recipe" action="list"/>">
List Recipes</a>
<a href="<s:url namespace="/recipe" action="search"/>">
Search Recipes</a>
<a href="<s:url namespace="/recipe" action="new"/>">
Create Recipe</a>
<a href="<s:url namespace="/shopping" action="list"/>">
Shopping List</a>

Why specify the namespace as a separate attribute as opposed to just including it in the action name or URL? The<s:url> tag is namespace-aware: creating links within a namespace doesn't require the namespace attribute. Actions within other namespaces require the namespace to be specified. Navigation links, which must work no matter what namespace we're in, can just use it all the time.

The slash (/) in a namespace is not optional. Without it, Struts 2 will not know that we're in a namespace and will prefix an additional namespace to the URL, thereby breaking it.

Namespaces allow us to use common sense links within a package. For example, if we were administering a large number of simple data models (users, groups, and so on), we could split them in to packages, each getting a namespace, and each with a list action.

On a page in the "users" package,<s:url action="list"/> would refer to the "users" package's list action. To link to the "groups" package list action, we specify the namespace:<s:url action="list" namespace="groups"/>.

Struts 2 configuration files can include additional configuration files with the<include> element. For example, we might configure our shopping list package in its own file and include it after our other packages were defined as seen here.

<!-- ... existing config file ... -->
</package>
<include file="com/packt/s2wad/ch02/shopping/shopping.xml"/> </struts>

The shopping.xml file is placed in our shopping package and referred to by a classpath-relative path, like any other classpath resource. We can put the configuration files wherever we want—we could just as easily keep it at the root level.

This is a simple way to break up areas of responsibility, delineate application functionality, reduce potential edit conflicts, and keep configuration as local to the implementation as possible.

To complete our wireframe application, which is just enough to show our user stories, we need to create several JSP files to match our story URLs. The / namespace holds the home action, so we create /WEB-INF/jsps/home.jsp. The /recipe namespace holds the recipe list, new recipes, and recipe search pages. Each JSP is named as we'd expect, and in /WEB-INF/jsps/recipe/. The /shopping namespace contains only the shopping list action with its JSP in /WEB-INF/jsps/shopping/list.jsp.

Each of these skeletal JSP files contains our navigation JSP and a header letting us know which page we're on. For example, our home.jsp file is mostly HTML.

<html>
<head>
<title>Home</title>
</head>
<body>
<div id="nav">
<jsp:include page="/WEB-INF/jsps/shared/nav.jsp"/>
</div>
<div id="content">
<h1>Home</h1>
<p>Home page.</p>
</div>
</body>
</html>

When we visit /home.action, we'll see the navigation links at the top and a big "Home" headline. Visiting /recipe/list.action is the same, but with a big "Recipes" headline. Not terribly exciting, but we already see the beginnings of the functionality.

We can use the Configuration Browser Plug-in to examine what Struts 2 believes our configuration is. (Struts 2 doesn't always agree with us, but is nice enough to tell us when we're wrong.) We just add the library to our classpath.

To browse our configuration, we visit /config-browser/index.action, where we'll see something similar to the following:

From here, we can examine our action configurations, result attributes, and so on. It's a handy way to compare what we think our configuration is with what Struts 2 thinks it is. Struts 2 is running the show, and its version wins even if we think it's wrong.

Hate XML? The Convention Plug-in allows us to operate completely configuration-free, and to use annotations when the defaults aren't quite what we need. The Convention Plug-in is also used by the REST Plug-in (discussed later in the book).

Using the plug-in is almost as simple as dropping its JAR file into our classpath, but not quite easy. The Convention Plug-in has its own library dependencies. Maven makes this trivial. Without Maven, it's easiest to grab the libraries from the REST Plug-in showcase application.

In this example, we won't use a Struts 2 configuration file. We'll set all of our constants in our web.xml file. For example, we'll still set struts.devMode to true.

<filter>
<filter-name>struts2</filter-name>
<filter-class>
org.apache.struts2.dispatcher.ng.filter.StrutsPrepareAndExecuteFilter
</filter-class>
<init-param>
<param-name>struts.devMode</param-name>
<param-value>true</param-value>
</init-param>
</filter>

<init-param>
<param-name>struts.convention.result.path</param-name>
<param-value>/WEB-INF/jsps</param-value>
</init-param>

package com.packt.s2wad.ch02.convention.actions;
public class SanityAction extends ActionSupport {
public String execute() {
System.out.println("***** Hello from SanityAction!");
return "success";
}
}

package com.packt.s2wad.ch02.convention.actions;
public class WhichresultAction extends ActionSupport {
private long ctm;
public String execute() {
ctm = System.currentTimeMillis();
return ((ctm & 1L) == 1L) ? "odd" : "even";
}
public long getCtm() { return ctm; }
}

<h1><s:property value="ctm"/> is odd!</h1>

@Action(value = "/tristate")
public String tristate() {
ctm = System.currentTimeMillis();
long tmp = ctm - ((ctm / 10L) * 10L);
if (tmp <= 3) return "three";
if (tmp <= 6) return "six";
return "nine";
}

@Action(value = "/tristate",
results = {
@Result(name="three",
location="/WEB-INF/jsps/tristate/tristate-three.jsp"),
@Result(name="six",
location="/WEB-INF/jsps/tristate/tristate-six.jsp"),
@Result(name="nine",
location="/WEB-INF/jsps/tristate/tristate-nine.jsp")
})

@Results({
@Result(name="nine",
location="/WEB-INF/jsps/tristate/tristate-nine.jsp")
})
public class MoreresultsAction extends ActionSupport {
@Action(value = "/tristate",
results = {
@Result(name="three",
location="/WEB-INF/jsps/tristate/tristate-three.jsp"),
@Result(name="six",
location="/WEB-INF/jsps/tristate/tristate-six.jsp")
})
public String tristate() {
// ...
}
}