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