Annotation Interface ExceptionHandler


@Target(METHOD) @Retention(RUNTIME) @Documented @Reflective(org.springframework.web.bind.annotation.ExceptionHandlerReflectiveProcessor.class) public @interface ExceptionHandler
Annotation for handling exceptions in specific handler classes and/or handler methods.

Handler methods which are annotated with this annotation are allowed to have very flexible signatures. They may have parameters of the following types, in arbitrary order:

  • An exception argument: declared as a general Exception or as a more specific exception. This also serves as a mapping hint if the annotation itself does not narrow the exception types through its value(). You may refer to a top-level exception being propagated or to a nested cause within a wrapper exception. As of 5.3, any cause level is being exposed, whereas previously only an immediate cause was considered.
  • Request and/or response objects (typically from the Servlet API). You may choose any specific request/response type, e.g. ServletRequest / HttpServletRequest.
  • Session object: typically HttpSession. An argument of this type will enforce the presence of a corresponding session. As a consequence, such an argument will never be null. Note that session access may not be thread-safe, in particular in a Servlet environment: Consider switching the "synchronizeOnSession" flag to "true" if multiple requests are allowed to access a session concurrently.
  • WebRequest or NativeWebRequest. Allows for generic request parameter access as well as request/session attribute access, without ties to the native Servlet API.
  • Locale for the current request locale (determined by the most specific locale resolver available, i.e. the configured LocaleResolver in a Servlet environment).
  • InputStream / Reader for access to the request's content. This will be the raw InputStream/Reader as exposed by the Servlet API.
  • OutputStream / Writer for generating the response's content. This will be the raw OutputStream/Writer as exposed by the Servlet API.
  • Model as an alternative to returning a model map from the handler method. Note that the provided model is not pre-populated with regular model attributes and therefore always empty, as a convenience for preparing the model for an exception-specific view.

The following return types are supported for handler methods:

You may combine the ExceptionHandler annotation with @ResponseStatus for a specific HTTP error status.

Since:
3.0
Author:
Arjen Poutsma, Juergen Hoeller, Brian Clozel
See Also:
  • Optional Element Summary

    Optional Elements
    Modifier and Type
    Optional Element
    Description
    Class<? extends Throwable>[]
    Exceptions handled by the annotated method.
    Media Types that can be produced by the annotated method.
    Class<? extends Throwable>[]
    Exceptions handled by the annotated method.
  • Element Details

    • value

      @AliasFor("exception") Class<? extends Throwable>[] value
      Exceptions handled by the annotated method.

      This is an alias for exception().

      Default:
      {}
    • exception

      @AliasFor("value") Class<? extends Throwable>[] exception
      Exceptions handled by the annotated method. If empty, will default to any exceptions listed in the method argument list.
      Since:
      6.2
      Default:
      {}
    • produces

      String[] produces
      Media Types that can be produced by the annotated method.
      Since:
      6.2
      Default:
      {}