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

    All Methods Instance Methods Concrete Methods
    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.

Copyright © 2000–2026 Apache Software Foundation. All rights reserved.