Our form for entering a recipe ID will contain a single text field, the recipe ID, and a submit button. We'll use some I18N functionality already introduced for the page title and the text field label. Setting the key attribute of the form field tags automagically looks up the form element label, sets the form element name, and retrieves the appropriate value from the action when necessary. We'll learn a lot more about form tags in an upcoming chapter. However, sometimes a little teaser can be entertaining.

We'll use the Convention plug-in again. Our action will have only a few responsibilities, including displaying the form, validating the form, and directing us to the action that will actually display the recipe. We don't have to write anything beyond the action definition to display the form:

package com.packt.s2wad.ch04.actions.recipes;
import com.opensymphony.xwork2.ActionSupport;
public class ViewByIdAction extends ActionSupport { }

We'll create a package.properties file containing a title and form element label entry. The important bits of our JSPs are reduced to the following:

<s:form action="view-by-id-process">
<s:textfield key="recipe.id"/>
<s:submit/>
</s:form>

Don't worry! It will all be explained later on. However, much of it is obvious. Also, as you've probably read some of the Struts 2 tag documentation, you've already run across these.

Again, following convention, this will be located in /WEB-INF/content/recipes/view-by-id.jsp.

If we view the generated source, we'll see output nearly identical to the table-based HTML that we created in the previous chapter. The logic for displaying form validation error messages is included as well. Hooray, custom tags. Notice that our<s:form> tag's action attribute points to an action we haven't defined yet.

We'll submit our form to another Convention-based action, as seen previously. We'll define this action using Convention's @Action annotation that we saw earlier, and create another method in our existing ViewByIdAction:

@Action(value = "view-by-id-process",
results = {
@Result(name = INPUT,
location =
"/WEB-INF/content/recipes/view-by-id.jsp")
})
public String process() {
return SUCCESS;
}

Notice our @Result annotation. We've configured an "input" result manually, and determined that it will use the conventionally located JSP page containing our form. We'll learn more about the validation process in a later chapter. However, we can conclude that if there are any validation errors, Struts 2 will return us to the "input" result, our form in this case.

Validating the form will add the following code to our action:

public void validate() {
if (recipe == null || recipe.getId() == null) {
addFieldError("recipe.id", "Recipe ID is required.");
}
}

If we submit the form without entering a recipe ID, we should see something similar to the following screenshot. The custom tag checks for and displays error messages on a per-field basis—all for free.

Remember when I said you'd wonder why we went through all the trouble of doing it on our own?

The next step is to configure a success result, that is, what is to be done when validation passes. To demonstrate dynamic results (using OGNL in our results configuration), we'll create a result that redirects to a view action, used to view a recipe, potentially from various other pages (like a list of recipes).

We'll add another @Result annotation to our @Action annotation's results parameter:

@Result(name = SUCCESS,
type = "redirectAction",
location = "show",
params = {"recipe.id", "%{recipe.id}"})

This @Result uses the redirectAction result, sending us to an action named show. The annotation also includes a parameter. Here, we're sending a parameter named recipe.id, and its value is ${recipe.id}.

The %{recipe.id} parameter value is an OGNL expression—the same as we'd use in a Struts 2 custom tag—wrapped in %{} characters. We can also wrap OGNL expressions in %{} when we use Struts 2 custom tags. This is compulsory in some cases.

We can use the same OGNL expressions in our Struts 2 XML configuration files as well, also wrapped in %{} characters. It's important to note that in much of the existing documentation, we'll see OGNL expressions in both XML and annotations using the ${} notation. This is still supported, but changed to include the use of %{} to better match how we use OGNL in our JSP pages.

The bottom line is that we're sending a parameter named recipe.id to the show action (which we haven't written yet), and giving it a value of our recipe's ID, which is entered using our form.

The complete action method, along with its annotations, will look like this:

@Action(value = "view-by-id-process",
results = {
@Result(name = SUCCESS,
type = "redirectAction",
location = "show",
params = {"recipe.id", "%{recipe.id}"}),
@Result(name = INPUT,
location =
"/WEB-INF/content/recipes/view-by-id.jsp")
})
public String process() {
log.debug(String.format("Enter: recipe.id=%d.",
recipe.getId()));
return SUCCESS;
}

