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