Chapter 10: Managing Errors

---

In this chapter, we look at some of the methods available when you're managing errors in a Struts application. We begin by discussing the various error classes provided by the Struts Framework. We also examine how errors are managed in both the Controller and Views of a Struts application by adding error handling to our wroxapp stock quote application.

The goal of this chapter is to show you how errors can be managed in a Struts application. At the end of this chapter, you will know how and where the Struts error-management component can be leveraged.

Struts Error Management

The Struts Framework is packaged with two main classes that are intended for error management. The first of these classes is the ActionError class, which represents an encapsulation of a single error message. The second error management class is the ActionErrors class, which acts as a container for a collection of ActionError instances. These two classes are the focus of this chapter.

ActionError

The first of our error-management classes, the org.apache.struts.action.ActionError class, extends the org.apache.struts.action.ActionMessage class and represents a single error message. This message—most often created in either an Action or an ActionForm instance—is composed of a message key, which is used to look up a resource from the application resource bundle, and up to n-number of text replacement values, which can be used to dynamically modify an error message.

The ActionError class can be instantiated using one of six different constructors. The method signatures for each of these constructors are shown here:

 public ActionError(java.lang.String key) public ActionError(java.lang.String key,                    java.lang.Object value0) public ActionError(java.lang.String key,                    java.lang.Object value0,                    java.lang.Object value1) public ActionError(java.lang.String key,                    java.lang.Object value0,                    java.lang.Object valuel,                    java.lang.Object value2) public ActionError(java.lang.String key,                    java.lang.Object value0,                    java.lang.Object value1,                    java.lang.Object value2,                    java.lang.Object value3) public ActionError(java.lang.String key,                    java.lang.Object[] values) 

The key attribute of the ActionError class is used to look up a resource from the application resource bundle, which we describe in Chapter 9, "Internationalizing Your Struts Applications." This allows you to provide error messages that are i18n enabled. We see examples of this when we add error management to our wroxapp application.

The value0..3 attributes allow you to pass up to four replacement objects that can be used to dynamically modify messages. This allows you to parameterize an internationalized message.

Here's an example of constructing an ActionError:

 ActionError error = new ActionError("errors.lookup.unknown",                                     symbol); 

This ActionError instance looks up the resource bundle string with the key errors.lookup.unknown and substitutes the value of the symbol object as the retrieved resource's first parameter. If we were to assume our resource bundle contained the entry

 errors.lookup.unknown=Unknown Symbol : {0} 

and the symbol object was a String containing the value BOBCO, then the resulting message would look something like this:

 Unknown Symbol : BOBCO 

The placeholders used by the ActionError class are formatted according the standard JDK's java.text.MessageFormat, using the replacement symbols of {0}, {1}, {2}, and {3}.

The final ActionError constructor allows you to pass an Object array of replace values—this allows you to substitute any number of string replacements in your error message.

ActionErrors

The second of our error-management classes, the org.apache.struts.action.ActionErrors class, extends the org.apache.struts.action.ActionMessages class and represents a collection of ActionError classes. The ActionErrors class is composed of two constructors and a single method that allows you to add an ActionError object to the current collection of ActionErrors.

In addition to the add() method, the ActionErrors class inherits eight extremely useful methods that are used to query and manipulate the contained ActionError instances. Table 10.1 describes the methods of the ActionErrors and ActionMessages classes.

Table 10.1: The Methods of the ActionErrors Class

Method	Description
ActionErrors.add()	Adds an ActionError instance, associated with a property, to the internal ActionErrors HashMap. Note that the internal HashMap contains an ArrayList of ActionErrors. This allows you to add multiple ActionError objects bound to the same property.
ActionMessages.clear()	Removes all of the ActionError instances currently stored in the ActionErrors object.
ActionMessages.isEmpty()	Returns true, if no ActionError objects are currently stored in the ActionErrors collection; otherwise, returns false.
ActionMessages.get()	Returns a Java Iterator referencing all of the current ActionError objects, without regard to the property they are bound to.
ActionMessages.get (java.lang.String)	Returns a Java Iterator referencing all of the current ActionError objects bound to the property represented by the String value passed to this method.
ActionMessages.properties()	Returns a Java Iterator referencing all of the current properties bound to ActionError objects.
ActionMessages.size()	Returns the number of ActionError objects, without regard to the property they are bound to.
ActionMessages.size (java.lang.String)	Returns the number of ActionError objects bound to the property represented by the String value passed to this method.

The get() methods listed in Table 10.1 actually return ActionMessage instances; therefore, you will need to downcast these objects to an ActionError object to get your original error objects back out.

The add() method is the method most often used when managing collections of errors. The following code snippet contains two add() methods and shows how ActionError objects can be added to the ActionErrors collection:

 ActionErrors errors = new ActionErrors(); errors.add("propertyname",            new ActionError("key"); errors.add(ActionErrors.GLOBAL_ERROR,            new ActionError("key"); 

As you can see, the only difference between these two add()s is the first parameter. This parameter represents the property to which the ActionError being added should be bound.

The first add() example uses a String as the property value. This tells Struts that this error is bound to an input property from the HTML form that submitted this request. This method is most often used to report errors that have occurred when validating the form in the ActionForm.validate() method.

The second add() example uses a predefined static that tells the framework that this error message is not associated with a single form property but is instead related to the Action or application.

---