Note that we've put a logging statement in our process() method (logging will be discussed in more detail in a later chapter). The reason for this is about to become apparent.

If we run the code at this point and submit the form with a reasonable integer value in the form field, we'll notice something rather interesting. When we submit the form, we'll see a log statement that displays the ID we entered.

No big deal, right? The Recipe class's id property is defined as a java.lang.Integer. As we all know, forms can submit only strings. However, it's working.

XWork has type conversions built right in for many common types. This means that simple conversions, such as the string-to-Integer seen above, are generally handled transparently by the framework. This saves a fair amount of time and headache during coding. You might not have even noticed. It just seems so natural, and it is. Converting form values to Java objects on our own was tedious, error-prone, and it cluttered up the code that did the real work. We'll cover more about type conversion in Chapter 6.

Something else is happening as well. Even though we have no code that creates a Recipe object, we're logging (to the console) a bit of the recipe property. The framework is creating a Recipe instance as well. Remember instantiating everything on our own? Remember pulling request parameters out on our own, converting them, and copying them into our model object? In many cases, particularly the most common ones, we don't have to do that anymore. This is very helpful in many ways. It saves code, cognitive overhead, and duplication of effort.

Our view action receives the recipe.id parameter, again into a Recipe object, instantiated and filled by the framework without any intervention from us. Now that's quite handy. For now, as we're not using a database, we're going to look up some fake, hard-coded data—but from where?

One very important principle of agile software development is to decouple our application as much as possible. This means that our individual code chunks should strive to do only one thing, and do it well.

In the past, we would load up our servlets (or framework classes) with all the code to do everything. In Struts 2 terms, we would code a database lookup into our action, handle database exceptions in our action code, marshal (say) a JDBC result set into a business model, and who knows what else.

This is a horrible idea.

However, as we progress through the book, we'll see many reasons why (and how) doing it differently is a really good idea. One of the easiest reasons to highlight is that it makes our code much longer. This increases the cognitive overhead necessary to understand how a particular section of code works, what its purpose is, and so on.

One of the easiest chunks to move out of the mainline code is database access and data marshaling. We'll return to this topic in force in later chapters, especially when we cover testability, Spring, and the mysterious-sounding Inversion of Control (IoC) (also known as Dependency Injection).

Until then, we'll write a class that pretends it's retrieving recipes from a database—but it's really just a map of hard-coded recipes. We will, however, create a parallel interface that our recipe service will implement. This allows us to write other recipe services that implement the same interface. The code in the action shouldn't have to change once we're retrieving recipes from the database.

For now, it's enough to know that there is an interface, RecipeService, which we can use to retrieve a single recipe by ID.

For now, the interface defines only what we need—the ability to find a recipe by its ID.

package com.packt.s2wad.ch04.services;
public interface RecipeService {
Recipe findById(Integer id);
}

Our implementation is called (somewhat accusingly) FakeRecipeService, and is really simple. Some of the code is elided here to make the snippet shorter. The key point to remember is that there's a map of recipes, and we can retrieve them through the findById() method.

public class FakeRecipeService implements RecipeService {
private static Map<Integer, Recipe> recipes =
new LinkedHashMap<Integer, Recipe>() {{
put(1, new Recipe(1, "Spicy Lentil Pot", ...));
put(2, new Recipe(2, "Bread and Water", ...));
...
}};
public Recipe findById(Integer id) {
return recipes.get(id);
}
}

Finally, we code our view action, which for now, simply instantiates an instance of the FakeRecipeService and uses it to look up our ID (getters and setters not shown). We'll see better ways to handle getting our recipe service later in the book.

public class ShowAction extends ActionSupport {
private Recipe recipe;
private RecipeService recipeService =
new FakeRecipeService();
public String execute() throws Exception {
recipe = recipeService.findById(recipe.getId());
return recipe != null ? SUCCESS : "notfound";
}
}

