org.apache.struts2.interceptor

Class ExceptionMappingInterceptor

java.lang.Object

org.apache.struts2.interceptor.AbstractInterceptor

org.apache.struts2.interceptor.ExceptionMappingInterceptor

All Implemented Interfaces:

Serializable, ConditionalInterceptor, Interceptor

public class ExceptionMappingInterceptor
extends AbstractInterceptor

This interceptor forms the core functionality of the exception handling feature. Exception handling allows you to map an exception to a result code, just as if the action returned a result code instead of throwing an unexpected exception. When an exception is encountered, it is wrapped with an ExceptionHolder and pushed on the stack, providing easy access to the exception from within your result.

Note: While you can configure exception mapping in your configuration file at any point, the configuration will not have any effect if this interceptor is not in the interceptor stack for your actions. It is recommended that you make this interceptor the first interceptor on the stack, ensuring that it has full access to catch any exception, even those caused by other interceptors.

Interceptor parameters:

• logEnabled (optional) - Should exceptions also be logged? (boolean true|false)
• logLevel (optional) - what log level should we use (trace, debug, info, warn, error, fatal)? - defaut is debug
• logCategory (optional) - If provided we would use this category (eg. com.mycompany.app). Default is to use com.opensymphony.xwork2.interceptor.ExceptionMappingInterceptor.

The parameters above enables us to log all thrown exceptions with stacktace in our own logfile, and present a friendly webpage (with no stacktrace) to the end user.

Extending the interceptor:

If you want to add custom handling for publishing the Exception, you may override publishException(ActionInvocation, ExceptionHolder). The default implementation pushes the given ExceptionHolder on value stack. A custom implementation could add additional logging etc.

Example code:

 
 <xwork>
     <package name="default" extends="xwork-default">
         <global-results>
             <result name="error" type="freemarker">error.ftl</result>
         </global-results>

         <global-exception-mappings>
             <exception-mapping exception="java.lang.Exception" result="error"/>
         </global-exception-mappings>

         <action name="test">
             <interceptor-ref name="exception"/>
             <interceptor-ref name="basicStack"/>
             <exception-mapping exception="com.acme.CustomException" result="custom_error"/>
             <result name="custom_error">custom_error.ftl</result>
             <result name="success" type="freemarker">test.ftl</result>
         </action>
     </package>
 </xwork>
 
 

This second example will also log the exceptions using our own category com.mycompany.app.unhandled at WARN level.

 
 <xwork>
   <package name="something" extends="xwork-default">
      <interceptors>
          <interceptor-stack name="exceptionmappingStack">
              <interceptor-ref name="exception">
                  <param name="logEnabled">true</param>
                  <param name="logCategory">com.mycompany.app.unhandled</param>
                  <param name="logLevel">WARN</param>
              </interceptor-ref>
              <interceptor-ref name="i18n"/>
              <interceptor-ref name="staticParams"/>
              <interceptor-ref name="params"/>
              <interceptor-ref name="validation">
                  <param name="excludeMethods">input,back,cancel,browse</param>
              </interceptor-ref>
          </interceptor-stack>
      </interceptors>

      <default-interceptor-ref name="exceptionmappingStack"/>

      <global-results>
           <result name="unhandledException">/unhandled-exception.jsp</result>
      </global-results>

      <global-exception-mappings>
           <exception-mapping exception="java.lang.Exception" result="unhandledException"/>
      </global-exception-mappings>

      <action name="exceptionDemo" class="org.apache.struts2.showcase.exceptionmapping.ExceptionMappingAction">
          <exception-mapping exception="org.apache.struts2.showcase.exceptionmapping.ExceptionMappingException"
                             result="damm"/>
          <result name="input">index.jsp</result>
          <result name="success">success.jsp</result>
          <result name="damm">damm.jsp</result>
      </action>

   </package>
 </xwork>
 
 

Author:

