001/*
002 * Copyright 2002-2015 the original author or authors.
003 *
004 * Licensed under the Apache License, Version 2.0 (the "License");
005 * you may not use this file except in compliance with the License.
006 * You may obtain a copy of the License at
007 *
008 *      https://www.apache.org/licenses/LICENSE-2.0
009 *
010 * Unless required by applicable law or agreed to in writing, software
011 * distributed under the License is distributed on an "AS IS" BASIS,
012 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
013 * See the License for the specific language governing permissions and
014 * limitations under the License.
015 */
016
017package org.springframework.web.bind.annotation;
018
019import java.lang.annotation.Documented;
020import java.lang.annotation.ElementType;
021import java.lang.annotation.Retention;
022import java.lang.annotation.RetentionPolicy;
023import java.lang.annotation.Target;
024
025/**
026 * Annotation for handling exceptions in specific handler classes and/or
027 * handler methods. Provides consistent style between Servlet and Portlet
028 * environments, with the semantics adapting to the concrete environment.
029 *
030 * <p>Handler methods which are annotated with this annotation are allowed to
031 * have very flexible signatures. They may have parameters of the following
032 * types, in arbitrary order:
033 * <ul>
034 * <li>An exception argument: declared as a general Exception or as a more
035 * specific exception. This also serves as a mapping hint if the annotation
036 * itself does not narrow the exception types through its {@link #value()}.
037 * <li>Request and/or response objects (Servlet API or Portlet API).
038 * You may choose any specific request/response type, e.g.
039 * {@link javax.servlet.ServletRequest} / {@link javax.servlet.http.HttpServletRequest}
040 * or {@link javax.portlet.PortletRequest} / {@link javax.portlet.ActionRequest} /
041 * {@link javax.portlet.RenderRequest}. Note that in the Portlet case,
042 * an explicitly declared action/render argument is also used for mapping
043 * specific request types onto a handler method (in case of no other
044 * information given that differentiates between action and render requests).
045 * <li>Session object (Servlet API or Portlet API): either
046 * {@link javax.servlet.http.HttpSession} or {@link javax.portlet.PortletSession}.
047 * An argument of this type will enforce the presence of a corresponding session.
048 * As a consequence, such an argument will never be {@code null}.
049 * <i>Note that session access may not be thread-safe, in particular in a
050 * Servlet environment: Consider switching the
051 * {@link org.springframework.web.servlet.mvc.method.annotation.RequestMappingHandlerAdapter#setSynchronizeOnSession
052 * "synchronizeOnSession"} flag to "true" if multiple requests are allowed to
053 * access a session concurrently.</i>
054 * <li>{@link org.springframework.web.context.request.WebRequest} or
055 * {@link org.springframework.web.context.request.NativeWebRequest}.
056 * Allows for generic request parameter access as well as request/session
057 * attribute access, without ties to the native Servlet/Portlet API.
058 * <li>{@link java.util.Locale} for the current request locale
059 * (determined by the most specific locale resolver available,
060 * i.e. the configured {@link org.springframework.web.servlet.LocaleResolver}
061 * in a Servlet environment and the portal locale in a Portlet environment).
062 * <li>{@link java.io.InputStream} / {@link java.io.Reader} for access
063 * to the request's content. This will be the raw InputStream/Reader as
064 * exposed by the Servlet/Portlet API.
065 * <li>{@link java.io.OutputStream} / {@link java.io.Writer} for generating
066 * the response's content. This will be the raw OutputStream/Writer as
067 * exposed by the Servlet/Portlet API.
068 * <li>{@link org.springframework.ui.Model} as an alternative to returning
069 * a model map from the handler method. Note that the provided model is not
070 * pre-populated with regular model attributes and therefore always empty,
071 * as a convenience for preparing the model for an exception-specific view.
072 * </ul>
073 *
074 * <p>The following return types are supported for handler methods:
075 * <ul>
076 * <li>A {@code ModelAndView} object (Servlet MVC or Portlet MVC).
077 * <li>A {@link org.springframework.ui.Model} object, with the view name implicitly
078 * determined through a {@link org.springframework.web.servlet.RequestToViewNameTranslator}.
079 * <li>A {@link java.util.Map} object for exposing a model,
080 * with the view name implicitly determined through a
081 * {@link org.springframework.web.servlet.RequestToViewNameTranslator}.
082 * <li>A {@link org.springframework.web.servlet.View} object.
083 * <li>A {@link String} value which is interpreted as view name.
084 * <li>{@link ResponseBody @ResponseBody} annotated methods (Servlet-only)
085 * to set the response content. The return value will be converted to the
086 * response stream using
087 * {@linkplain org.springframework.http.converter.HttpMessageConverter message converters}.
088 * <li>An {@link org.springframework.http.HttpEntity HttpEntity&lt;?&gt;} or
089 * {@link org.springframework.http.ResponseEntity ResponseEntity&lt;?&gt;} object
090 * (Servlet-only) to set response headers and content. The ResponseEntity body
091 * will be converted and written to the response stream using
092 * {@linkplain org.springframework.http.converter.HttpMessageConverter message converters}.
093 * <li>{@code void} if the method handles the response itself (by
094 * writing the response content directly, declaring an argument of type
095 * {@link javax.servlet.ServletResponse} / {@link javax.servlet.http.HttpServletResponse}
096 * / {@link javax.portlet.RenderResponse} for that purpose)
097 * or if the view name is supposed to be implicitly determined through a
098 * {@link org.springframework.web.servlet.RequestToViewNameTranslator}
099 * (not declaring a response argument in the handler method signature;
100 * only applicable in a Servlet environment).
101 * </ul>
102 *
103 * <p>In Servlet environments, you can combine the {@code ExceptionHandler} annotation
104 * with {@link ResponseStatus @ResponseStatus}, to define the response status
105 * for the HTTP response.
106 *
107 * <p><b>Note:</b> In Portlet environments, {@code ExceptionHandler} annotated methods
108 * will only be called during the render and resource phases - just like
109 * {@link org.springframework.web.portlet.HandlerExceptionResolver} beans would.
110 * Exceptions carried over from the action and event phases will be invoked during
111 * the render phase as well, with exception handler methods having to be present
112 * on the controller class that defines the applicable <i>render</i> method.
113 *
114 * @author Arjen Poutsma
115 * @author Juergen Hoeller
116 * @since 3.0
117 * @see org.springframework.web.context.request.WebRequest
118 * @see org.springframework.web.servlet.mvc.annotation.AnnotationMethodHandlerExceptionResolver
119 * @see org.springframework.web.portlet.mvc.annotation.AnnotationMethodHandlerExceptionResolver
120 */
121@Target(ElementType.METHOD)
122@Retention(RetentionPolicy.RUNTIME)
123@Documented
124public @interface ExceptionHandler {
125
126        /**
127         * Exceptions handled by the annotated method. If empty, will default to any
128         * exceptions listed in the method argument list.
129         */
130        Class<? extends Throwable>[] value() default {};
131
132}