Note that we're returning notfound when we don't find a recipe. The Convention plug-in will look for /WEB-INF/content/recipes/show-notfound.jsp, and will build the JSP file name using the action name and the action's return value.

Our recipe show-success.jsp page just displays the recipe's title, description, and so on. Here's a fragment:

<h1><s:text name="recipe.show-recipe.header"/></h1>
<h2><s:text name="ingredients"/></h2>
<p>${recipe.ingredients}</p>
<p>${recipe.description}</p>
...

Note that we're using the I18N features in several more places. During our prototyping / low-fidelity phase, we probably don't care if we do that or not. However, it gives us a chance to again see how we can use action properties in our messages. The recipe.show-recipe.header message is defined in package.properties as follows:

recipe.show-recipe.header=Recipe: ${recipe.name}

This gives us a localized "Recipe" header along with our recipe's name. Of course, this works only if we don't have localized recipe names… but think low-fidelity!

The FreeMarker support in Struts 2 is built-in. Hence, configuring a FreeMarker result looks like the other results types we've seen. Only the FreeMarker library (already a dependency of Struts 2) is required—no additional libraries or plug-ins are necessary. In addition to the location and parse parameters, FreeMarker results may also specify the contentType parameter (which defaults to "text/html") to allow writing other content types. (This is surprisingly handy, for example, when producing XML, CSV, and so on.) The writeIfCompleted (false by default) may also be specified, which will write the output to the stream only if there were no errors while processing the template.

As a simple example of using a FreeMarker result, we'll create another show recipe method in our existing action. However, we will use FreeMarker instead of JSP to view the results. Our new method just returns the value of our existing execute() method. However, as we're using Convention's @Action annotation, it will search for files named after our action name. This means Convention will look for fmshow-success.ftl and fmshow-notfound.ftl. (It will actually look for the same files, but with a JSP extension. If it doesn't find those, it will look for FreeMarker files next).

@Action(value = "fmshow")
public String fmshow() throws Exception {
return execute();
}

Our FreeMarker template looks much like you'd expect it to (assuming you expected FreeMarker and not JSP). The portion that displays the recipe header and title looks very similar to that of our JSP file:

<h1><@s.text name="recipe.show-recipe.header"/></h1>
<h2>
<@s.text name="recipe.show-recipe.description.header"/>
</h2>
<div id="description">
${recipe.description}
</div>

The Struts 2 custom tags are used, but with the<@s.tagname...> syntax. We can also use FreeMarker's EL notation inside the ${} characters, just like in JSP, to access the value stack.

The FreeMarker result type may also be used to create various text-based result types very easily because of its contentType parameter. For example, by using one of the comma-separated value content types, such as "text/csv", you could create a page that could then be imported into a spreadsheet application. The default dispatcher result type for JSP pages does not have a similar contentType parameter, meaning that we must define the content type in the JSP page itself.

With its ability to use Struts 2 custom tags and its concise syntax, FreeMarker can be a compelling replacement for JSP views. There are a few potential gotchas when using FreeMarker results. They are discussed in the Struts 2 documentation wiki in the Tag Developers Guide.

Perhaps the most glaring gotcha is FreeMarker's requirement that tags be declared as "inline" or "block" tags with an inability to switch between the two. For the sake of convenience, some Struts 2 tags are defined as "inline" tags, that is, tags that accept no inner content. For example, the<s:action> tag is defined as an inline tag.

As we'll see in the next chapter, the<s:action> tag may be used with nested<s:param> tags. This use case is currently not possible using FreeMarker.

We'll work a bit backwards, starting with our result configuration. This is a sort of built-in test-driven development step. Our application will fail unless we finish writing our custom result type. We add the following to the top of our struts.xml file in our default package element:

<package name="default" namespace="/"
extends="struts-default">
<result-types>
<result-type name="markdown"
class="com.packt.s2wad.ch04.examples.MarkdownResult"/>
</result-types>
...

This tells Struts 2 that we can now use a result type markdown, and that it is implemented by the MarkdownResult class.

