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