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