Our action is simple, because we're making assumptions in the interests of brevity (as usual).

package com.packt.s2wad.ch04.examples;
import com.opensymphony.xwork2.ActionSupport;
public class MarkdownAction extends ActionSupport {
private String mdid;
public String getMdid() { return mdid; }
public void setMdid(String mdid) { mdid = mdid; }
}

The XML action configuration is similarly simple:

<action name="viewmd"
class="com.packt.s2wad.ch04.examples.MarkdownAction">
<result type="markdown">
/WEB-INF/mdrecipes/${mdid}.md
</result>
</action>

The biggest assumptions are:

In our case, they're just named 1.md, 2.md, and so on. This is not, of course, production-ready code.

We see again how useful accessing action properties in our result configuration can be. Struts 2 handles what essentially is a miniature templating mechanism, saving us the trouble of building up strings ourselves.

We need only three simple steps to implement our custom result type:

In real life, we'd pay more attention to error handling.

Our Markdown result looks like this (imports, getters, and setters not shown):

package com.packt.s2wad.ch04.examples;
public class MarkdownResult extends StrutsResultSupport {
private String defaultEncoding = "ISO-8859-1";
public void doExecute(final String finalLocation,
final ActionInvocation invocation)
throws Exception {
String markdownInput =
readFromContextPath(invocation, finalLocation);
if ((markdownInput == null)
|| (markdownInput.length() == 0)) {
// FIXME Like our error handling?
}
MarkdownProcessor p = new MarkdownProcessor();
String markdown = p.markdown(markdownInput);
ActionContext actionContext =
invocation.getInvocationContext();
HttpServletResponse response =
(HttpServletResponse)
actionContext.get(StrutsStatics.HTTP_RESPONSE);
byte[] markdownBytes =
markdown.getBytes(defaultEncoding);
response.setContentLength(markdownBytes.length);
response.setContentType("text/html;charset="
+ this.defaultEncoding);
PrintWriter out = response.getWriter();
out.print(markdown);
}
private String
readFromContextPath(ActionInvocation invocation,
String finalLocation) {
ServletContext servletContext =
ServletActionContext.getServletContext();
File inFile =
new File(servletContext.getRealPath(finalLocation));
if (!inFile.exists()) {
// FIXME More awesome error handling.
return "";
}
try {
return FileUtils.readFileToString(inFile,
defaultEncoding);
} catch (IOException e) {
e.printStackTrace();
}
return "";
}
}

The entry point into StrutsResultSupport classes is the doExecute() method. It receives the current action invocation and the location of the result, which is parsed for OGNL expressions if necessary. In our case, we're passing the Markdown recipe ID from the action into the location using OGNL. Therefore, the finalLocation parameter would be 1.md if we passed an mdid value of 1.

We read the Markdown file in the readFromContextPath() method. Reading a file into a String is boring, so we've used Apache Commons IO's FileUtils class. (Commons IO is required for the default Struts 2 file uploading process; so we shouldn't feel too bad about adding another dependency.) What is (slightly) less boring is how we access things like the ServletContext from within our custom result. This highlights a simple way to get access to the servlet context on the rare occasions we need to tie ourselves to the servlet API (we also saw this in the chapter covering Struts 2 actions).

ServletActionContext.getServletContext()

I won't talk about it much because using this method ties us to the servlet specification, and we try to avoid that whenever possible. In this case, it was unavoidable as I've packaged the Markdown-based recipe files into our web application for easy deployment, but not on the classpath. Typically, they would live outside the application.

Other than that, it's just a matter of using the MarkdownJ package to transform the Markdown markup into HTML and returning it to the browser with the appropriate headers set. The rest of the doExecute() method uses a MarkdownJ processor to convert the Markdown file contents and write it directly to the response.

When we make a request to /viewmd.action?mdid=1, our result gets the location, /WEB-INF/mdrecipes/1.md, thanks to our result configuration. The file contents are run through the Markdown conversion process and get transformed into HTML which, without any styling, will present us with something resembling this: