001// *************************************************************************************************************************** 002// * Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file * 003// * distributed with this work for additional information regarding copyright ownership. The ASF licenses this file * 004// * to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance * 005// * with the License. You may obtain a copy of the License at * 006// * * 007// * http://www.apache.org/licenses/LICENSE-2.0 * 008// * * 009// * Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an * 010// * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the * 011// * specific language governing permissions and limitations under the License. * 012// *************************************************************************************************************************** 013package org.apache.juneau.rest.annotation; 014 015import static java.lang.annotation.ElementType.*; 016import static java.lang.annotation.RetentionPolicy.*; 017 018import java.lang.annotation.*; 019 020import org.apache.juneau.*; 021import org.apache.juneau.rest.*; 022import org.apache.juneau.http.annotation.*; 023import org.apache.juneau.remote.*; 024 025/** 026 * Identifies a REST Java method on a {@link RestServlet} implementation class. 027 * 028 * <h5 class='section'>See Also:</h5> 029 * <ul> 030 * <li class='link'>{@doc juneau-rest-server.RestMethod} 031 * </ul> 032 */ 033@Documented 034@Target(METHOD) 035@Retention(RUNTIME) 036@Inherited 037public @interface RestMethod { 038 039 /** 040 * Sets the bean filters for the serializers and parsers defined on this method. 041 * 042 * <p> 043 * If no value is specified, the bean filters are inherited from the class. 044 * <br>Otherwise, this value overrides the bean filters defined on the class. 045 * 046 * <p> 047 * Use {@link Inherit} to inherit bean filters defined on the class. 048 * 049 * <p> 050 * Use {@link None} to suppress inheriting bean filters defined on the class. 051 * 052 * <h5 class='section'>See Also:</h5> 053 * <ul> 054 * <li class='jf'>{@link BeanContext#BEAN_beanFilters} 055 * </ul> 056 */ 057 Class<?>[] beanFilters() default {}; 058 059 /** 060 * Shortcut for specifying the {@link BeanContext#BEAN_includeProperties} property on all serializers. 061 * 062 * <p> 063 * The typical use case is when you're rendering summary and details views of the same bean in a resource and 064 * you want to expose or hide specific properties depending on the level of detail you want. 065 * 066 * <p> 067 * In the example below, our 'summary' view is a list of beans where we only want to show the ID property, 068 * and our detail view is a single bean where we want to expose different fields: 069 * <p class='bcode w800'> 070 * <jc>// Our bean</jc> 071 * <jk>public class</jk> MyBean { 072 * 073 * <jc>// Summary properties</jc> 074 * <ja>@Html</ja>(link=<js>"servlet:/mybeans/{id}"</js>) 075 * <jk>public</jk> String <jf>id</jf>; 076 * 077 * <jc>// Detail properties</jc> 078 * <jk>public</jk> String <jf>a</jf>, <jf>b</jf>; 079 * } 080 * 081 * <jc>// Only render "id" property.</jc> 082 * <ja>@RestMethod</ja>(name=<jsf>GET</jsf>, path=<js>"/mybeans"</js>, bpi=<js>"MyBean: id"</js>) 083 * <jk>public</jk> List<MyBean> getBeanSummary() {...} 084 * 085 * <jc>// Only render "a" and "b" properties.</jc> 086 * <ja>@RestMethod</ja>(name=<jsf>GET</jsf>, path=<js>"/mybeans/{id}"</js>, bpi=<js>"MyBean: a,b"</js>) 087 * <jk>public</jk> MyBean getBeanDetails(<ja>@Path</ja> String id) {...} 088 * </p> 089 * 090 * <h5 class='section'>Notes:</h5> 091 * <ul class='spaced-list'> 092 * <li> 093 * The format of each value is: <js>"Key: comma-delimited-tokens"</js>. 094 * <li> 095 * Keys can be fully-qualified or short class names or <js>"*"</js> to represent all classes. 096 * <li> 097 * Values are comma-delimited lists of bean property names. 098 * <li> 099 * Properties apply to specified class and all subclasses. 100 * <li> 101 * Semicolons can be used as an additional separator for multiple values: 102 * <p class='bcode w800'> 103 * <jc>// Equivalent</jc> 104 * bpi={<js>"Bean1: foo"</js>,<js>"Bean2: bar,baz"</js>} 105 * bpi=<js>"Bean1: foo; Bean2: bar,baz"</js> 106 * </p> 107 * </ul> 108 * 109 * <h5 class='section'>See Also:</h5> 110 * <ul> 111 * <li class='jf'>{@link BeanContext#BEAN_includeProperties} 112 * </ul> 113 */ 114 String[] bpi() default {}; 115 116 /** 117 * Shortcut for specifying the {@link BeanContext#BEAN_excludeProperties} property on all serializers. 118 * 119 * <p> 120 * Same as {@link #bpi()} except you specify a list of bean property names that you want to exclude from 121 * serialization. 122 * 123 * <p> 124 * In the example below, our 'summary' view is a list of beans where we want to exclude some properties: 125 * <p class='bcode w800'> 126 * <jc>// Our bean</jc> 127 * <jk>public class</jk> MyBean { 128 * 129 * <jc>// Summary properties</jc> 130 * <ja>@Html</ja>(link=<js>"servlet:/mybeans/{id}"</js>) 131 * <jk>public</jk> String <jf>id</jf>; 132 * 133 * <jc>// Detail properties</jc> 134 * <jk>public</jk> String <jf>a</jf>, <jf>b</jf>; 135 * } 136 * 137 * <jc>// Don't show "a" and "b" properties.</jc> 138 * <ja>@RestMethod</ja>(name=<jsf>GET</jsf>, path=<js>"/mybeans"</js>, bpx=<js>"MyBean: a,b"</js>) 139 * <jk>public</jk> List<MyBean> getBeanSummary() {...} 140 * 141 * <jc>// Render all properties.</jc> 142 * <ja>@RestMethod</ja>(name=<jsf>GET</jsf>, path=<js>"/mybeans/{id}"</js>) 143 * <jk>public</jk> MyBean getBeanDetails(<ja>@Path</ja> String id) {...} 144 * </p> 145 * 146 * <h5 class='section'>Notes:</h5> 147 * <ul class='spaced-list'> 148 * <li> 149 * The format of each value is: <js>"Key: comma-delimited-tokens"</js>. 150 * <li> 151 * Keys can be fully-qualified or short class names or <js>"*"</js> to represent all classes. 152 * <li> 153 * Values are comma-delimited lists of bean property names. 154 * <li> 155 * Properties apply to specified class and all subclasses. 156 * <li> 157 * Semicolons can be used as an additional separator for multiple values: 158 * <p class='bcode w800'> 159 * <jc>// Equivalent</jc> 160 * bpx={<js>"Bean1: foo"</js>,<js>"Bean2: bar,baz"</js>} 161 * bpx=<js>"Bean1: foo; Bean2: bar,baz"</js> 162 * </p> 163 * </ul> 164 * 165 * <h5 class='section'>See Also:</h5> 166 * <ul> 167 * <li class='jf'>{@link BeanContext#BEAN_excludeProperties} 168 * </ul> 169 */ 170 String[] bpx() default {}; 171 172 /** 173 * Specifies whether this method can be called based on the client version. 174 * 175 * <p> 176 * The client version is identified via the HTTP request header identified by 177 * {@link RestResource#clientVersionHeader() @RestResource(clientVersionHeader)} which by default is <js>"X-Client-Version"</js>. 178 * 179 * <p> 180 * This is a specialized kind of {@link RestMatcher} that allows you to invoke different Java methods for the same 181 * method/path based on the client version. 182 * 183 * <p> 184 * The format of the client version range is similar to that of OSGi versions. 185 * 186 * <p> 187 * In the following example, the Java methods are mapped to the same HTTP method and URL <js>"/foobar"</js>. 188 * <p class='bcode w800'> 189 * <jc>// Call this method if X-Client-Version is at least 2.0. 190 * // Note that this also matches 2.0.1.</jc> 191 * <ja>@RestMethod</ja>(name=<jsf>GET</jsf>, path=<js>"/foobar"</js>, clientVersion=<js>"2.0"</js>) 192 * <jk>public</jk> Object method1() {...} 193 * 194 * <jc>// Call this method if X-Client-Version is at least 1.1, but less than 2.0.</jc> 195 * <ja>@RestMethod</ja>(name=<jsf>GET</jsf>, path=<js>"/foobar"</js>, clientVersion=<js>"[1.1,2.0)"</js>) 196 * <jk>public</jk> Object method2() {...} 197 * 198 * <jc>// Call this method if X-Client-Version is less than 1.1.</jc> 199 * <ja>@RestMethod</ja>(name=<jsf>GET</jsf>, path=<js>"/foobar"</js>, clientVersion=<js>"[0,1.1)"</js>) 200 * <jk>public</jk> Object method3() {...} 201 * </p> 202 * 203 * <p> 204 * It's common to combine the client version with transforms that will convert new POJOs into older POJOs for 205 * backwards compatibility. 206 * <p class='bcode w800'> 207 * <jc>// Call this method if X-Client-Version is at least 2.0.</jc> 208 * <ja>@RestMethod</ja>(name=<jsf>GET</jsf>, path=<js>"/foobar"</js>, clientVersion=<js>"2.0"</js>) 209 * <jk>public</jk> NewPojo newMethod() {...} 210 * 211 * <jc>// Call this method if X-Client-Version is at least 1.1, but less than 2.0.</jc> 212 * <ja>@RestMethod</ja>(name=<jsf>GET</jsf>, path=<js>"/foobar"</js>, clientVersion=<js>"[1.1,2.0)"</js>, transforms={NewToOldPojoSwap.<jk>class</jk>}) 213 * <jk>public</jk> NewPojo oldMethod() { 214 * <jk>return</jk> newMethod(); 215 * } 216 * 217 * <p> 218 * Note that in the previous example, we're returning the exact same POJO, but using a transform to convert it into 219 * an older form. 220 * The old method could also just return back a completely different object. 221 * The range can be any of the following: 222 * <ul> 223 * <li><js>"[0,1.0)"</js> = Less than 1.0. 1.0 and 1.0.0 does not match. 224 * <li><js>"[0,1.0]"</js> = Less than or equal to 1.0. Note that 1.0.1 will match. 225 * <li><js>"1.0"</js> = At least 1.0. 1.0 and 2.0 will match. 226 * </ul> 227 * 228 * <h5 class='section'>See Also:</h5> 229 * <ul> 230 * <li class='jf'>{@link RestContext#REST_clientVersionHeader} 231 * </ul> 232 */ 233 String clientVersion() default ""; 234 235 /** 236 * Class-level response converters. 237 * 238 * <p> 239 * Associates one or more {@link RestConverter converters} with this method. 240 * 241 * <h5 class='section'>See Also:</h5> 242 * <ul> 243 * <li class='jf'>{@link RestContext#REST_converters} 244 * </ul> 245 */ 246 Class<? extends RestConverter>[] converters() default {}; 247 248 /** 249 * Default <code>Accept</code> header. 250 * 251 * <p> 252 * The default value for the <code>Accept</code> header if not specified on a request. 253 * 254 * <p> 255 * This is a shortcut for using {@link #defaultRequestHeaders()} for just this specific header. 256 */ 257 String defaultAccept() default ""; 258 259 /** 260 * Default character encoding. 261 * 262 * <p> 263 * The default character encoding for the request and response if not specified on the request. 264 * 265 * <h5 class='section'>Notes:</h5> 266 * <ul class='spaced-list'> 267 * <li> 268 * Supports {@doc DefaultRestSvlVariables} 269 * (e.g. <js>"$S{mySystemProperty}"</js>). 270 * </ul> 271 * 272 * <h5 class='section'>See Also:</h5> 273 * <ul> 274 * <li class='jf'>{@link RestContext#REST_defaultCharset} 275 * </ul> 276 */ 277 String defaultCharset() default ""; 278 279 /** 280 * Default <code>Content-Type</code> header. 281 * 282 * <p> 283 * The default value for the <code>Content-Type</code> header if not specified on a request. 284 * 285 * <p> 286 * This is a shortcut for using {@link #defaultRequestHeaders()} for just this specific header. 287 */ 288 String defaultContentType() default ""; 289 290 /** 291 * Specifies default values for form-data parameters. 292 * 293 * <p> 294 * Strings are of the format <js>"name=value"</js>. 295 * 296 * <p> 297 * Affects values returned by {@link RestRequest#getFormData(String)} when the parameter is not present on the 298 * request. 299 * 300 * <h5 class='section'>Example:</h5> 301 * <p class='bcode w800'> 302 * <ja>@RestMethod</ja>(name=<jsf>POST</jsf>, path=<js>"/*"</js>, defaultFormData={<js>"foo=bar"</js>}) 303 * <jk>public</jk> String doGet(<ja>@FormData</ja>(<js>"foo"</js>) String foo) {...} 304 * </p> 305 * 306 * <h5 class='section'>Notes:</h5> 307 * <ul class='spaced-list'> 308 * <li> 309 * You can use either <js>':'</js> or <js>'='</js> as the key/value delimiter. 310 * <li> 311 * Key and value is trimmed of whitespace. 312 * <li> 313 * Supports {@doc DefaultRestSvlVariables} 314 * (e.g. <js>"$S{mySystemProperty}"</js>). 315 * </ul> 316 */ 317 String[] defaultFormData() default {}; 318 319 /** 320 * Specifies default values for query parameters. 321 * 322 * <p> 323 * Strings are of the format <js>"name=value"</js>. 324 * 325 * <p> 326 * Affects values returned by {@link RestRequest#getQuery(String)} when the parameter is not present on the request. 327 * 328 * <h5 class='section'>Example:</h5> 329 * <p class='bcode w800'> 330 * <ja>@RestMethod</ja>(name=<jsf>GET</jsf>, path=<js>"/*"</js>, defaultQuery={<js>"foo=bar"</js>}) 331 * <jk>public</jk> String doGet(<ja>@Query</ja>(<js>"foo"</js>) String foo) {...} 332 * </p> 333 * 334 * <h5 class='section'>Notes:</h5> 335 * <ul class='spaced-list'> 336 * <li> 337 * You can use either <js>':'</js> or <js>'='</js> as the key/value delimiter. 338 * <li> 339 * Key and value is trimmed of whitespace. 340 * <li> 341 * Supports {@doc DefaultRestSvlVariables} 342 * (e.g. <js>"$S{mySystemProperty}"</js>). 343 * </ul> 344 */ 345 String[] defaultQuery() default {}; 346 347 /** 348 * Default request headers. 349 * 350 * <p> 351 * Specifies default values for request headers if they're not passed in through the request. 352 * 353 * <h5 class='section'>Example:</h5> 354 * <p class='bcode w800'> 355 * <jc>// Assume "text/json" Accept value when Accept not specified</jc> 356 * <ja>@RestMethod</ja>(name=<jsf>GET</jsf>, path=<js>"/*"</js>, defaultRequestHeaders={<js>"Accept: text/json"</js>}) 357 * <jk>public</jk> String doGet() {...} 358 * </p> 359 * 360 * <h5 class='section'>Notes:</h5> 361 * <ul class='spaced-list'> 362 * <li> 363 * Supports {@doc DefaultRestSvlVariables} 364 * (e.g. <js>"$S{mySystemProperty}"</js>). 365 * </ul> 366 * 367 * <h5 class='section'>See Also:</h5> 368 * <ul> 369 * <li class='jf'>{@link RestContext#REST_defaultRequestHeaders} 370 * </ul> 371 */ 372 String[] defaultRequestHeaders() default {}; 373 374 /** 375 * Optional description for the exposed API. 376 * 377 * <p> 378 * This description is used in the following locations: 379 * <ul class='spaced-list'> 380 * <li> 381 * The value returned by {@link RestRequest#getMethodDescription()}. 382 * <li> 383 * The <js>"$R{methodDescription}"</js> variable. 384 * <li> 385 * The description of the method in the Swagger page. 386 * </ul> 387 * 388 * <h5 class='section'>Notes:</h5> 389 * <ul class='spaced-list'> 390 * <li> 391 * Corresponds to the swagger field <code>/paths/{path}/{method}/description</code>. 392 * <li> 393 * Supports {@doc DefaultRestSvlVariables} 394 * (e.g. <js>"$L{my.localized.variable}"</js>). 395 * </ul> 396 * 397 * <h5 class='section'>See Also:</h5> 398 * <ul> 399 * <li class='jm'>{@link RestInfoProvider#getDescription(RestRequest)} 400 * </ul> 401 */ 402 String[] description() default {}; 403 404 /** 405 * Compression encoders. 406 * 407 * <p> 408 * Use this annotation when the list of encoders assigned to a method differs from the list of encoders assigned at 409 * the servlet level. 410 * 411 * <p> 412 * These can be used to enable various kinds of compression (e.g. <js>"gzip"</js>) on requests and responses. 413 * 414 * <h5 class='section'>Notes:</h5> 415 * <ul class='spaced-list'> 416 * <li> 417 * Use <code>inherit={<js>"ENCODERS"</js>}</code> to inherit encoders from the resource class. 418 * </ul> 419 * 420 * <h5 class='section'>See Also:</h5> 421 * <ul> 422 * <li class='jf'>{@link RestContext#REST_encoders} 423 * </ul> 424 */ 425 Class<?>[] encoders() default {}; 426 427 /** 428 * Shortcut for setting {@link #properties()} of simple boolean types. 429 * 430 * <p> 431 * Setting a flag is equivalent to setting the same property to <js>"true"</js>. 432 */ 433 String[] flags() default {}; 434 435 /** 436 * Method-level guards. 437 * 438 * <p> 439 * Associates one or more {@link RestGuard RestGuards} with this method. 440 * 441 * <h5 class='section'>See Also:</h5> 442 * <ul> 443 * <li class='jf'>{@link RestContext#REST_guards} 444 * </ul> 445 */ 446 Class<? extends RestGuard>[] guards() default {}; 447 448 /** 449 * Provides HTML-doc-specific metadata on this method. 450 * 451 * <p> 452 * Information provided here overrides information provided in the servlet-level annotation. 453 * 454 * <h5 class='section'>See Also:</h5> 455 * <ul> 456 * <li class='link'>{@doc juneau-rest-server.HtmlDocAnnotation} 457 * </ul> 458 */ 459 HtmlDoc htmldoc() default @HtmlDoc; 460 461 /** 462 * Method matchers. 463 * 464 * <p> 465 * Associates one more more {@link RestMatcher RestMatchers} with this method. 466 * 467 * <p> 468 * Matchers are used to allow multiple Java methods to handle requests assigned to the same URL path pattern, but 469 * differing based on some request attribute, such as a specific header value. 470 * 471 * <h5 class='section'>See Also:</h5> 472 * <ul> 473 * <li class='jac'>{@link RestMatcher} 474 * </ul> 475 */ 476 Class<? extends RestMatcher>[] matchers() default {}; 477 478 /** 479 * The maximum allowed input size (in bytes) on HTTP requests. 480 * 481 * <p> 482 * Useful for alleviating DoS attacks by throwing an exception when too much input is received instead of resulting 483 * in out-of-memory errors which could affect system stability. 484 * 485 * <h5 class='section'>Example:</h5> 486 * <p class='bcode w800'> 487 * <ja>@RestMethod</ja>( 488 * maxInput=<js>"100M"</js> 489 * ) 490 * </p> 491 * 492 * <h5 class='section'>Notes:</h5> 493 * <ul class='spaced-list'> 494 * <li> 495 * Supports {@doc DefaultRestSvlVariables} 496 * (e.g. <js>"$S{mySystemProperty}"</js>). 497 * </ul> 498 * 499 * <h5 class='section'>See Also:</h5> 500 * <ul> 501 * <li class='jf'>{@link RestContext#REST_maxInput} 502 * </ul> 503 */ 504 String maxInput() default ""; 505 506 /** 507 * REST method name. 508 * 509 * <p> 510 * Typically <js>"GET"</js>, <js>"PUT"</js>, <js>"POST"</js>, <js>"DELETE"</js>, or <js>"OPTIONS"</js>. 511 * 512 * <p> 513 * Method names are case-insensitive (always folded to upper-case). 514 * 515 * <p> 516 * Note that you can use {@link org.apache.juneau.http.HttpMethodName} for constant values. 517 * 518 * <p> 519 * Besides the standard HTTP method names, the following can also be specified: 520 * <ul class='spaced-list'> 521 * <li> 522 * <js>"*"</js> 523 * - Denotes any method. 524 * <br>Use this if you want to capture any HTTP methods in a single Java method. 525 * <br>The {@link Method @Method} annotation and/or {@link RestRequest#getMethod()} method can be used to 526 * distinguish the actual HTTP method name. 527 * <li> 528 * <js>""</js> 529 * - Auto-detect. 530 * <br>The method name is determined based on the Java method name. 531 * <br>For example, if the method is <code>doPost(...)</code>, then the method name is automatically detected 532 * as <js>"POST"</js>. 533 * <br>Otherwise, defaults to <js>"GET"</js>. 534 * <li> 535 * <js>"PROXY"</js> 536 * - Remote-proxy interface. 537 * <br>This denotes a Java method that returns an object (usually an interface, often annotated with the 538 * {@link RemoteInterface @RemoteInterface} annotation) to be used as a remote proxy using 539 * <code>RestClient.getRemoteInterface(Class<T> interfaceClass, String url)</code>. 540 * <br>This allows you to construct client-side interface proxies using REST as a transport medium. 541 * <br>Conceptually, this is simply a fancy <code>POST</code> against the url <js>"/{path}/{javaMethodName}"</js> 542 * where the arguments are marshalled from the client to the server as an HTTP body containing an array of 543 * objects, passed to the method as arguments, and then the resulting object is marshalled back to the client. 544 * <li> 545 * Anything else 546 * - Overloaded non-HTTP-standard names that are passed in through a <code>&method=methodName</code> URL 547 * parameter. 548 * </ul> 549 */ 550 String name() default ""; 551 552 /** 553 * Parsers. 554 * 555 * <p> 556 * If no value is specified, the parsers are inherited from the class. 557 * <br>Otherwise, this value overrides the parsers defined on the class. 558 * 559 * <p> 560 * Use {@link Inherit} to inherit parsers defined on the class. 561 * 562 * <p> 563 * Use {@link None} to suppress inheriting parsers defined on the class. 564 * 565 * <p class='bcode w800'> 566 * <jk>public class</jk> MyResource <jk>extends</jk> RestServlet { 567 * 568 * <ja>@RestMethod</ja>( 569 * name=<jsf>PUT</jsf>, 570 * path=<js>"/foo"</js>, 571 * parsers=MySpecialParser.<jk>class</jk> 572 * ) 573 * <jk>public</jk> Object doGetWithSpecialAcceptType() { 574 * <jc>// Handle request for special Accept type</jc> 575 * } 576 * } 577 * </p> 578 * 579 * <h5 class='section'>See Also:</h5> 580 * <ul> 581 * <li class='jf'>{@link RestContext#REST_parsers} 582 * </ul> 583 */ 584 Class<?>[] parsers() default {}; 585 586 /** 587 * Optional path pattern for the specified method. 588 * 589 * <p> 590 * Appending <js>"/*"</js> to the end of the path pattern will make it match any remainder too. 591 * <br>Not appending <js>"/*"</js> to the end of the pattern will cause a 404 (Not found) error to occur if the exact 592 * pattern is not found. 593 * 594 * <p> 595 * The path can contain variables that get resolved to {@link Path @Path} parameters. 596 * 597 * <h5 class='figure'>Examples:</h5> 598 * <p class='bcode w800'> 599 * <ja>@RestMethod</ja>(name=<jsf>GET</jsf>, path=<js>"/myurl/{foo}/{bar}/{baz}/*"</js>) 600 * </p> 601 * <p class='bcode w800'> 602 * <ja>@RestMethod</ja>(name=<jsf>GET</jsf>, path=<js>"/myurl/{0}/{1}/{2}/*"</js>) 603 * </p> 604 * 605 * <p> 606 * If you do not specify a path name, then the path name is inferred from the Java method name. 607 * 608 * <h5 class='figure'>Example:</h5> 609 * <p class='bcode w800'> 610 * <jc>// Path is assumed to be "/foo".</jc> 611 * <ja>@RestMethod</ja>(name=<jsf>GET</jsf>) 612 * <jk>public void</jk> foo() {...} 613 * </p> 614 * 615 * <p> 616 * If you also do not specify the {@link #name()} and the Java method name starts with <js>"get"</js>, <js>"put"</js>, <js>"post"</js>, or <js>"deleted"</js>, 617 * then the HTTP method name is stripped from the inferred path. 618 * 619 * <h5 class='figure'>Examples:</h5> 620 * <p class='bcode w800'> 621 * <jc>// Method is GET, path is "/foo".</jc> 622 * <ja>@RestMethod</ja> 623 * <jk>public void</jk> getFoo() {...} 624 * </p> 625 * <p class='bcode w800'> 626 * <jc>// Method is DELETE, path is "/bar".</jc> 627 * <ja>@RestMethod</ja> 628 * <jk>public void</jk> deleteBar() {...} 629 * </p> 630 * <p class='bcode w800'> 631 * <jc>// Method is GET, path is "/foobar".</jc> 632 * <ja>@RestMethod</ja> 633 * <jk>public void</jk> foobar() {...} 634 * </p> 635 * <p class='bcode w800'> 636 * <jc>// Method is GET, path is "/".</jc> 637 * <ja>@RestMethod</ja> 638 * <jk>public void</jk> get() {...} 639 * </p> 640 * 641 * 642 * <h5 class='section'>See Also:</h5> 643 * <ul> 644 * <li class='ja'>{@link Path} 645 * </ul> 646 */ 647 String path() default ""; 648 649 /** 650 * Sets the POJO swaps for the serializers and parsers defined on this method. 651 * 652 * <p> 653 * If no value is specified, the POJO swaps are inherited from the class. 654 * <br>Otherwise, this value overrides the POJO swaps defined on the class. 655 * 656 * <p> 657 * Use {@link Inherit} to inherit POJO swaps defined on the class. 658 * 659 * <p> 660 * Use {@link None} to suppress inheriting POJO swaps defined on the class. 661 * 662 * <h5 class='section'>See Also:</h5> 663 * <ul> 664 * <li class='jf'>{@link BeanContext#BEAN_pojoSwaps} 665 * </ul> 666 */ 667 Class<?>[] pojoSwaps() default {}; 668 669 /** 670 * URL path pattern priority. 671 * 672 * <p> 673 * To force path patterns to be checked before other path patterns, use a higher priority number. 674 * 675 * <p> 676 * By default, it's <code>0</code>, which means it will use an internal heuristic to determine a best match. 677 */ 678 int priority() default 0; 679 680 /** 681 * Same as {@link RestResource#properties() @RestResource(properties)}, except defines property values by default when this method is called. 682 * 683 * <p> 684 * This is equivalent to simply calling <code>res.addProperties()</code> in the Java method, but is provided for 685 * convenience. 686 */ 687 Property[] properties() default {}; 688 689 /** 690 * Serializers. 691 * 692 * <p> 693 * If no value is specified, the serializers are inherited from the class. 694 * <br>Otherwise, this value overrides the serializers defined on the class. 695 * 696 * <p> 697 * Use {@link Inherit} to inherit serializers defined on the class. 698 * 699 * <p> 700 * Use {@link None} to suppress inheriting serializers defined on the class. 701 * 702 * <h5 class='section'>Example:</h5> 703 * <p class='bcode w800'> 704 * <jk>public class</jk> MyResource <jk>extends</jk> RestServlet { 705 * 706 * <ja>@RestMethod</ja>( 707 * name=<jsf>GET</jsf>, 708 * path=<js>"/foo"</js>, 709 * serializers=MySpecialSerializer.<jk>class</jk> 710 * ) 711 * <jk>public</jk> Object doGetWithSpecialAcceptType() { 712 * <jc>// Handle request for special Accept type</jc> 713 * } 714 * } 715 * </p> 716 * 717 * <h5 class='section'>See Also:</h5> 718 * <ul> 719 * <li class='jf'>{@link RestContext#REST_serializers} 720 * </ul> 721 */ 722 Class<?>[] serializers() default {}; 723 724 /** 725 * Optional summary for the exposed API. 726 * 727 * <p> 728 * This summary is used in the following locations: 729 * <ul class='spaced-list'> 730 * <li> 731 * The value returned by {@link RestRequest#getMethodSummary()}. 732 * <li> 733 * The <js>"$R{methodSummary}"</js> variable. 734 * <li> 735 * The summary of the method in the Swagger page. 736 * </ul> 737 * 738 * <h5 class='section'>Notes:</h5> 739 * <ul class='spaced-list'> 740 * <li> 741 * Corresponds to the swagger field <code>/paths/{path}/{method}/summary</code>. 742 * <li> 743 * Supports {@doc DefaultRestSvlVariables} 744 * (e.g. <js>"$L{my.localized.variable}"</js>). 745 * </ul> 746 */ 747 String summary() default ""; 748 749 /** 750 * Supported accept media types. 751 * 752 * <p> 753 * Overrides the media types inferred from the serializers that identify what media types can be produced by the resource. 754 * 755 * <h5 class='section'>Notes:</h5> 756 * <ul class='spaced-list'> 757 * <li> 758 * Supports {@doc DefaultRestSvlVariables} 759 * (e.g. <js>"$S{mySystemProperty}"</js>). 760 * </ul> 761 * 762 * <h5 class='section'>See Also:</h5> 763 * <ul> 764 * <li class='jf'>{@link RestContext#REST_produces} 765 * </ul> 766 */ 767 String[] produces() default {}; 768 769 /** 770 * Supported content media types. 771 * 772 * <p> 773 * Overrides the media types inferred from the parsers that identify what media types can be consumed by the resource. 774 * 775 * <h5 class='section'>Notes:</h5> 776 * <ul class='spaced-list'> 777 * <li> 778 * Supports {@doc DefaultRestSvlVariables} 779 * (e.g. <js>"$S{mySystemProperty}"</js>). 780 * </ul> 781 * 782 * <h5 class='section'>See Also:</h5> 783 * <ul> 784 * <li class='jf'>{@link RestContext#REST_consumes} 785 * </ul> 786 */ 787 String[] consumes() default {}; 788 789 /** 790 * Provides swagger-specific metadata on this method. 791 * 792 * <p> 793 * Used to populate the auto-generated OPTIONS swagger documentation. 794 * 795 * <p> 796 * The format of this annotation is JSON when all individual parts are concatenated. 797 * <br>The starting and ending <js>'{'</js>/<js>'}'</js> characters around the entire value are optional. 798 * 799 * <h5 class='section'>Example:</h5> 800 * <p class='bcode w800'> 801 * <ja>@RestMethod</ja>( 802 * name=<jsf>PUT</jsf>, 803 * path=<js>"/{propertyName}"</js>, 804 * 805 * <jc>// Swagger info.</jc> 806 * swagger={ 807 * <js>"parameters:["</js>, 808 * <js>"{name:'propertyName',in:'path',description:'The system property name.'},"</js>, 809 * <js>"{in:'body',description:'The new system property value.'}"</js>, 810 * <js>"],"</js>, 811 * <js>"responses:{"</js>, 812 * <js>"302: {headers:{Location:{description:'The root URL of this resource.'}}},"</js>, 813 * <js>"403: {description:'User is not an admin.'}"</js>, 814 * <js>"}"</js> 815 * } 816 * ) 817 * </p> 818 * 819 * <h5 class='section'>Notes:</h5> 820 * <ul class='spaced-list'> 821 * <li> 822 * The format is {@doc juneau-marshall.JsonDetails.SimplifiedJson}. 823 * <br>Multiple lines are concatenated with newlines. 824 * <li> 825 * The starting and ending <js>'{'</js>/<js>'}'</js> characters around the entire value are optional. 826 * <li> 827 * These values are superimposed on top of any Swagger JSON file present for the resource in the classpath. 828 * <li> 829 * Supports {@doc DefaultRestSvlVariables} 830 * (e.g. <js>"$L{my.localized.variable}"</js>). 831 * </ul> 832 * 833 * <h5 class='section'>See Also:</h5> 834 * <ul> 835 * <li class='ja'>{@link MethodSwagger} 836 * <li class='jm'>{@link RestInfoProvider#getSwagger(RestRequest)} 837 * </ul> 838 */ 839 MethodSwagger swagger() default @MethodSwagger; 840}