Matthew E. Porter (matthew dot porter at metissian dot com), Claus Ibsen

See Also:

Serialized Form

Field Summary

Fields

Modifier and Type	Field and Description
protected org.apache.logging.log4j.Logger	categoryLogger
protected String	logCategory
protected boolean	logEnabled
protected String	logLevel

Constructor Summary

Constructors

Constructor and Description
ExceptionMappingInterceptor()

Method Summary

Modifier and Type	Method and Description
protected void	doLog(org.apache.logging.log4j.Logger logger, Exception e) Performs the actual logging.
protected ExceptionMappingConfig	findMappingFromExceptions(List<ExceptionMappingConfig> exceptionMappings, Throwable t) Try to find appropriate ExceptionMappingConfig based on provided Throwable
int	getDepth(String exceptionMapping, Throwable t) Return the depth to the superclass matching.
String	getLogCategory()
String	getLogLevel()
protected void	handleLogging(Exception e) Handles the logging of the exception.
String	intercept(ActionInvocation invocation) Override to handle interception
boolean	isLogEnabled()
protected void	publishException(ActionInvocation invocation, ExceptionHolder exceptionHolder) Default implementation to handle ExceptionHolder publishing.
void	setLogCategory(String logCatgory)
void	setLogEnabled(boolean logEnabled)
void	setLogLevel(String logLevel)

Methods inherited from class org.apache.struts2.interceptor.AbstractInterceptor

destroy, init, setDisabled, shouldIntercept

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

categoryLogger

protected org.apache.logging.log4j.Logger categoryLogger

logEnabled

protected boolean logEnabled

logCategory

protected String logCategory

logLevel

protected String logLevel

Constructor Detail

ExceptionMappingInterceptor

public ExceptionMappingInterceptor()

Method Detail

isLogEnabled

public boolean isLogEnabled()

setLogEnabled

public void setLogEnabled(boolean logEnabled)

getLogCategory

public String getLogCategory()

setLogCategory

public void setLogCategory(String logCatgory)

getLogLevel

public String getLogLevel()

setLogLevel

public void setLogLevel(String logLevel)

intercept

public String intercept(ActionInvocation invocation)
                 throws Exception

Description copied from class: AbstractInterceptor

Override to handle interception

Specified by:

intercept in interface Interceptor

Specified by:

intercept in class AbstractInterceptor

Parameters:

invocation - the action invocation

Returns:

the return code, either returned from ActionInvocation.invoke(), or from the interceptor itself.

Throws:

Exception - any system-level error, as defined in Action.execute().

handleLogging

protected void handleLogging(Exception e)

Handles the logging of the exception.

Parameters:

e - the exception to log.

doLog

protected void doLog(org.apache.logging.log4j.Logger logger,
                     Exception e)

Performs the actual logging.

Parameters:

logger - the provided logger to use.

e - the exception to log.

findMappingFromExceptions

protected ExceptionMappingConfig findMappingFromExceptions(List<ExceptionMappingConfig> exceptionMappings,
                                                           Throwable t)

Try to find appropriate ExceptionMappingConfig based on provided Throwable

Parameters:

exceptionMappings - list of defined exception mappings

t - caught exception

Returns:

appropriate mapping or null

getDepth

public int getDepth(String exceptionMapping,
                    Throwable t)

Return the depth to the superclass matching. 0 means ex matches exactly. Returns -1 if there's no match. Otherwise, returns depth. Lowest depth wins.

Parameters:

exceptionMapping - the mapping classname

t - the cause

Returns:

the depth, if not found -1 is returned.

publishException

protected void publishException(ActionInvocation invocation,
                                ExceptionHolder exceptionHolder)

Default implementation to handle ExceptionHolder publishing. Pushes given ExceptionHolder on the stack. Subclasses may override this to customize publishing.

Parameters:

invocation - The invocation to publish Exception for.

exceptionHolder - The exceptionHolder wrapping the Exception to publish.