001/* 002 * Licensed to the Apache Software Foundation (ASF) under one or more 003 * contributor license agreements. See the NOTICE file distributed with 004 * this work for additional information regarding copyright ownership. 005 * The ASF licenses this file to You under the Apache License, Version 2.0 006 * (the "License"); you may not use this file except in compliance with 007 * the License. You may obtain a copy of the License at 008 * 009 * http://www.apache.org/licenses/LICENSE-2.0 010 * 011 * Unless required by applicable law or agreed to in writing, software 012 * distributed under the License is distributed on an "AS IS" BASIS, 013 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 014 * See the License for the specific language governing permissions and 015 * limitations under the License. 016 */ 017package org.apache.juneau.rest.server; 018 019import static java.lang.annotation.ElementType.*; 020import static java.lang.annotation.RetentionPolicy.*; 021 022import java.lang.annotation.*; 023 024import org.apache.juneau.bean.swagger.*; 025import org.apache.juneau.commons.*; 026import org.apache.juneau.commons.inject.*; 027import org.apache.juneau.http.remote.*; 028import org.apache.juneau.marshall.encoders.*; 029import org.apache.juneau.marshall.parser.*; 030import org.apache.juneau.marshall.serializer.*; 031import org.apache.juneau.rest.server.converter.*; 032import org.apache.juneau.rest.server.guard.*; 033import org.apache.juneau.rest.server.matcher.*; 034import org.apache.juneau.rest.server.metrics.*; 035import org.apache.juneau.rest.server.servlet.*; 036import org.apache.juneau.rest.server.swagger.*; 037 038/** 039 * Identifies a REST operation Java method on a {@link RestServlet} implementation class. 040 * 041 * <h2 class='section'>See Also:</h2><ul> 042 * <li class='link'><a class="doclink" href="https://juneau.apache.org/docs/topics/RestOpAnnotatedMethods">@RestOp-Annotated Method</a> 043 044 * </ul> 045 */ 046@Target(METHOD) 047@Retention(RUNTIME) 048@Inherited 049@AnnotationGroup(RestOp.class) 050public @interface RestOp { 051 052 /** 053 * Specifies whether this method can be called based on the client version. 054 * 055 * <p> 056 * The client version is identified via the HTTP request header identified by 057 * {@link Rest#clientVersionHeader() @Rest(clientVersionHeader)} which by default is <js>"Client-Version"</js>. 058 * 059 * <p> 060 * This is a specialized kind of {@link RestMatcher} that allows you to invoke different Java methods for the same 061 * method/path based on the client version. 062 * 063 * <p> 064 * The format of the client version range is similar to that of OSGi versions. 065 * 066 * <p> 067 * In the following example, the Java methods are mapped to the same HTTP method and URL <js>"/foobar"</js>. 068 * <p class='bjava'> 069 * <jc>// Call this method if Client-Version is at least 2.0. 070 * // Note that this also matches 2.0.1.</jc> 071 * <ja>@RestOp</ja>(method=<jsf>GET</jsf>, path=<js>"/foobar"</js>, clientVersion=<js>"2.0"</js>) 072 * <jk>public</jk> Object method1() {...} 073 * 074 * <jc>// Call this method if Client-Version is at least 1.1, but less than 2.0.</jc> 075 * <ja>@RestOp</ja>(method=<jsf>GET</jsf>, path=<js>"/foobar"</js>, clientVersion=<js>"[1.1,2.0)"</js>) 076 * <jk>public</jk> Object method2() {...} 077 * 078 * <jc>// Call this method if Client-Version is less than 1.1.</jc> 079 * <ja>@RestOp</ja>(method=<jsf>GET</jsf>, path=<js>"/foobar"</js>, clientVersion=<js>"[0,1.1)"</js>) 080 * <jk>public</jk> Object method3() {...} 081 * </p> 082 * 083 * <p> 084 * It's common to combine the client version with transforms that will convert new POJOs into older POJOs for 085 * backwards compatibility. 086 * <p class='bjava'> 087 * <jc>// Call this method if Client-Version is at least 2.0.</jc> 088 * <ja>@RestOp</ja>(method=<jsf>GET</jsf>, path=<js>"/foobar"</js>, clientVersion=<js>"2.0"</js>) 089 * <jk>public</jk> NewPojo newMethod() {...} 090 * 091 * <jc>// Call this method if X-Client-Version is at least 1.1, but less than 2.0.</jc> 092 * <ja>@RestOp</ja>(method=<jsf>GET</jsf>, path=<js>"/foobar"</js>, clientVersion=<js>"[1.1,2.0)"</js>) 093 * <ja>@MarshalledConfig(swaps=NewToOldSwap.<jk>class</jk>) 094 * <jk>public</jk> NewPojo oldMethod() { 095 * <jk>return</jk> newMethod(); 096 * } 097 * 098 * <p> 099 * Note that in the previous example, we're returning the exact same POJO, but using a transform to convert it into 100 * an older form. 101 * The old method could also just return back a completely different object. 102 * The range can be any of the following: 103 * <ul> 104 * <li><js>"[0,1.0)"</js> = Less than 1.0. 1.0 and 1.0.0 does not match. 105 * <li><js>"[0,1.0]"</js> = Less than or equal to 1.0. Note that 1.0.1 will match. 106 * <li><js>"1.0"</js> = At least 1.0. 1.0 and 2.0 will match. 107 * </ul> 108 * 109 * <h4 class='section'>See Also:</h4><ul> 110 * <li class='ja'>{@link Rest#clientVersionHeader()} 111 * </ul> 112 * 113 * @return The annotation value. 114 */ 115 String clientVersion() default ""; 116 117 /** 118 * Supported content media types. 119 * 120 * <p> 121 * Overrides the media types inferred from the parsers that identify what media types can be consumed by the resource. 122 * 123 * <h4 class='section'>Notes:</h4><ul> 124 * <li class='note'> 125 * Supports <a class="doclink" href="https://juneau.apache.org/docs/topics/RestServerSvlVariables">REST Server SVL Variables</a> 126 * (e.g. <js>"${S:mySystemProperty}"</js>). 127 * </ul> 128 * 129 * <h4 class='section'>See Also:</h4><ul> 130 * <li class='jm'>{@link RestOpContext#getSupportedContentTypes()} 131 * </ul> 132 * 133 * @return The annotation value. 134 */ 135 String[] consumes() default {}; 136 137 /** 138 * Class-level response converters. 139 * 140 * <p> 141 * Associates one or more {@link RestConverter converters} with this method. 142 * 143 * @return The annotation value. 144 */ 145 Class<? extends RestConverter>[] converters() default {}; 146 147 /** 148 * Default <c>Accept</c> header. 149 * 150 * <p> 151 * The default value for the <c>Accept</c> header if not specified on a request. 152 * 153 * <p> 154 * This is a shortcut for using {@link #defaultRequestHeaders()} for just this specific header. 155 * 156 * @return The annotation value. 157 */ 158 String defaultAccept() default ""; 159 160 /** 161 * Default character encoding. 162 * 163 * <p> 164 * The default character encoding for the request and response if not specified on the request. 165 * 166 * <h4 class='section'>Notes:</h4><ul> 167 * <li class='note'> 168 * Supports <a class="doclink" href="https://juneau.apache.org/docs/topics/RestServerSvlVariables">REST Server SVL Variables</a> 169 * (e.g. <js>"${S:mySystemProperty}"</js>). 170 * </ul> 171 * 172 * <h4 class='section'>See Also:</h4><ul> 173 * <li class='ja'>{@link Rest#defaultCharset} 174 * </ul> 175 * 176 * @return The annotation value. 177 */ 178 String defaultCharset() default ""; 179 180 /** 181 * Default <c>Content-Type</c> header. 182 * 183 * <p> 184 * The default value for the <c>Content-Type</c> header if not specified on a request. 185 * 186 * <p> 187 * This is a shortcut for using {@link #defaultRequestHeaders()} for just this specific header. 188 * 189 * @return The annotation value. 190 */ 191 String defaultContentType() default ""; 192 193 /** 194 * Default request attributes. 195 * 196 * <p> 197 * Specifies default values for request attributes if they're not already set on the request. 198 * 199 * <p> 200 * Affects values returned by the following methods: 201 * <ul> 202 * <li class='jm'>{@link RestRequest#getAttribute(String)}. 203 * <li class='jm'>{@link RestRequest#getAttributes()}. 204 * </ul> 205 * 206 * <h4 class='section'>Example:</h4> 207 * <p class='bjava'> 208 * <jc>// Defined via annotation resolving to a config file setting with default value.</jc> 209 * <ja>@Rest</ja>(defaultRequestAttributes={<js>"Foo=bar"</js>, <js>"Baz: ${C:REST/myAttributeValue}"</js>}) 210 * <jk>public class</jk> MyResource { 211 * 212 * <jc>// Override at the method level.</jc> 213 * <ja>@RestGet</ja>(defaultRequestAttributes={<js>"Foo: bar"</js>}) 214 * <jk>public</jk> Object myMethod() {...} 215 * } 216 * </p> 217 * 218 * <h4 class='section'>Notes:</h4><ul> 219 * <li class='note'> 220 * Supports <a class="doclink" href="https://juneau.apache.org/docs/topics/RestServerSvlVariables">REST Server SVL Variables</a> 221 * (e.g. <js>"${L:my.localized.variable}"</js>). 222 * </ul> 223 * 224 * <h4 class='section'>See Also:</h4><ul> 225 * <li class='ja'>{@link Rest#defaultRequestAttributes()} 226 * </ul> 227 * 228 * @return The annotation value. 229 */ 230 String[] defaultRequestAttributes() default {}; 231 232 /** 233 * Specifies default values for form-data parameters. 234 * 235 * <p> 236 * Strings are of the format <js>"name=value"</js>. 237 * 238 * <p> 239 * Affects values returned by {@link RestRequest#getFormParam(String)} when the parameter is not present on the 240 * request. 241 * 242 * <h4 class='section'>Example:</h4> 243 * <p class='bjava'> 244 * <ja>@RestOp</ja>(method=<jsf>POST</jsf>, path=<js>"/*"</js>, defaultRequestFormData={<js>"foo=bar"</js>}) 245 * <jk>public</jk> String doPost(<ja>@FormData</ja>(<js>"foo"</js>) String <jv>foo</jv>) {...} 246 * </p> 247 * 248 * <h4 class='section'>Notes:</h4><ul> 249 * <li class='note'> 250 * You can use either <js>':'</js> or <js>'='</js> as the key/value delimiter. 251 * <li class='note'> 252 * Key and value is trimmed of whitespace. 253 * <li class='note'> 254 * Supports <a class="doclink" href="https://juneau.apache.org/docs/topics/RestServerSvlVariables">REST Server SVL Variables</a> 255 * (e.g. <js>"${S:mySystemProperty}"</js>). 256 * </ul> 257 * 258 * @return The annotation value. 259 */ 260 String[] defaultRequestFormData() default {}; 261 262 /** 263 * Default request headers. 264 * 265 * <p> 266 * Specifies default values for request headers if they're not passed in through the request. 267 * 268 * <h4 class='section'>Example:</h4> 269 * <p class='bjava'> 270 * <jc>// Assume "text/json" Accept value when Accept not specified</jc> 271 * <ja>@RestOp</ja>(method=<jsf>GET</jsf>, path=<js>"/*"</js>, defaultRequestHeaders={<js>"Accept: text/json"</js>}) 272 * <jk>public</jk> String doGet() {...} 273 * </p> 274 * 275 * <h4 class='section'>Notes:</h4><ul> 276 * <li class='note'> 277 * Supports <a class="doclink" href="https://juneau.apache.org/docs/topics/RestServerSvlVariables">REST Server SVL Variables</a> 278 * (e.g. <js>"${S:mySystemProperty}"</js>). 279 * </ul> 280 * 281 * @return The annotation value. 282 */ 283 String[] defaultRequestHeaders() default {}; 284 285 /** 286 * Specifies default values for query parameters. 287 * 288 * <p> 289 * Strings are of the format <js>"name=value"</js>. 290 * 291 * <p> 292 * Affects values returned by {@link RestRequest#getQueryParam(String)} when the parameter is not present on the request. 293 * 294 * <h4 class='section'>Example:</h4> 295 * <p class='bjava'> 296 * <ja>@RestOp</ja>(method=<jsf>GET</jsf>, path=<js>"/*"</js>, defaultRequestQueryData={<js>"foo=bar"</js>}) 297 * <jk>public</jk> String doGet(<ja>@Query</ja>(<js>"foo"</js>) String <jv>foo</jv>) {...} 298 * </p> 299 * 300 * <h4 class='section'>Notes:</h4><ul> 301 * <li class='note'> 302 * You can use either <js>':'</js> or <js>'='</js> as the key/value delimiter. 303 * <li class='note'> 304 * Key and value is trimmed of whitespace. 305 * <li class='note'> 306 * Supports <a class="doclink" href="https://juneau.apache.org/docs/topics/RestServerSvlVariables">REST Server SVL Variables</a> 307 * (e.g. <js>"${S:mySystemProperty}"</js>). 308 * </ul> 309 * 310 * @return The annotation value. 311 */ 312 String[] defaultRequestQueryData() default {}; 313 314 /** 315 * Default response headers. 316 * 317 * <p> 318 * Specifies default values for response headers if they're not overwritten during the request. 319 * 320 * <h4 class='section'>Example:</h4> 321 * <p class='bjava'> 322 * <jc>// Assume "text/json" Accept value when Accept not specified</jc> 323 * <ja>@RestOp</ja>(method=<jsf>GET</jsf>, path=<js>"/*"</js>, defaultResponseHeaders={<js>"Content-Type: text/json"</js>}) 324 * <jk>public</jk> String doGet() {...} 325 * </p> 326 * 327 * <h4 class='section'>Notes:</h4><ul> 328 * <li class='note'> 329 * Supports <a class="doclink" href="https://juneau.apache.org/docs/topics/RestServerSvlVariables">REST Server SVL Variables</a> 330 * (e.g. <js>"${S:mySystemProperty}"</js>). 331 * </ul> 332 * 333 * @return The annotation value. 334 */ 335 String[] defaultResponseHeaders() default {}; 336 337 /** 338 * Optional description for the exposed API. 339 * 340 * <p> 341 * This description is used in the following locations: 342 * <ul class='spaced-list'> 343 * <li> 344 * The value returned by {@link Operation#getDescription()} in the auto-generated swagger. 345 * <li> 346 * The <js>"${RS:operationDescription}"</js> variable. 347 * <li> 348 * The description of the method in the Swagger page. 349 * </ul> 350 * 351 * <h4 class='section'>Notes:</h4><ul> 352 * <li class='note'> 353 * Corresponds to the swagger field <c>/paths/{path}/{method}/description</c>. 354 * <li class='note'> 355 * Supports <a class="doclink" href="https://juneau.apache.org/docs/topics/RestServerSvlVariables">REST Server SVL Variables</a> 356 * (e.g. <js>"${L:my.localized.variable}"</js>). 357 * </ul> 358 * 359 * @return The annotation value. 360 */ 361 String[] description() default {}; 362 363 /** 364 * Specifies the compression encoders for this method. 365 * 366 * <p> 367 * Encoders are used to enable various kinds of compression (e.g. <js>"gzip"</js>) on requests and responses. 368 * 369 * <p> 370 * This value overrides encoders specified at the class level using {@link Rest#encoders()}. 371 * The {@link org.apache.juneau.marshall.encoders.EncoderSet.Inherit EncoderSet.Inherit} class can be used to include values from the parent class. 372 * 373 * <h4 class='section'>Example:</h4> 374 * <p class='bjava'> 375 * <jc>// Define a REST resource that handles GZIP compression.</jc> 376 * <ja>@Rest</ja>( 377 * encoders={ 378 * GzipEncoder.<jk>class</jk> 379 * } 380 * ) 381 * <jk>public class</jk> MyResource { 382 * 383 * <jc>// Define a REST method that can also use a custom encoder.</jc> 384 * <ja>@RestOp</ja>( 385 * method=<jsf>GET</jsf>, 386 * encoders={ 387 * EncoderSet.Inherit.<jk>class</jk>, MyEncoder.<jk>class</jk> 388 * } 389 * ) 390 * <jk>public</jk> MyBean doGet() { 391 * ... 392 * } 393 * } 394 * </p> 395 * 396 * <p> 397 * For programmatic equivalents, contribute a {@link EncoderSet} bean via 398 * {@link Bean @Bean(name="encoders")} (use methodScope to scope to specific operation methods). 399 * 400 * <h4 class='section'>See Also:</h4><ul> 401 * <li class='link'><a class="doclink" href="https://juneau.apache.org/docs/topics/RestServerEncoders">Encoders in REST servers</a> 402 * </ul> 403 * 404 * @return The annotation value. 405 */ 406 Class<? extends Encoder>[] encoders() default {}; 407 408 /** 409 * Method-level guards. 410 * 411 * <p> 412 * Associates one or more {@link RestGuard RestGuards} with this method. 413 * 414 * @return The annotation value. 415 */ 416 Class<? extends RestGuard>[] guards() default {}; 417 418 /** 419 * Method matchers. 420 * 421 * <p> 422 * Associates one more more {@link RestMatcher RestMatchers} with this method. 423 * 424 * <p> 425 * Matchers are used to allow multiple Java methods to handle requests assigned to the same URL path pattern, but 426 * differing based on some request attribute, such as a specific header value. 427 * 428 * <h4 class='section'>See Also:</h4><ul> 429 * <li class='jac'>{@link RestMatcher} 430 * </ul> 431 * 432 * @return The annotation value. 433 */ 434 Class<? extends RestMatcher>[] matchers() default {}; 435 436 /** 437 * The maximum allowed input size (in bytes) on HTTP requests. 438 * 439 * <p> 440 * Useful for alleviating DoS attacks by throwing an exception when too much input is received instead of resulting 441 * in out-of-memory errors which could affect system stability. 442 * 443 * <h4 class='section'>Example:</h4> 444 * <p class='bjava'> 445 * <ja>@RestOp</ja>( 446 * maxInput=<js>"10M"</js> 447 * ) 448 * </p> 449 * 450 * <h4 class='section'>Notes:</h4><ul> 451 * <li> 452 * Supports <a class="doclink" href="https://juneau.apache.org/docs/topics/RestServerSvlVariables">REST Server SVL Variables</a> 453 * (e.g. <js>"${S:mySystemProperty}"</js>). 454 * </ul> 455 * 456 * <h4 class='section'>See Also:</h4><ul> 457 * <li class='ja'>{@link Rest#maxInput} 458 * </ul> 459 * 460 * @return The annotation value. 461 */ 462 String maxInput() default ""; 463 464 /** 465 * REST method name. 466 * 467 * <p> 468 * Typically <js>"GET"</js>, <js>"PUT"</js>, <js>"POST"</js>, <js>"DELETE"</js>, or <js>"OPTIONS"</js>. 469 * 470 * <p> 471 * Method names are case-insensitive (always folded to upper-case). 472 * 473 * <p> 474 * Note that you can use {@link org.apache.juneau.http.HttpMethod} for constant values. 475 * 476 * <p> 477 * Note that you can also use {@link #value()} to specify the method name and path in shortened form. 478 * 479 * <p> 480 * Besides the standard HTTP method names, the following can also be specified: 481 * <ul class='spaced-list'> 482 * <li> 483 * <js>"*"</js> 484 * - Denotes any method. 485 * <br>Use this if you want to capture any HTTP methods in a single Java method. 486 * <br>The {@link Method @Method} annotation and/or {@link RestRequest#getMethod()} method can be used to 487 * distinguish the actual HTTP method name. 488 * <li> 489 * <js>""</js> 490 * - Auto-detect. 491 * <br>The method name is determined based on the Java method name. 492 * <br>For example, if the method is <c>doPost(...)</c>, then the method name is automatically detected 493 * as <js>"POST"</js>. 494 * <br>Otherwise, defaults to <js>"GET"</js>. 495 * <li> 496 * <js>"RRPC"</js> 497 * - Remote-proxy interface. 498 * <br>This denotes a Java method that returns an object (usually an interface, often annotated with the 499 * {@link Remote @Remote} annotation) to be used as a remote proxy using 500 * <c>RestClient.getRemoteInterface(Class<T> interfaceClass, String url)</c>. 501 * <br>This allows you to construct client-side interface proxies using REST as a transport medium. 502 * <br>Conceptually, this is simply a fancy <c>POST</c> against the url <js>"/{path}/{javaMethodName}"</js> 503 * where the arguments are marshalled from the client to the server as an HTTP content containing an array of 504 * objects, passed to the method as arguments, and then the resulting object is marshalled back to the client. 505 * <li> 506 * Anything else 507 * - Overloaded non-HTTP-standard names that are passed in through a <c>&method=methodName</c> URL 508 * parameter. 509 * <br>On a safe request (<c>GET</c>, <c>HEAD</c>, <c>OPTIONS</c>, <c>TRACE</c>), only when the operation is 510 * declared {@link #read() read=true}. 511 * </ul> 512 * 513 * @return The annotation value. 514 */ 515 String method() default ""; 516 517 /** 518 * Specifies the parsers for converting HTTP request bodies into POJOs for this method. 519 * 520 * <p> 521 * Parsers are used to convert the content of HTTP requests into POJOs. 522 * <br>Any of the Juneau framework parsers can be used in this setting. 523 * <br>The parser selected is based on the request <c>Content-Type</c> header matched against the values returned by the following method 524 * using a best-match algorithm: 525 * <ul class='javatree'> 526 * <li class='jm'>{@link Parser#getMediaTypes()} 527 * </ul> 528 * 529 * <p> 530 * This value overrides parsers specified at the class level using {@link Rest#parsers()}. 531 * The {@link org.apache.juneau.marshall.parser.ParserSet.Inherit ParserSet.Inherit} class can be used to include values from the parent class. 532 * 533 * <h4 class='section'>Example:</h4> 534 * <p class='bjava'> 535 * <jc>// Define a REST resource that can consume JSON and HTML.</jc> 536 * <ja>@Rest</ja>( 537 * parsers={ 538 * JsonParser.<jk>class</jk>, 539 * HtmlParser.<jk>class</jk> 540 * } 541 * ) 542 * <jk>public class</jk> MyResource { 543 * 544 * <jc>// Define a REST method that can also consume XML.</jc> 545 * <ja>@RestOp</ja>( 546 * method=<jsf>POST</jsf>, 547 * parsers={ 548 * ParserSet.Inherit.<jk>class</jk>, XmlParser.<jk>class</jk> 549 * } 550 * ) 551 * <jk>public void</jk> doPost(MyBean <jv>bean</jv>) { 552 * ... 553 * } 554 * } 555 * </p> 556 * 557 * <p> 558 * For programmatic equivalents, contribute a {@link ParserSet} bean via 559 * {@link Bean @Bean(name="parsers")} (use methodScope to scope to specific operation methods). 560 * 561 * <h4 class='section'>See Also:</h4><ul> 562 * <li class='link'><a class="doclink" href="https://juneau.apache.org/docs/topics/Marshalling">Marshalling</a> 563 * </ul> 564 * 565 * @return The annotation value. 566 */ 567 Class<?>[] parsers() default {}; 568 569 /** 570 * Optional path pattern for the specified method. 571 * 572 * <p> 573 * Appending <js>"/*"</js> to the end of the path pattern will make it match any remainder too. 574 * <br>Not appending <js>"/*"</js> to the end of the pattern will cause a 404 (Not found) error to occur if the exact 575 * pattern is not found. 576 * 577 * <p> 578 * The path can contain variables that get resolved to {@link org.apache.juneau.http.Path @Path} parameters. 579 * 580 * <h4 class='figure'>Examples:</h4> 581 * <p class='bjava'> 582 * <ja>@RestOp</ja>(method=<jsf>GET</jsf>, path=<js>"/myurl/{foo}/{bar}/{baz}/*"</js>) 583 * </p> 584 * <p class='bjava'> 585 * <ja>@RestOp</ja>(method=<jsf>GET</jsf>, path=<js>"/myurl/{0}/{1}/{2}/*"</js>) 586 * </p> 587 * 588 * <p> 589 * If you do not specify a path name, then the path name is inferred from the Java method name. 590 * 591 * <h4 class='figure'>Example:</h4> 592 * <p class='bjava'> 593 * <jc>// Path is assumed to be "/foo".</jc> 594 * <ja>@RestOp</ja>(method=<jsf>GET</jsf>) 595 * <jk>public void</jk> foo() {...} 596 * </p> 597 * 598 * <p> 599 * If you also do not specify the {@link #method()} and the Java method name starts with <js>"get"</js>, <js>"put"</js>, <js>"post"</js>, or <js>"delete"</js>, 600 * then the HTTP method name is stripped from the inferred path. 601 * 602 * <h4 class='figure'>Examples:</h4> 603 * <p class='bjava'> 604 * <jc>// Method is GET, path is "/foo".</jc> 605 * <ja>@RestOp</ja> 606 * <jk>public void</jk> getFoo() {...} 607 * </p> 608 * <p class='bjava'> 609 * <jc>// Method is DELETE, path is "/bar".</jc> 610 * <ja>@RestOp</ja> 611 * <jk>public void</jk> deleteBar() {...} 612 * </p> 613 * <p class='bjava'> 614 * <jc>// Method is GET, path is "/foobar".</jc> 615 * <ja>@RestOp</ja> 616 * <jk>public void</jk> foobar() {...} 617 * </p> 618 * <p class='bjava'> 619 * <jc>// Method is GET, path is "/".</jc> 620 * <ja>@RestOp</ja> 621 * <jk>public void</jk> get() {...} 622 * </p> 623 * 624 * <p> 625 * Note that you can also use {@link #value()} to specify the method name and path in shortened form. 626 * 627 * <h4 class='section'>See Also:</h4><ul> 628 * <li class='ja'>{@link org.apache.juneau.http.Path} 629 * </ul> 630 * 631 * @return The annotation value. 632 */ 633 String[] path() default {}; 634 635 /** 636 * Per-operation override for {@link Rest#problemDetails() @Rest(problemDetails)}. 637 * 638 * <p> 639 * When set on a {@code @RestOp} method, this value takes precedence over the resource-level 640 * {@code @Rest(problemDetails)} attribute for this operation. Tri-state semantics: 641 * 642 * <ul class='values'> 643 * <li><js>"true"</js> — enable problem-details responses for this operation. 644 * <li><js>"false"</js> — disable problem-details responses for this operation (overrides an 645 * opted-in resource). 646 * <li><js>""</js> (default) — inherit from {@link Rest#problemDetails()}. 647 * </ul> 648 * 649 * <h4 class='section'>Notes:</h4><ul> 650 * <li class='note'> 651 * Supports <a class="doclink" href="https://juneau.apache.org/docs/topics/RestServerSvlVariables">REST Server SVL Variables</a> 652 * (e.g. <js>"${L:my.localized.variable}"</js>). 653 * </ul> 654 * 655 * <h4 class='section'>See Also:</h4><ul> 656 * <li class='ja'>{@link Rest#problemDetails()} 657 * </ul> 658 * 659 * @return The annotation value. 660 */ 661 String problemDetails() default ""; 662 663 /** 664 * Per-operation override for {@link Rest#debugMarshalling() @Rest(debugMarshalling)}. 665 * 666 * <p> 667 * When set on a {@code @RestOp} method, this value takes precedence over the resource-level 668 * {@code @Rest(debugMarshalling)} attribute for this operation. Tri-state semantics: 669 * 670 * <ul class='values'> 671 * <li><js>"true"</js> — enable marshalling debug for this operation. 672 * <li><js>"false"</js> — disable marshalling debug for this operation (overrides an opted-in resource). 673 * <li><js>""</js> (default) — inherit from {@link Rest#debugMarshalling()}. 674 * </ul> 675 * 676 * <h4 class='section'>Notes:</h4><ul> 677 * <li class='note'> 678 * Supports <a class="doclink" href="https://juneau.apache.org/docs/topics/RestServerSvlVariables">REST Server SVL Variables</a>. 679 * </ul> 680 * 681 * <h4 class='section'>See Also:</h4><ul> 682 * <li class='ja'>{@link Rest#debugMarshalling()} 683 * </ul> 684 * 685 * @return The annotation value. 686 */ 687 String debugMarshalling() default ""; 688 689 /** 690 * Per-operation override for {@link Rest#virtualThreads() @Rest(virtualThreads)}. 691 * 692 * <p> 693 * When set, this value takes precedence over the resource-level setting for this operation. Tri-state 694 * semantics: 695 * 696 * <ul class='values'> 697 * <li><js>"true"</js> — enable virtual-thread dispatch for this operation (Java 21+ only; 698 * gracefully ignored on older JVMs). 699 * <li><js>"false"</js> — disable virtual-thread dispatch for this operation (overrides an 700 * opted-in resource). 701 * <li><js>""</js> (default) — inherit from {@link Rest#virtualThreads()}. 702 * </ul> 703 * 704 * <h4 class='section'>Notes:</h4><ul> 705 * <li class='note'> 706 * Supports <a class="doclink" href="https://juneau.apache.org/docs/topics/RestServerSvlVariables">REST Server SVL Variables</a> 707 * (e.g. <js>"${E:ENABLE_VT:false}"</js>). 708 * </ul> 709 * 710 * <h4 class='section'>See Also:</h4><ul> 711 * <li class='ja'>{@link Rest#virtualThreads()} 712 * </ul> 713 * 714 * @return The annotation value. 715 */ 716 String virtualThreads() default ""; 717 718 /** 719 * Per-operation observability opt-in / opt-out control. 720 * 721 * <p> 722 * Overrides the resource-level {@link Rest#observability()} setting for this specific operation. 723 * Controls whether the observability block ({@link MetricsRecorder} / 724 * {@link org.apache.juneau.rest.server.tracing.TracerHook}) fires for this operation. 725 * 726 * <ul class='values'> 727 * <li><js>"true"</js> — strict opt-in: this operation <em>requires</em> a wired observability backend. 728 * If neither a {@code @Bean MetricsRecorder} nor a {@code @Bean TracerHook} is registered when the 729 * {@link RestContext} is built, construction fails with a precise error. 730 * <li><js>"false"</js> — explicit opt-out: the observability block is short-circuited for this operation, 731 * even when a wired backend is present. Also suppresses 732 * {@link org.apache.juneau.rest.server.tracing.TraceContextResponseProcessor} header injection. 733 * <li><js>""</js> (default) — inherits the resource-level {@link Rest#observability()} setting. 734 * If the resource-level setting is also empty, uses the existing behavior: the observability block 735 * runs per-op, but a missing backend silently falls back to the NoOp singleton. 736 * </ul> 737 * 738 * <h4 class='section'>Notes:</h4><ul> 739 * <li class='note'> 740 * Supports <a class="doclink" href="https://juneau.apache.org/docs/topics/RestServerSvlVariables">REST Server SVL Variables</a> 741 * (e.g. <js>"${E:ENABLE_OP_OBSERVABILITY:false}"</js>). 742 * <li class='note'> 743 * This per-operation setting takes full precedence over {@link Rest#observability()}. 744 * </ul> 745 * 746 * <h4 class='section'>See Also:</h4><ul> 747 * <li class='ja'>{@link Rest#observability()} 748 * <li class='jc'>{@link MetricsRecorder} 749 * <li class='jc'>{@link org.apache.juneau.rest.server.tracing.TracerHook} 750 * </ul> 751 * 752 * @return The annotation value. 753 * @since 10.0.0 754 */ 755 String observability() default ""; 756 757 /** 758 * Per-operation metric name override. 759 * 760 * <p> 761 * Overrides the metric name passed to {@link MetricsRecorder#record(String, String, String, int, java.time.Duration, Throwable, String, String) record()} 762 * for this operation. When empty (default), the recorder uses its own default name derivation (typically the 763 * fully-qualified operation name). 764 * 765 * <h4 class='section'>Notes:</h4><ul> 766 * <li class='note'> 767 * Supports <a class="doclink" href="https://juneau.apache.org/docs/topics/RestServerSvlVariables">REST Server SVL Variables</a>. 768 * <li class='note'> 769 * Has no effect when observability is disabled for this operation. 770 * </ul> 771 * 772 * @return The annotation value. 773 * @since 10.0.0 774 */ 775 String metricName() default ""; 776 777 /** 778 * Per-operation metric tags. 779 * 780 * <p> 781 * Additional metric tags to pass to {@link MetricsRecorder#record(String, String, String, int, java.time.Duration, Throwable, String, String) record()}. 782 * Format: comma-separated {@code key=value} pairs, e.g. {@code "team=payments,region=us-east"}. 783 * When empty (default), no additional tags are passed. 784 * 785 * <h4 class='section'>Notes:</h4><ul> 786 * <li class='note'> 787 * Supports <a class="doclink" href="https://juneau.apache.org/docs/topics/RestServerSvlVariables">REST Server SVL Variables</a>. 788 * <li class='note'> 789 * The recorder implementation is responsible for parsing the comma-separated {@code key=value} string. 790 * <li class='note'> 791 * Has no effect when observability is disabled for this operation. 792 * </ul> 793 * 794 * @return The annotation value. 795 * @since 10.0.0 796 */ 797 String metricTags() default ""; 798 799 /** 800 * Per-operation override for {@link Rest#asyncTimeoutMillis() @Rest(asyncTimeoutMillis)}. 801 * 802 * <p> 803 * Configurable timeout (milliseconds) applied to {@link java.util.concurrent.CompletableFuture}-returning 804 * handlers. Default is 30,000 ms inherited from the resource. Set to {@code "0"} to disable the timeout. 805 * 806 * <h4 class='section'>Notes:</h4><ul> 807 * <li class='note'> 808 * Supports <a class="doclink" href="https://juneau.apache.org/docs/topics/RestServerSvlVariables">REST Server SVL Variables</a>. 809 * </ul> 810 * 811 * <h4 class='section'>See Also:</h4><ul> 812 * <li class='ja'>{@link Rest#asyncTimeoutMillis()} 813 * </ul> 814 * 815 * @return The annotation value. 816 */ 817 String asyncTimeoutMillis() default ""; 818 819 /** 820 * Per-operation override for {@link Rest#asyncCompletionExecutor() @Rest(asyncCompletionExecutor)}. 821 * 822 * <p> 823 * Names the {@link java.util.concurrent.Executor} bean used to route completion callbacks for this 824 * specific operation through a dedicated thread pool. Empty string (default) inherits from 825 * {@link Rest#asyncCompletionExecutor()}. 826 * 827 * <h4 class='section'>See Also:</h4><ul> 828 * <li class='ja'>{@link Rest#asyncCompletionExecutor()} 829 * </ul> 830 * 831 * @return The annotation value. 832 * @since 10.0.0 833 */ 834 String asyncCompletionExecutor() default ""; 835 836 /** 837 * Supported accept media types. 838 * 839 * <p> 840 * Overrides the media types inferred from the serializers that identify what media types can be produced by the resource. 841 * 842 * <h4 class='section'>Notes:</h4><ul> 843 * <li class='note'> 844 * Supports <a class="doclink" href="https://juneau.apache.org/docs/topics/RestServerSvlVariables">REST Server SVL Variables</a> 845 * (e.g. <js>"${S:mySystemProperty}"</js>). 846 * </ul> 847 * 848 * <h4 class='section'>See Also:</h4><ul> 849 * <li class='jm'>{@link RestOpContext#getSupportedAcceptTypes()} 850 * </ul> 851 * 852 * @return The annotation value. 853 */ 854 String[] produces() default {}; 855 856 /** 857 * Allowed serializer session option keys for this operation (ordered merge, prefix {@code -key} removes a key). 858 * 859 * <p> 860 * Comma-delimited list of session property keys that clients may send via the <js>"X-Juneau-Serializer-Options"</js> 861 * header or <js>"juneauSerializerOptions"</js> query parameter. 862 * Merged on top of resource-level {@link Rest#allowedSerializerOptions()} values. 863 * Use {@link #noInherit()} to replace rather than extend the resource-level list. 864 * 865 * <h4 class='section'>See Also:</h4><ul> 866 * <li class='link'><a class="doclink" href="https://juneau.apache.org/docs/topics/SessionOptions#safe-properties">Safe Properties</a> 867 * </ul> 868 * 869 * @return The annotation value. 870 */ 871 String[] allowedSerializerOptions() default {}; 872 873 /** 874 * Allowed parser session option keys for this operation (ordered merge, prefix {@code -key} removes a key). 875 * 876 * <p> 877 * Comma-delimited list of session property keys that clients may send via the <js>"X-Juneau-Parser-Options"</js> 878 * header or <js>"juneauParserOptions"</js> query parameter. 879 * Merged on top of resource-level {@link Rest#allowedParserOptions()} values. 880 * Use {@link #noInherit()} to replace rather than extend the resource-level list. 881 * 882 * <h4 class='section'>See Also:</h4><ul> 883 * <li class='link'><a class="doclink" href="https://juneau.apache.org/docs/topics/SessionOptions#safe-properties">Safe Properties</a> 884 * </ul> 885 * 886 * @return The annotation value. 887 */ 888 String[] allowedParserOptions() default {}; 889 890 /** 891 * Property names for which less-derived contributions are NOT inherited. 892 * 893 * <p> 894 * Accepted values: {@code "allowedSerializerOptions"}, {@code "allowedParserOptions"}, 895 * {@code "problemDetails"}, {@code "debugMarshalling"}. 896 * Prevents the named property from inheriting values from the enclosing {@code @Rest} annotation. 897 * The {@code noInherit} attribute itself is never inherited. 898 * 899 * <h4 class='section'>See Also:</h4><ul> 900 * <li class='link'><a class="doclink" href="https://juneau.apache.org/docs/topics/SessionOptions">Session Options via HTTP</a> 901 * </ul> 902 * 903 * @return The annotation value. 904 */ 905 String[] noInherit() default {}; 906 907 /** 908 * Declares that this operation's custom method is a read. 909 * 910 * <p> 911 * A request whose request line is safe (<c>GET</c>, <c>HEAD</c>, <c>OPTIONS</c> or <c>TRACE</c>) may be overridden 912 * (through the {@code method} query parameter or an override header, see {@link Rest#allowedMethodParams()} and 913 * {@link Rest#allowedMethodHeaders()}) only to another safe method, or to the method of an operation declared 914 * <c>read=<jk>true</jk></c>. Any other override of a safe request is refused with <c>405 Method Not Allowed</c>, 915 * so a link, a crawler or a prefetcher following a plain <c>GET</c> can never reach an operation that changes state. 916 * 917 * <h4 class='section'>Example:</h4> 918 * <p class='bjava'> 919 * <jc>// Reachable as GET /files/foo.txt?method=VIEW, as well as VIEW /files/foo.txt.</jc> 920 * <ja>@RestOp</ja>(method=<js>"VIEW"</js>, path=<js>"/files/*"</js>, read=<jk>true</jk>) 921 * <jk>public</jk> Reader view(...) {...} 922 * </p> 923 * 924 * <p> 925 * The declaration is the developer's promise that the operation does not change state, exactly as <c>GET</c> 926 * promises. Nothing can verify it. {@link Mutating @Mutating} is the opposite promise. 927 * 928 * <h4 class='section'>Notes:</h4><ul> 929 * <li class='note'> 930 * The attribute is read from the annotation that supplies the operation's method (or, when the method is 931 * inferred from the Java method name, from the nearest <ja>@RestOp</ja>). A subclass that re-declares the method 932 * therefore also re-declares whether it is a read: <c>read=<jk>true</jk></c> on an overridden annotation that 933 * names its own method is replaced along with that method. <c>read=<jk>true</jk></c> on another 934 * <ja>@RestOp</ja> in the chain that names no method would be silently ignored, so it fails the resource when 935 * its operations are assembled. 936 * <li class='note'> 937 * <c>read=<jk>true</jk></c> fails the resource when the method is <c>POST</c>, <c>PUT</c>, <c>PATCH</c>, 938 * <c>DELETE</c>, <c>CONNECT</c>, <js>"*"</js> or <js>"RRPC"</js>, or when the Java method is also 939 * {@link Mutating @Mutating}. On a safe method it is redundant and has no effect. 940 * <li class='note'> 941 * A CSRF or loopback boundary filter still judges a request on the method it claims, so behind a boundary a 942 * <c>GET ?method=VIEW</c> is treated as a write. Prefer path-based links (<c>/view/{file}</c>) for reads. 943 * </ul> 944 * 945 * <h4 class='section'>See Also:</h4><ul> 946 * <li class='ja'>{@link Mutating} 947 * <li class='jm'>{@link MethodSafety#check(java.util.List)} 948 * </ul> 949 * 950 * @return The annotation value. 951 * @since 10.0.0 952 */ 953 boolean read() default false; 954 955 /** 956 * Role guard. 957 * 958 * <p> 959 * An expression defining if a user with the specified roles are allowed to access this method. 960 * 961 * <h4 class='section'>Example:</h4> 962 * <p class='bjava'> 963 * <jk>public class</jk> MyResource <jk>extends</jk> BasicRestServlet { 964 * 965 * <ja>@RestOp</ja>( 966 * method=<jsf>GET</jsf>, 967 * path=<js>"/foo"</js>, 968 * roleGuard=<js>"ROLE_ADMIN || (ROLE_READ_WRITE && ROLE_SPECIAL)"</js> 969 * ) 970 * <jk>public</jk> Object doGet() { 971 * } 972 * } 973 * </p> 974 * 975 * <h4 class='section'>Notes:</h4><ul> 976 * <li class='note'> 977 * Supports any of the following expression constructs: 978 * <ul> 979 * <li><js>"foo"</js> - Single arguments. 980 * <li><js>"foo,bar,baz"</js> - Multiple OR'ed arguments. 981 * <li><js>"foo | bar | baz"</js> - Multiple OR'ed arguments, pipe syntax. 982 * <li><js>"foo || bar || baz"</js> - Multiple OR'ed arguments, Java-OR syntax. 983 * <li><js>"fo*"</js> - Patterns including <js>'*'</js> and <js>'?'</js>. 984 * <li><js>"fo* & *oo"</js> - Multiple AND'ed arguments, ampersand syntax. 985 * <li><js>"fo* && *oo"</js> - Multiple AND'ed arguments, Java-AND syntax. 986 * <li><js>"fo* || (*oo || bar)"</js> - Parenthesis. 987 * </ul> 988 * <li class='note'> 989 * AND operations take precedence over OR operations (as expected). 990 * <li class='note'> 991 * Whitespace is ignored. 992 * <li class='note'> 993 * <jk>null</jk> or empty expressions always match as <jk>false</jk>. 994 * <li class='note'> 995 * If patterns are used, you must specify the list of declared roles using {@link #rolesDeclared()}. 996 * <li class='note'> 997 * Supports <a class="doclink" href="https://juneau.apache.org/docs/topics/RestServerSvlVariables">REST Server SVL Variables</a> 998 * (e.g. <js>"${L:my.localized.variable}"</js>). 999 * <li class='note'> 1000 * When defined on parent/child classes and methods, ALL guards within the hierarchy must pass. 1001 * </ul> 1002 * 1003 * @return The annotation value. 1004 */ 1005 String roleGuard() default ""; 1006 1007 /** 1008 * Declared roles. 1009 * 1010 * <p> 1011 * A comma-delimited list of all possible user roles. 1012 * 1013 * <p> 1014 * Used in conjunction with {@link #roleGuard()} is used with patterns. 1015 * 1016 * <h4 class='section'>Example:</h4> 1017 * <p class='bjava'> 1018 * <jk>public class</jk> MyResource <jk>extends</jk> BasicRestServlet { 1019 * 1020 * <ja>@RestOp</ja>( 1021 * method=<jsf>GET</jsf>, 1022 * path=<js>"/foo"</js>, 1023 * rolesDeclared=<js>"ROLE_ADMIN,ROLE_READ_WRITE,ROLE_READ_ONLY,ROLE_SPECIAL"</js>, 1024 * roleGuard=<js>"ROLE_ADMIN || (ROLE_READ_WRITE && ROLE_SPECIAL)"</js> 1025 * ) 1026 * <jk>public</jk> Object doGet() { 1027 * } 1028 * } 1029 * </p> 1030 * 1031 * @return The annotation value. 1032 */ 1033 String rolesDeclared() default ""; 1034 1035 /** 1036 * Specifies the serializers for marshalling POJOs into response bodies for this method. 1037 * 1038 * <p> 1039 * Serializer are used to convert POJOs to HTTP response bodies. 1040 * <br>Any of the Juneau framework serializers can be used in this setting. 1041 * <br>The serializer selected is based on the request <c>Accept</c> header matched against the values returned by the following method 1042 * using a best-match algorithm: 1043 * <ul class='javatree'> 1044 * <li class='jm'>{@link Serializer#getMediaTypeRanges()} 1045 * </ul> 1046 * 1047 * <p> 1048 * This value overrides serializers specified at the class level using {@link Rest#serializers()}. 1049 * The {@link org.apache.juneau.marshall.serializer.SerializerSet.Inherit SerializerSet.Inherit} class can be used to include values from the parent class. 1050 * 1051 * <h4 class='section'>Example:</h4> 1052 * <p class='bjava'> 1053 * <jc>// Define a REST resource that can produce JSON and HTML.</jc> 1054 * <ja>@Rest</ja>( 1055 * serializers={ 1056 * JsonParser.<jk>class</jk>, 1057 * HtmlParser.<jk>class</jk> 1058 * } 1059 * ) 1060 * <jk>public class</jk> MyResource { 1061 * 1062 * <jc>// Define a REST method that can also produce XML.</jc> 1063 * <ja>@RestOp</ja>( 1064 * method=<jsf>POST</jsf>, 1065 * parsers={ 1066 * SerializerSet.Inherit.<jk>class</jk>, XmlParser.<jk>class</jk> 1067 * } 1068 * ) 1069 * <jk>public void</jk> doPost(MyBean <jv>bean</jv>) { 1070 * ... 1071 * } 1072 * } 1073 * </p> 1074 * 1075 * <p> 1076 * For programmatic equivalents, contribute a {@link SerializerSet} bean via 1077 * {@link Bean @Bean(name="serializers")} (use methodScope to scope to specific operation methods). 1078 * 1079 * <h4 class='section'>See Also:</h4><ul> 1080 * <li class='link'><a class="doclink" href="https://juneau.apache.org/docs/topics/Marshalling">Marshalling</a> 1081 * </ul> 1082 * 1083 * @return The annotation value. 1084 */ 1085 Class<? extends Serializer>[] serializers() default {}; 1086 1087 /** 1088 * Optional summary for the exposed API. 1089 * 1090 * <p> 1091 * This summary is used in the following locations: 1092 * <ul class='spaced-list'> 1093 * <li> 1094 * The value returned by {@link Operation#getSummary()} in the auto-generated swagger. 1095 * <li> 1096 * The <js>"${RS:operationSummary}"</js> variable. 1097 * <li> 1098 * The summary of the method in the Swagger page. 1099 * </ul> 1100 * 1101 * <h4 class='section'>Notes:</h4><ul> 1102 * <li class='note'> 1103 * Corresponds to the swagger field <c>/paths/{path}/{method}/summary</c>. 1104 * <li class='note'> 1105 * Supports <a class="doclink" href="https://juneau.apache.org/docs/topics/RestServerSvlVariables">REST Server SVL Variables</a> 1106 * (e.g. <js>"${L:my.localized.variable}"</js>). 1107 * </ul> 1108 * 1109 * @return The annotation value. 1110 */ 1111 String summary() default ""; 1112 1113 /** 1114 * Provides swagger-specific metadata on this method. 1115 * 1116 * <p> 1117 * Used to populate the auto-generated OPTIONS swagger documentation. 1118 * 1119 * <p> 1120 * The format of this annotation is JSON when all individual parts are concatenated. 1121 * <br>The starting and ending <js>'{'</js>/<js>'}'</js> characters around the entire value are optional. 1122 * 1123 * <h4 class='section'>Example:</h4> 1124 * <p class='bjava'> 1125 * <ja>@RestOp</ja>( 1126 * method=<jsf>PUT</jsf>, 1127 * path=<js>"/{propertyName}"</js>, 1128 * 1129 * <jc>// Swagger info.</jc> 1130 * swagger={ 1131 * <js>"parameters:["</js>, 1132 * <js>"{name:'propertyName',in:'path',description:'The system property name.'},"</js>, 1133 * <js>"{in:'body',description:'The new system property value.'}"</js>, 1134 * <js>"],"</js>, 1135 * <js>"responses:{"</js>, 1136 * <js>"302: {headers:{Location:{description:'The root URL of this resource.'}}},"</js>, 1137 * <js>"403: {description:'User is not an admin.'}"</js>, 1138 * <js>"}"</js> 1139 * } 1140 * ) 1141 * </p> 1142 * 1143 * <h4 class='section'>Notes:</h4><ul> 1144 * <li class='note'> 1145 * The format is <a class="doclink" href="https://juneau.apache.org/docs/topics/JuneauBeanSwagger2">juneau-bean-swagger-v2</a>. 1146 * <br>Multiple lines are concatenated with newlines. 1147 * <li class='note'> 1148 * The starting and ending <js>'{'</js>/<js>'}'</js> characters around the entire value are optional. 1149 * <li class='note'> 1150 * These values are superimposed on top of any Swagger JSON file present for the resource in the classpath. 1151 * <li class='note'> 1152 * Supports <a class="doclink" href="https://juneau.apache.org/docs/topics/RestServerSvlVariables">REST Server SVL Variables</a> 1153 * (e.g. <js>"${L:my.localized.variable}"</js>). 1154 * </ul> 1155 * 1156 * <h4 class='section'>See Also:</h4><ul> 1157 * <li class='ja'>{@link OpSwagger} 1158 * <li class='jc'>{@link SwaggerProvider} 1159 * </ul> 1160 * 1161 * @return The annotation value. 1162 */ 1163 OpSwagger swagger() default @OpSwagger; 1164 1165 /** 1166 * REST method name and path. 1167 * 1168 * <p> 1169 * Can be used to provide a shortened combined form for the {@link #method()} and {@link #path()} values. 1170 * 1171 * <p> 1172 * The following examples are considered equivalent. 1173 * <p class='bjava'> 1174 * <jc>// Normal form</jc> 1175 * <ja>@RestOp</ja>(method=<jsf>PUT</jsf>, path=<js>"/{propertyName}"</js>) 1176 * 1177 * <jc>// Shortened form</jc> 1178 * <ja>@RestOp</ja>(<js>"PUT /{propertyName}"</js>) 1179 * </p> 1180 * 1181 * <h4 class='section'>Notes:</h4><ul> 1182 * <li class='note'> 1183 * The path portion is optional. 1184 * </ul> 1185 * 1186 * @return The annotation value. 1187 */ 1188 String value() default ""; 1189}