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