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