001/*
002 * Copyright 2002-2017 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
025import org.springframework.core.annotation.AliasFor;
026import org.springframework.http.HttpStatus;
027
028/**
029 * Marks a method or exception class with the status {@link #code} and
030 * {@link #reason} that should be returned.
031 *
032 * <p>The status code is applied to the HTTP response when the handler
033 * method is invoked and overrides status information set by other means,
034 * like {@code ResponseEntity} or {@code "redirect:"}.
035 *
036 * <p><strong>Warning</strong>: when using this annotation on an exception
037 * class, or when setting the {@code reason} attribute of this annotation,
038 * the {@code HttpServletResponse.sendError} method will be used.
039 *
040 * <p>With {@code HttpServletResponse.sendError}, the response is considered
041 * complete and should not be written to any further. Furthermore, the Servlet
042 * container will typically write an HTML error page therefore making the
043 * use of a {@code reason} unsuitable for REST APIs. For such cases it is
044 * preferable to use a {@link org.springframework.http.ResponseEntity} as
045 * a return type and avoid the use of {@code @ResponseStatus} altogether.
046 *
047 * <p>Note that a controller class may also be annotated with
048 * {@code @ResponseStatus} and is then inherited by all {@code @RequestMapping}
049 * methods.
050 *
051 * @author Arjen Poutsma
052 * @author Sam Brannen
053 * @since 3.0
054 * @see org.springframework.web.servlet.mvc.annotation.ResponseStatusExceptionResolver
055 * @see javax.servlet.http.HttpServletResponse#sendError(int, String)
056 */
057@Target({ElementType.TYPE, ElementType.METHOD})
058@Retention(RetentionPolicy.RUNTIME)
059@Documented
060public @interface ResponseStatus {
061
062        /**
063         * Alias for {@link #code}.
064         */
065        @AliasFor("code")
066        HttpStatus value() default HttpStatus.INTERNAL_SERVER_ERROR;
067
068        /**
069         * The status <em>code</em> to use for the response.
070         * <p>Default is {@link HttpStatus#INTERNAL_SERVER_ERROR}, which should
071         * typically be changed to something more appropriate.
072         * @since 4.2
073         * @see javax.servlet.http.HttpServletResponse#setStatus(int)
074         * @see javax.servlet.http.HttpServletResponse#sendError(int)
075         */
076        @AliasFor("value")
077        HttpStatus code() default HttpStatus.INTERNAL_SERVER_ERROR;
078
079        /**
080         * The <em>reason</em> to be used for the response.
081         * @see javax.servlet.http.HttpServletResponse#sendError(int, String)
082         */
083        String reason() default "";
084
085}