001/* 002 * Copyright 2002-2020 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; 026 027/** 028 * Annotation for mapping web requests onto methods in request-handling classes 029 * with flexible method signatures. 030 * 031 * <p>Both Spring MVC and Spring WebFlux support this annotation through a 032 * {@code RequestMappingHandlerMapping} and {@code RequestMappingHandlerAdapter} 033 * in their respective modules and package structure. For the exact list of 034 * supported handler method arguments and return types in each, please use the 035 * reference documentation links below: 036 * <ul> 037 * <li>Spring MVC 038 * <a href="https://docs.spring.io/spring/docs/current/spring-framework-reference/web.html#mvc-ann-arguments">Method Arguments</a> 039 * and 040 * <a href="https://docs.spring.io/spring/docs/current/spring-framework-reference/web.html#mvc-ann-return-types">Return Values</a> 041 * </li> 042 * <li>Spring WebFlux 043 * <a href="https://docs.spring.io/spring/docs/current/spring-framework-reference/web-reactive.html#webflux-ann-arguments">Method Arguments</a> 044 * and 045 * <a href="https://docs.spring.io/spring/docs/current/spring-framework-reference/web-reactive.html#webflux-ann-return-types">Return Values</a> 046 * </li> 047 * </ul> 048 * 049 * <p><strong>Note:</strong> This annotation can be used both at the class and 050 * at the method level. In most cases, at the method level applications will 051 * prefer to use one of the HTTP method specific variants 052 * {@link GetMapping @GetMapping}, {@link PostMapping @PostMapping}, 053 * {@link PutMapping @PutMapping}, {@link DeleteMapping @DeleteMapping}, or 054 * {@link PatchMapping @PatchMapping}.</p> 055 * 056 * <p><b>NOTE:</b> When using controller interfaces (e.g. for AOP proxying), 057 * make sure to consistently put <i>all</i> your mapping annotations - such as 058 * {@code @RequestMapping} and {@code @SessionAttributes} - on 059 * the controller <i>interface</i> rather than on the implementation class. 060 * 061 * @author Juergen Hoeller 062 * @author Arjen Poutsma 063 * @author Sam Brannen 064 * @since 2.5 065 * @see GetMapping 066 * @see PostMapping 067 * @see PutMapping 068 * @see DeleteMapping 069 * @see PatchMapping 070 */ 071@Target({ElementType.TYPE, ElementType.METHOD}) 072@Retention(RetentionPolicy.RUNTIME) 073@Documented 074@Mapping 075public @interface RequestMapping { 076 077 /** 078 * Assign a name to this mapping. 079 * <p><b>Supported at the type level as well as at the method level!</b> 080 * When used on both levels, a combined name is derived by concatenation 081 * with "#" as separator. 082 * @see org.springframework.web.servlet.mvc.method.annotation.MvcUriComponentsBuilder 083 * @see org.springframework.web.servlet.handler.HandlerMethodMappingNamingStrategy 084 */ 085 String name() default ""; 086 087 /** 088 * The primary mapping expressed by this annotation. 089 * <p>This is an alias for {@link #path}. For example, 090 * {@code @RequestMapping("/foo")} is equivalent to 091 * {@code @RequestMapping(path="/foo")}. 092 * <p><b>Supported at the type level as well as at the method level!</b> 093 * When used at the type level, all method-level mappings inherit 094 * this primary mapping, narrowing it for a specific handler method. 095 * <p><strong>NOTE</strong>: A handler method that is not mapped to any path 096 * explicitly is effectively mapped to an empty path. 097 */ 098 @AliasFor("path") 099 String[] value() default {}; 100 101 /** 102 * The path mapping URIs (e.g. {@code "/profile"}). 103 * <p>Ant-style path patterns are also supported (e.g. {@code "/profile/**"}). 104 * At the method level, relative paths (e.g. {@code "edit"}) are supported 105 * within the primary mapping expressed at the type level. 106 * Path mapping URIs may contain placeholders (e.g. <code>"/${profile_path}"</code>). 107 * <p><b>Supported at the type level as well as at the method level!</b> 108 * When used at the type level, all method-level mappings inherit 109 * this primary mapping, narrowing it for a specific handler method. 110 * <p><strong>NOTE</strong>: A handler method that is not mapped to any path 111 * explicitly is effectively mapped to an empty path. 112 * @since 4.2 113 */ 114 @AliasFor("value") 115 String[] path() default {}; 116 117 /** 118 * The HTTP request methods to map to, narrowing the primary mapping: 119 * GET, POST, HEAD, OPTIONS, PUT, PATCH, DELETE, TRACE. 120 * <p><b>Supported at the type level as well as at the method level!</b> 121 * When used at the type level, all method-level mappings inherit this 122 * HTTP method restriction. 123 */ 124 RequestMethod[] method() default {}; 125 126 /** 127 * The parameters of the mapped request, narrowing the primary mapping. 128 * <p>Same format for any environment: a sequence of "myParam=myValue" style 129 * expressions, with a request only mapped if each such parameter is found 130 * to have the given value. Expressions can be negated by using the "!=" operator, 131 * as in "myParam!=myValue". "myParam" style expressions are also supported, 132 * with such parameters having to be present in the request (allowed to have 133 * any value). Finally, "!myParam" style expressions indicate that the 134 * specified parameter is <i>not</i> supposed to be present in the request. 135 * <p><b>Supported at the type level as well as at the method level!</b> 136 * When used at the type level, all method-level mappings inherit this 137 * parameter restriction. 138 */ 139 String[] params() default {}; 140 141 /** 142 * The headers of the mapped request, narrowing the primary mapping. 143 * <p>Same format for any environment: a sequence of "My-Header=myValue" style 144 * expressions, with a request only mapped if each such header is found 145 * to have the given value. Expressions can be negated by using the "!=" operator, 146 * as in "My-Header!=myValue". "My-Header" style expressions are also supported, 147 * with such headers having to be present in the request (allowed to have 148 * any value). Finally, "!My-Header" style expressions indicate that the 149 * specified header is <i>not</i> supposed to be present in the request. 150 * <p>Also supports media type wildcards (*), for headers such as Accept 151 * and Content-Type. For instance, 152 * <pre class="code"> 153 * @RequestMapping(value = "/something", headers = "content-type=text/*") 154 * </pre> 155 * will match requests with a Content-Type of "text/html", "text/plain", etc. 156 * <p><b>Supported at the type level as well as at the method level!</b> 157 * When used at the type level, all method-level mappings inherit this 158 * header restriction. 159 * @see org.springframework.http.MediaType 160 */ 161 String[] headers() default {}; 162 163 /** 164 * Narrows the primary mapping by media types that can be consumed by the 165 * mapped handler. Consists of one or more media types one of which must 166 * match to the request {@code Content-Type} header. Examples: 167 * <pre class="code"> 168 * consumes = "text/plain" 169 * consumes = {"text/plain", "application/*"} 170 * consumes = MediaType.TEXT_PLAIN_VALUE 171 * </pre> 172 * Expressions can be negated by using the "!" operator, as in 173 * "!text/plain", which matches all requests with a {@code Content-Type} 174 * other than "text/plain". 175 * <p><b>Supported at the type level as well as at the method level!</b> 176 * If specified at both levels, the method level consumes condition overrides 177 * the type level condition. 178 * @see org.springframework.http.MediaType 179 * @see javax.servlet.http.HttpServletRequest#getContentType() 180 */ 181 String[] consumes() default {}; 182 183 /** 184 * Narrows the primary mapping by media types that can be produced by the 185 * mapped handler. Consists of one or more media types one of which must 186 * be chosen via content negotiation against the "acceptable" media types 187 * of the request. Typically those are extracted from the {@code "Accept"} 188 * header but may be derived from query parameters, or other. Examples: 189 * <pre class="code"> 190 * produces = "text/plain" 191 * produces = {"text/plain", "application/*"} 192 * produces = MediaType.TEXT_PLAIN_VALUE 193 * produces = "text/plain;charset=UTF-8" 194 * </pre> 195 * <p>If a declared media type contains a parameter (e.g. "charset=UTF-8", 196 * "type=feed", "type=entry") and if a compatible media type from the request 197 * has that parameter too, then the parameter values must match. Otherwise 198 * if the media type from the request does not contain the parameter, it is 199 * assumed the client accepts any value. 200 * <p>Expressions can be negated by using the "!" operator, as in "!text/plain", 201 * which matches all requests with a {@code Accept} other than "text/plain". 202 * <p><b>Supported at the type level as well as at the method level!</b> 203 * If specified at both levels, the method level produces condition overrides 204 * the type level condition. 205 * @see org.springframework.http.MediaType 206 */ 207 String[] produces() default {}; 208 209}