8 min read

Handling exceptions in Struts 2

Struts 2 provides a declarative exception handling mechanism that can be configured globally (for an entire package), or for a specific action. This capability can reduce the amount of exception handling code necessary inside actions under some circumstances, most notably when underlying systems, such as our services, throw runtime exceptions (exceptions that we don’t need to wrap in a try/catch or declare that a method throws).

To sum it up, we can map exception classes to Struts 2 results.

The exception handling mechanism depends on the exception interceptor. If we modify our interceptor stack, we must keep that in mind. In general, removing the exception interceptor isn’t preferred.

Global exception mappings

Setting up a global exception handler result is as easy as adding a global exception mapping element to a Struts 2 configuration file package definition and configuring its result. For example, to catch generic runtime exceptions, we could add the following:


This means that if a java.lang.RuntimeException (or a subclass) is thrown, the framework will take us to the runtime result. The runtime result may be declared in an element, an action configuration, or both. The most specific result will be used. This implies that an action’s result configuration might take precedence over a global exception mapping.

For example, consider the global exception mapping shown in the previous code snippet. If we configure an action as follows, and a RuntimeException is thrown, we’ll see the locally defined runtime result, even if there is a global runtime result.




This can occasionally lead to confusion if a result name happens to collide with a result used for an exception. However, this can happen with global results anyway (a case where a naming convention for global results can be handy).

Action-specific exception mappings

In addition to overriding the result used for an exception mapping, we can also override a global exception mapping on a per-action basis. For example, if an action needs to use a result named runtime2 as the destination of a RuntimeException, we can configure an exception mapping specific to that action.


As with our earlier examples, the runtime2 result may be configured either as a global result or as an action-specific result.

Accessing the exception

We have many options regarding how to handle exceptions. We can show the user a generic “Something horrible has happened!” page, we can take the user back and allow them to retry the operation or refill the input form, and so on. The appropriate course of action depends on the application and, most likely, on the type of exception.

We can display exception-specific information as well. The exception interceptor pushes an exception encapsulation object onto the stack with the exception and exceptionStack properties. While the stack trace is probably not appropriate for user-level error pages, the exception can be used to help create a useful error message, provide I18N property keys for messages (or values used in messages), suggest possible remedies, and so on.

The simplest example of accessing the exception property from our JSP is to simply display the exception message. For example, if we threw a RuntimeException, we might create it as follows:

throw new
RuntimeException("Runtime thrown from ThrowingAction");

Our exception result page, then, could access the message using the usual property tag (or JSTL, if we’re taking advantage of Struts 2’s custom request processor):

The underlying action is still available on the stack—it’s the next object on the value stack. It can be accessed from the JSP as usual, as long as we’re not trying to access properties named exception or exceptionStack, which would be masked by the exception holder. (We can still access an action property named exception using OGNL’s immediate stack index notation—[1].exception.)

Architecting exceptions and exception handling

We have pretty good control over what is displayed for our application exceptions. It is customizable based on exception type, and may be overridden on a per-action basis. However, to make use of this flexibility, we require a well-thought-out exception policy in our application. There are some general principles we can follow to help make this easier.

Checked versus unchecked exceptions

Before we start, let’s recall that Java offers two main types of exceptions—checked and unchecked. Checked exceptions are exceptions we declare with a throws keyword or wrapped in a try/catch block. Unchecked exceptions are runtime exceptions or a subclass.

It isn’t always clear what type we should use when writing our code or creating our exceptions. It’s been the subject of much debate over the years, but some guidelines have become apparent.

One clear thing about checked exceptions is that they aren’t always worth the aggravation they cause, but may be useful when the programmer has a reasonable chance of recovering from the exception.

One issue with checked exceptions is that unless they’re caught and wrapped in a more abstract exception (coming up next), we’re actually circumventing some of the benefits of encapsulation. One of the benefits being circumvented is that when exceptions are declared as being thrown all the way up a call hierarchy, all of the classes involved are forced to know something about the class throwing the exception. It’s relatively rare that this exposure is justifiable.

Application-specific exceptions

One of the more useful exception techniques is to create application-specific exception classes. A compelling feature of providing our own exception classes is that we can include useful diagnostic information in the exception class itself. These classes are like any other Java class. They can contain methods, properties, and constructors.

For example, let’s assume a service that throws an exception when the user calling the service doesn’t have access rights to the service. One way to create and throw this exception would be as follows:

throw new RuntimeException("User " + user.getId()
+ " does not have access to the 'update' service.");

However, there are some issues with this approach. It’s awkward from the Struts 2’s standpoint. Because it’s a RuntimeException, we have only one option for handling the exception—mapping a RuntimeException to a result. Yes, we could map the exception type per-action, but that gets unwieldy. It also doesn’t help if we need to map two different types of RuntimeExceptions to two different results.

Another potential issue would arise if we had a process that examined exceptions and did something useful with them. For example, we might send an email with user details based on the above exception. This would amount to parsing the exception message, pulling out the user ID, and using it to get user details for inclusion in the email.

This is where we’d need to create an exception class of our own, subclassed from RuntimeException. The class would have encapsulated exception related information, and a mechanism to differentiate between the different types of exceptions.

A third benefit comes when we wrap lower-level exceptions—for example, a Spring-related exception. Rather than create a Spring dependency up the entire call chain, we’d wrap it in our own exception, abstracting the lower-level exception. This allows us to change the underlying implementation and aggregate differing exception types under one (or more) application-specific exception.

One way of creating the above scenario would be to create an exception class that takes a User object and a message as its constructor arguments:

package com.packt.s2wad.ch09.exceptions;
public class UserAccessException extends RuntimeException {
private User user;
private String msg;
public UserAccessException(User user, String msg) {
this.user = user;
this.msg = msg;
public String getMessage() {
return "User " + user.getId() + " " + msg;

We can now create an exception mapping for a UserAccessException (as well as a generic RuntimeException if we need it). In addition, the exception carries along with it the information needed to create useful messages:

throw new UserAccessException(user,
"does not have access to the 'update' service.");

“Self-documenting” of code could be made even safer, in the sense of ensuring that it’s only used in the ways in which it is intended. We could add an enum to the class to encapsulate the reasons the exception can be thrown, including the text for each reason. We’ll add the following inside  our UserAccessException:

public enum Reason {
NO_ROLE("does not have role"),
NO_ACCESS("does not have access");
private String message;
private Reason(String message) {
this.message = message;
public String getMessage() { return message; }

We’ll also modify the constructor and getMessage() method to use the new Reason enumeration.

public UserAccessException(User user, Reason reason) {
this.user = user;
this.reason = reason;
public String getMessage() {
return String.format("User %d %s.",
user.getId(), reason.getMessage());

Now, when we throw the exception, we explicitly know that we’re using the exception class correctly (at least type-wise). The string message for each of the exception reasons is encapsulated within the exception class itself.

throw new UserAccessException(user,

With Java 5’s static imports, it might make even more sense to create static helper methods in the exception class, leading to the concise, but understandable code:

throw userHasNoAccess(user);

Subscribe to the weekly Packt Hub newsletter. We'll send you the results of our AI Now Survey, featuring data and insights from across the tech landscape.

* indicates required


Please enter your comment!
Please enter your name here