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}