Adding Declarative Exception Handling to the Mini HR Application

---

Now that you've seen the benefits of using declarative exception handling and how it works, you are ready to revisit the Mini HR application and add declarative exception handling to it. Following is the list of steps involved in adding declarative exception handling to the Mini HR application:

1. Create an application exception class.

2. Update SearchAction to throw an application exception.

3. Set up an exception handler in the struts-config.xml file.

4. Create an exception-handler JSP.

5. Add an exception error message to the ApplicationResources.properties file.

6. Recompile, repackage, and run the updated application.

The following sections walk through each step of the process in detail.

Create an Application Exception Class

The first step in updating the Mini HR application to use declarative exception handling is to create an application exception class. Application exceptions are useful for distinguishing between specific error conditions. For example, an application could have a ConfigurationFileNotFoundException class and use it to indicate that a configuration file was not found, instead of simply throwing the more general java.io.FileNotFoundException. Application exceptions are also useful for distinguishing business logic-based exceptions, as is the case for the following NoResultsFoundException exception, which you will add to the Mini HR application:

package com.jamesholmes.minihr; public class NoResultsFoundException extends Exception { }

As you can see, this exception is very basic; it simply extends Exception and does not provide any other functionality. This approach uniquely identifies the exception and is useful when no additional functionality is needed beyond the base functionality provided by the Exception class.

Update SearchAction to Throw an Application Exception

Once you have created the application exception, NoResultsFoundException, you can put it to use in the SearchAction class. To use the exception, you'll add a check that determines whether or not any search results were returned from the EmployeeSearchService class. If no results are found, a NoResultsFoundException exception will be thrown. Following is the code that implements this logic:

// Throw an application exception if results were not found. if (results.size() < 1) {   throw new NoResultsFoundException(); }

When this exception is thrown, Struts will catch it and process it accordingly.

Following is the updated SearchAction class in its entirety:

package com.jamesholmes.minihr; import java.util.ArrayList; import javax.servlet.http.HttpServletRequest; import javax.servlet.http.HttpServletResponse; import org.apache.struts.action.Action; import org.apache.struts.action.ActionForm; import org.apache.struts.action.ActionForward; import org.apache.struts.action.ActionMapping; public final class SearchAction extends Action {   public ActionForward execute(ActionMapping mapping,     ActionForm form,     HttpServletRequest request,     HttpServletResponse response)     throws Exception   {     EmployeeSearchService service = new EmployeeSearchService();     ArrayList results;     SearchForm searchForm = (SearchForm) form;     // Perform employee search based on what criteria was entered.     String name = searchForm.getName();     if (name != null && name.trim().length() > 0) {       results = service.searchByName(name);     } else {       results = service.searchBySsNum(searchForm.getSsNum().trim());     }     // Throw an application exception if results were not found.     if (results.size() < 1) {       throw new NoResultsFoundException();     }     // Place search results in SearchForm for access by JSP.     searchForm.setResults(results);     // Forward control to this Action's input page.     return mapping.getInputForward();   } }

Set Up an Exception Handler in the struts-config.xml File

After you create an application exception and put it to use in an action, you must set up an exception handler for it in the struts-config.xml file. For Mini HR, the NoResultsFoundException exception will be thrown only by the SearchAction class, thus you'll define the action-specific exception handler shown next rather than a global exception handler:

<!-- Action Mappings Configuration --> <action-mappings>   <action path="/search"           type="com.jamesholmes.minihr.SearchAction"           name="searchForm"           scope="request"           validate="true"           input="/search.jsp">     <exception       type="com.jamesholmes.minihr.NoResultsFoundException"        key="error.NoResultsFoundException"       path="/exception.jsp"/>   </action> </action-mappings>

Because this exception handler is nested inside the action definition for SearchAction, it will only handle NoResultsFoundException exceptions that are thrown from that action. Alternatively, if you wanted to handle NoResultsFoundExceptions being thrown from any action, you would have to define a global exception handler, as shown next:

<global-exceptions>   <exception     type="com.jamesholmes.minihr.NoResultsFoundException"      key="error.NoResultsFoundException"     path="/exception.jsp"/> </global-exceptions>

Following is the updated struts-config.xml file in its entirety:

<?xml version="1.0"?> <!DOCTYPE struts-config PUBLIC   "-//Apache Software Foundation//DTD Struts Configuration 1.1//EN"   "http://jakarta.apache.org/struts/dtds/struts-config_1_1.dtd"> <struts-config>   <!-- Form Beans Configuration -->   <form-beans>     <form-bean name="searchForm"                type="com.jamesholmes.minihr.SearchForm"/>   </form-beans>   <!-- Global Forwards Configuration -->   <global-forwards>     <forward name="search" path="/search.jsp"/>   </global-forwards>   <!-- Action Mappings Configuration -->   <action-mappings>     <action path="/search"             type="com.jamesholmes.minihr.SearchAction"             name="searchForm"             scope="request"             validate="true"             input="/search.jsp">       <exception         type="com.jamesholmes.minihr.NoResultsFoundException"          key="error.NoResultsFoundException"         path="/exception.jsp"/>     </action>   </action-mappings>   <!-- Message Resources Configuration -->   <message-resources     parameter="com.jamesholmes.minihr.ApplicationResources"/> </struts-config>

Create an Exception-Handler JSP

When using exception handlers, you have to specify the URL to the page that will be forwarded to if the specified exception is caught by the handler. Following is the exception.jsp file specified for the NoResultsFoundException exception in the struts-config.xml file:

<%@ taglib uri="/WEB-INF/tlds/struts-html.tld" prefix="html" %> <html> <head> <title>ABC, Inc. Human Resources Portal</title> </head> <body> <font size="+1">ABC, Inc. Human Resources Portal</font><br> <hr width="100%" noshade="true"> <html:errors/> </body> </html>

As stated earlier in this chapter, when an exception is processed by Struts' built-in exception handler, it creates an ActionError object and stores it in request or session scope so that it can be accessed by the page being forwarded to. This page uses the HTML Tag Library's errors tag to output the error message.

One other point: Although this JSP is intended to be used by the exception handler for NoResultsFoundException, it is generic enough that you could use it as a general-purpose exception-handler page.

Add an Exception Error Message to the ApplicationResources.properties File

Recall from earlier in this chapter that each exception handler defined in the struts-config.xml file declares a key for an error message in Struts' resource bundle file: ApplicationResources.properties. At run time, the key is used to look up an error message to pass to the exception-handler page when the exception handler is triggered. Following is the error message that you must add to the ApplicationResources .properties file for the exception handler that was defined in the struts-config.xml file:

# Exception Error Resources error.NoResultsFoundException=<li>No Search Results Found</li>

The following code shows the updated ApplicationResources.properties file in its entirety:

# Label Resources label.search.name=Name label.search.ssNum=Social Security Number # Error Resources error.search.criteria.missing=<li>Search Criteria Missing</li> error.search.ssNum.invalid=<li>Invalid Social Security Number</li> errors.header=<font color="red"><b>Error(s)</b></font><ul> errors.footer=</ul><hr width="100%" size="1" noshade="true"> # Exception Error Resources error.NoResultsFoundException=<li>No Search Results Found</li>

Recompile, Repackage, and Run the Updated Application

Because you created a new application exception class and updated the SearchAction class, you need to recompile and repackage the Mini HR application before you run it. Assuming that you've made modifications to the original Mini HR application and it was set up in the c:\java\MiniHR directory (as described in Chapter 2), the following command line will recompile the application:

javac -classpath WEB-INF\lib\commons-beanutils.jar;                  WEB-INF\lib\commons-collections.jar;                  WEB-INF\lib\commons-lang.jar;                  WEB-INF\lib\commons-logging.jar;                  WEB-INF\lib\commons-validator.jar;                  WEB-INF\lib\digester.jar;                  WEB-INF\lib\fileupload.jar;                  WEB-INF\lib\jakarta-oro.jar;                  WEB-INF\lib\struts.jar;                  C:\java\jakarta-tomcat-4.1.27\common\lib\servlet.jar                     WEB-INF\src\com\jamesholmes\minihr\*.java                     -d WEB-INF\classes

After recompiling Mini HR, you need to repackage it using the following command line:

jar cf MiniHR.war *

This command must also be run from the directory where you have set up the Mini HR application (e.g., c:\java\MiniHR).

Similar to the way you ran Mini HR the first time, you now need to place the new MiniHR.war file that you just created into Tomcat's webapps directory and start Tomcat. As before, access the Mini HR application at http://localhost:8080/MiniHR/. Once you have the updated Mini HR application running, try entering a name or social security number that will not be found when searched for. When this happens, the SearchAction class will throw the NoResultsFoundException exception and then the exception.jsp page will be displayed, as shown in Figure 8-1.

Figure 8-1: The exception error page

---