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.marshall.encoders.*; 028import org.apache.juneau.marshall.parser.*; 029import org.apache.juneau.marshall.serializer.*; 030import org.apache.juneau.rest.server.converter.*; 031import org.apache.juneau.rest.server.guard.*; 032import org.apache.juneau.rest.server.matcher.*; 033import org.apache.juneau.rest.server.servlet.*; 034import org.apache.juneau.rest.server.swagger.*; 035 036/** 037 * Identifies a REST PATH operation Java method on a {@link RestServlet} implementation class. 038 * 039 * <p> 040 * This is a specialized subtype of <c><ja>{@link RestOp @RestOp}(method=<jsf>PATCH</jsf>)</c>. 041 * 042 * <h5 class='section'>See Also:</h5><ul> 043 * <li class='link'><a class="doclink" href="https://juneau.apache.org/docs/topics/RestOpAnnotatedMethods">@RestOp-Annotated Method</a> 044 045 * </ul> 046 */ 047@Target(METHOD) 048@Retention(RUNTIME) 049@Inherited 050@AnnotationGroup(RestOp.class) 051public @interface RestPatch { 052 053 /** 054 * Specifies whether this method can be called based on the client version. 055 * 056 * <p> 057 * The client version is identified via the HTTP request header identified by 058 * {@link Rest#clientVersionHeader() @Rest(clientVersionHeader)} which by default is <js>"Client-Version"</js>. 059 * 060 * <p> 061 * This is a specialized kind of {@link RestMatcher} that allows you to invoke different Java methods for the same 062 * method/path based on the client version. 063 * 064 * <p> 065 * The format of the client version range is similar to that of OSGi versions. 066 * 067 * <p> 068 * In the following example, the Java methods are mapped to the same HTTP method and URL <js>"/foobar"</js>. 069 * <p class='bjava'> 070 * <jc>// Call this method if Client-Version is at least 2.0. 071 * // Note that this also matches 2.0.1.</jc> 072 * <ja>@RestPatch</ja>(path=<js>"/foobar"</js>, clientVersion=<js>"2.0"</js>) 073 * <jk>public</jk> Object method1() {...} 074 * 075 * <jc>// Call this method if Client-Version is at least 1.1, but less than 2.0.</jc> 076 * <ja>@RestPatch</ja>(path=<js>"/foobar"</js>, clientVersion=<js>"[1.1,2.0)"</js>) 077 * <jk>public</jk> Object method2() {...} 078 * 079 * <jc>// Call this method if Client-Version is less than 1.1.</jc> 080 * <ja>@RestPatch</ja>(path=<js>"/foobar"</js>, clientVersion=<js>"[0,1.1)"</js>) 081 * <jk>public</jk> Object method3() {...} 082 * </p> 083 * 084 * <p> 085 * It's common to combine the client version with transforms that will convert new POJOs into older POJOs for 086 * backwards compatibility. 087 * <p class='bjava'> 088 * <jc>// Call this method if Client-Version is at least 2.0.</jc> 089 * <ja>@RestPatch</ja>(path=<js>"/foobar"</js>, clientVersion=<js>"2.0"</js>) 090 * <jk>public</jk> NewPojo newMethod() {...} 091 * 092 * <jc>// Call this method if X-Client-Version is at least 1.1, but less than 2.0.</jc> 093 * <ja>@RestPatch</ja>(path=<js>"/foobar"</js>, clientVersion=<js>"[1.1,2.0)"</js>) 094 * <ja>@MarshalledConfig</ja>(swaps=NewToOldSwap.<jk>class</jk>) 095 * <jk>public</jk> NewPojo oldMethod() { 096 * <jk>return</jk> newMethod(); 097 * } 098 * 099 * <p> 100 * Note that in the previous example, we're returning the exact same POJO, but using a transform to convert it into 101 * an older form. 102 * The old method could also just return back a completely different object. 103 * The range can be any of the following: 104 * <ul> 105 * <li><js>"[0,1.0)"</js> = Less than 1.0. 1.0 and 1.0.0 does not match. 106 * <li><js>"[0,1.0]"</js> = Less than or equal to 1.0. Note that 1.0.1 will match. 107 * <li><js>"1.0"</js> = At least 1.0. 1.0 and 2.0 will match. 108 * </ul> 109 * 110 * 111 * @return The annotation value. 112 */ 113 String clientVersion() default ""; 114 115 /** 116 * Supported content media types. 117 * 118 * <p> 119 * Overrides the media types inferred from the parsers that identify what media types can be consumed by the resource. 120 * 121 * <h5 class='section'>Notes:</h5><ul> 122 * <li class='note'> 123 * Supports <a class="doclink" href="https://juneau.apache.org/docs/topics/RestServerSvlVariables">REST Server SVL Variables</a> 124 * (e.g. <js>"$S{mySystemProperty}"</js>). 125 * </ul> 126 * 127 * <h5 class='section'>See Also:</h5><ul> 128 * <li class='jm'>{@link RestOpContext#getSupportedContentTypes()} 129 * </ul> 130 * 131 * @return The annotation value. 132 */ 133 String[] consumes() default {}; 134 135 /** 136 * Class-level response converters. 137 * 138 * <p> 139 * Associates one or more {@link RestConverter converters} with this method. 140 * 141 * 142 * @return The annotation value. 143 */ 144 Class<? extends RestConverter>[] converters() default {}; 145 146 /** 147 * Default <c>Accept</c> header. 148 * 149 * <p> 150 * The default value for the <c>Accept</c> header if not specified on a request. 151 * 152 * <p> 153 * This is a shortcut for using {@link #defaultRequestHeaders()} for just this specific header. 154 * 155 * @return The annotation value. 156 */ 157 String defaultAccept() default ""; 158 159 /** 160 * Default character encoding. 161 * 162 * <p> 163 * The default character encoding for the request and response if not specified on the request. 164 * 165 * <h5 class='section'>Notes:</h5><ul> 166 * <li class='note'> 167 * Supports <a class="doclink" href="https://juneau.apache.org/docs/topics/RestServerSvlVariables">REST Server SVL Variables</a> 168 * (e.g. <js>"$S{mySystemProperty}"</js>). 169 * </ul> 170 * 171 * <h5 class='section'>See Also:</h5><ul> 172 * <li class='ja'>{@link Rest#defaultCharset} 173 * </ul> 174 * 175 * @return The annotation value. 176 */ 177 String defaultCharset() default ""; 178 179 /** 180 * Default <c>Content-Type</c> header. 181 * 182 * <p> 183 * The default value for the <c>Content-Type</c> header if not specified on a request. 184 * 185 * <p> 186 * This is a shortcut for using {@link #defaultRequestHeaders()} for just this specific header. 187 * 188 * @return The annotation value. 189 */ 190 String defaultContentType() default ""; 191 192 /** 193 * Default request attributes. 194 * 195 * <p> 196 * Specifies default values for request attributes if they're not already set on the request. 197 * 198 * <p> 199 * Affects values returned by the following methods: 200 * <ul> 201 * <li class='jm'>{@link RestRequest#getAttribute(String)}. 202 * <li class='jm'>{@link RestRequest#getAttributes()}. 203 * </ul> 204 * 205 * <h5 class='section'>Example:</h5> 206 * <p class='bjava'> 207 * <jc>// Defined via annotation resolving to a config file setting with default value.</jc> 208 * <ja>@Rest</ja>(defaultRequestAttributes={<js>"Foo=bar"</js>, <js>"Baz: $C{REST/myAttributeValue}"</js>}) 209 * <jk>public class</jk> MyResource { 210 * 211 * <jc>// Override at the method level.</jc> 212 * <ja>@RestGet</ja>(defaultRequestAttributes={<js>"Foo: bar"</js>}) 213 * <jk>public</jk> Object myMethod() {...} 214 * } 215 * </p> 216 * 217 * </ul> 218 * <h5 class='section'>Notes:</h5><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 * <h5 class='section'>See Also:</h5><ul> * <li class='ja'>{@link Rest#defaultRequestAttributes()} 225 * </ul> 226 * 227 * @return The annotation value. 228 */ 229 String[] defaultRequestAttributes() default {}; 230 231 /** 232 * Specifies default values for form-data parameters. 233 * 234 * <p> 235 * Strings are of the format <js>"name=value"</js>. 236 * 237 * <p> 238 * Affects values returned by {@link RestRequest#getFormParam(String)} when the parameter is not present on the 239 * request. 240 * 241 * <h5 class='section'>Example:</h5> 242 * <p class='bjava'> 243 * <ja>@RestPatch</ja>(path=<js>"/*"</js>, defaultRequestFormData={<js>"foo=bar"</js>}) 244 * <jk>public</jk> String doGet(<ja>@FormData</ja>(<js>"foo"</js>) String <jv>foo</jv>) {...} 245 * </p> 246 * 247 * <h5 class='section'>Notes:</h5><ul> 248 * <li class='note'> 249 * You can use either <js>':'</js> or <js>'='</js> as the key/value delimiter. 250 * <li class='note'> 251 * Key and value is trimmed of whitespace. 252 * <li class='note'> 253 * Supports <a class="doclink" href="https://juneau.apache.org/docs/topics/RestServerSvlVariables">REST Server SVL Variables</a> 254 * (e.g. <js>"$S{mySystemProperty}"</js>). 255 * </ul> 256 * 257 * @return The annotation value. 258 */ 259 String[] defaultRequestFormData() default {}; 260 261 /** 262 * Default request headers. 263 * 264 * <p> 265 * Specifies default values for request headers if they're not passed in through the request. 266 * 267 * <h5 class='section'>Example:</h5> 268 * <p class='bjava'> 269 * <jc>// Assume "text/json" Accept value when Accept not specified</jc> 270 * <ja>@RestPatch</ja>(path=<js>"/*"</js>, defaultRequestHeaders={<js>"Accept: text/json"</js>}) 271 * <jk>public</jk> String doPost() {...} 272 * </p> 273 * 274 * <h5 class='section'>Notes:</h5><ul> 275 * <li class='note'> 276 * Supports <a class="doclink" href="https://juneau.apache.org/docs/topics/RestServerSvlVariables">REST Server SVL Variables</a> 277 * (e.g. <js>"$S{mySystemProperty}"</js>). 278 * </ul> 279 * 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 * <h5 class='section'>Example:</h5> 295 * <p class='bjava'> 296 * <ja>@RestPatch</ja>(path=<js>"/*"</js>, defaultRequestQueryData={<js>"foo=bar"</js>}) 297 * <jk>public</jk> String doPost(<ja>@Query</ja>(<js>"foo"</js>) String <jv>foo</jv>) {...} 298 * </p> 299 * 300 * <h5 class='section'>Notes:</h5><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 * <h5 class='section'>Example:</h5> 321 * <p class='bjava'> 322 * <jc>// Assume "text/json" Accept value when Accept not specified</jc> 323 * <ja>@RestPatch</ja>(path=<js>"/*"</js>, defaultResponseHeaders={<js>"Content-Type: text/json"</js>}) 324 * <jk>public</jk> String doPost() {...} 325 * </p> 326 * 327 * <h5 class='section'>Notes:</h5><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 * 334 * @return The annotation value. 335 */ 336 String[] defaultResponseHeaders() default {}; 337 338 /** 339 * Optional description for the exposed API. 340 * 341 * <p> 342 * This description is used in the following locations: 343 * <ul class='spaced-list'> 344 * <li> 345 * The value returned by {@link Operation#getDescription()} in the auto-generated swagger. 346 * <li> 347 * The <js>"$RS{operationDescription}"</js> variable. 348 * <li> 349 * The description of the method in the Swagger page. 350 * </ul> 351 * 352 * <h5 class='section'>Notes:</h5><ul> 353 * <li class='note'> 354 * Corresponds to the swagger field <c>/paths/{path}/{method}/description</c>. 355 * <li class='note'> 356 * Supports <a class="doclink" href="https://juneau.apache.org/docs/topics/RestServerSvlVariables">REST Server SVL Variables</a> 357 * (e.g. <js>"$L{my.localized.variable}"</js>). 358 * </ul> 359 * 360 * @return The annotation value. 361 */ 362 String[] description() default {}; 363 364 /** 365 * Specifies the compression encoders for this method. 366 * 367 * <p> 368 * Encoders are used to enable various kinds of compression (e.g. <js>"gzip"</js>) on requests and responses. 369 * 370 * <p> 371 * This value overrides encoders specified at the class level using {@link Rest#encoders()}. 372 * The {@link org.apache.juneau.marshall.encoders.EncoderSet.Inherit EncoderSet.Inherit} class can be used to include values from the parent class. 373 * 374 * <h5 class='section'>Example:</h5> 375 * <p class='bjava'> 376 * <jc>// Define a REST resource that handles GZIP compression.</jc> 377 * <ja>@Rest</ja>( 378 * encoders={ 379 * GzipEncoder.<jk>class</jk> 380 * } 381 * ) 382 * <jk>public class</jk> MyResource { 383 * 384 * <jc>// Define a REST method that can also use a custom encoder.</jc> 385 * <ja>@RestPatch</ja>( 386 * encoders={ 387 * EncoderSet.Inherit.<jk>class</jk>, MyEncoder.<jk>class</jk> 388 * } 389 * ) 390 * <jk>public void</jk> doPost(MyBean <jv>bean</jv>) { 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 * <h5 class='section'>See Also:</h5><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 * 415 * @return The annotation value. 416 */ 417 Class<? extends RestGuard>[] guards() default {}; 418 419 /** 420 * Method matchers. 421 * 422 * <p> 423 * Associates one more more {@link RestMatcher RestMatchers} with this method. 424 * 425 * <p> 426 * Matchers are used to allow multiple Java methods to handle requests assigned to the same URL path pattern, but 427 * differing based on some request attribute, such as a specific header value. 428 * 429 * <h5 class='section'>See Also:</h5><ul> 430 * <li class='jac'>{@link RestMatcher} 431 * </ul> 432 * 433 * @return The annotation value. 434 */ 435 Class<? extends RestMatcher>[] matchers() default {}; 436 437 /** 438 * The maximum allowed input size (in bytes) on HTTP requests. 439 * 440 * <p> 441 * Useful for alleviating DoS attacks by throwing an exception when too much input is received instead of resulting 442 * in out-of-memory errors which could affect system stability. 443 * 444 * <h5 class='section'>Example:</h5> 445 * <p class='bjava'> 446 * <ja>@RestPatch</ja>( 447 * maxInput=<js>"100M"</js> 448 * ) 449 * </p> 450 * 451 * <h5 class='section'>Notes:</h5><ul> 452 * <li class='note'> 453 * Supports <a class="doclink" href="https://juneau.apache.org/docs/topics/RestServerSvlVariables">REST Server SVL Variables</a> 454 * (e.g. <js>"$S{mySystemProperty}"</js>). 455 * </ul> 456 * 457 * <h5 class='section'>See Also:</h5><ul> 458 * <li class='ja'>{@link Rest#maxInput} 459 * </ul> 460 * 461 * @return The annotation value. 462 */ 463 String maxInput() default ""; 464 465 /** 466 * Specifies the parsers for converting HTTP request bodies into POJOs for this method. 467 * 468 * <p> 469 * Parsers are used to convert the content of HTTP requests into POJOs. 470 * <br>Any of the Juneau framework parsers can be used in this setting. 471 * <br>The parser selected is based on the request <c>Content-Type</c> header matched against the values returned by the following method 472 * using a best-match algorithm: 473 * <ul class='javatree'> 474 * <li class='jm'>{@link Parser#getMediaTypes()} 475 * </ul> 476 * 477 * <p> 478 * This value overrides parsers specified at the class level using {@link Rest#parsers()}. 479 * The {@link org.apache.juneau.marshall.parser.ParserSet.Inherit ParserSet.Inherit} class can be used to include values from the parent class. 480 * 481 * <h5 class='section'>Example:</h5> 482 * <p class='bjava'> 483 * <jc>// Define a REST resource that can consume JSON and HTML.</jc> 484 * <ja>@Rest</ja>( 485 * parsers={ 486 * JsonParser.<jk>class</jk>, 487 * HtmlParser.<jk>class</jk> 488 * } 489 * ) 490 * <jk>public class</jk> MyResource { 491 * 492 * <jc>// Define a REST method that can also consume XML.</jc> 493 * <ja>@RestPatch</ja>( 494 * parsers={ 495 * ParserSet.Inherit.<jk>class</jk>, XmlParser.<jk>class</jk> 496 * } 497 * ) 498 * <jk>public void</jk> doPost(MyBean <jv>bean</jv>) { 499 * ... 500 * } 501 * } 502 * </p> 503 * 504 * <p> 505 * For programmatic equivalents, contribute a {@link ParserSet} bean via 506 * {@link Bean @Bean(name="parsers")} (use methodScope to scope to specific operation methods). 507 * 508 * <h5 class='section'>See Also:</h5><ul> 509 * <li class='link'><a class="doclink" href="https://juneau.apache.org/docs/topics/Marshalling">Marshalling</a> 510 * </ul> 511 * 512 * @return The annotation value. 513 */ 514 Class<?>[] parsers() default {}; 515 516 /** 517 * Optional path pattern for the specified method. 518 * 519 * <p> 520 * Appending <js>"/*"</js> to the end of the path pattern will make it match any remainder too. 521 * <br>Not appending <js>"/*"</js> to the end of the pattern will cause a 404 (Not found) error to occur if the exact 522 * pattern is not found. 523 * 524 * <p> 525 * The path can contain variables that get resolved to {@link org.apache.juneau.http.Path @Path} parameters. 526 * 527 * <h5 class='figure'>Examples:</h5> 528 * <p class='bjava'> 529 * <ja>@RestPatch</ja>(path=<js>"/myurl/{foo}/{bar}/{baz}/*"</js>) 530 * </p> 531 * <p class='bjava'> 532 * <ja>@RestPatch</ja>(path=<js>"/myurl/{0}/{1}/{2}/*"</js>) 533 * </p> 534 * 535 * <p> 536 * If you do not specify a path name, then the path name is inferred from the Java method name. 537 * 538 * <h5 class='figure'>Example:</h5> 539 * <p class='bjava'> 540 * <jc>// Path is assumed to be "/foo".</jc> 541 * <ja>@RestPatch</ja> 542 * <jk>public void</jk> foo() {...} 543 * </p> 544 * 545 * <p> 546 * Note that you can also use {@link #value()} to specify the path. 547 * 548 * <h5 class='section'>See Also:</h5><ul> 549 * <li class='ja'>{@link org.apache.juneau.http.Path} 550 * </ul> 551 * 552 * @return The annotation value. 553 */ 554 String[] path() default {}; 555 556 /** 557 * Per-operation override for {@link Rest#problemDetails() @Rest(problemDetails)}. 558 * 559 * <p> 560 * When set on a {@code @RestPatch} method, this value takes precedence over the resource-level 561 * {@code @Rest(problemDetails)} attribute for this operation. Tri-state semantics: 562 * 563 * <ul class='values'> 564 * <li><js>"true"</js> — enable problem-details responses for this operation. 565 * <li><js>"false"</js> — disable problem-details responses for this operation (overrides an 566 * opted-in resource). 567 * <li><js>""</js> (default) — inherit from {@link Rest#problemDetails()}. 568 * </ul> 569 * 570 * <h5 class='section'>Notes:</h5><ul> 571 * <li class='note'> 572 * Supports <a class="doclink" href="https://juneau.apache.org/docs/topics/RestServerSvlVariables">REST Server SVL Variables</a> 573 * (e.g. <js>"$L{my.localized.variable}"</js>). 574 * </ul> 575 * 576 * <h5 class='section'>See Also:</h5><ul> 577 * <li class='ja'>{@link Rest#problemDetails()} 578 * </ul> 579 * 580 * @return The annotation value. 581 */ 582 String problemDetails() default ""; 583 584 /** 585 * Per-operation override for {@link Rest#debugMarshalling() @Rest(debugMarshalling)}. 586 * 587 * <p> 588 * When set on a {@code @RestPatch} method, this value takes precedence over the resource-level 589 * {@code @Rest(debugMarshalling)} attribute for this operation. Tri-state semantics: 590 * 591 * <ul class='values'> 592 * <li><js>"true"</js> — enable marshalling debug for this operation. 593 * <li><js>"false"</js> — disable marshalling debug for this operation (overrides an opted-in resource). 594 * <li><js>""</js> (default) — inherit from {@link Rest#debugMarshalling()}. 595 * </ul> 596 * 597 * <h5 class='section'>See Also:</h5><ul> 598 * <li class='ja'>{@link Rest#debugMarshalling()} 599 * </ul> 600 * 601 * @return The annotation value. 602 */ 603 String debugMarshalling() default ""; 604 605 /** 606 * Per-operation observability opt-in / opt-out control. 607 * 608 * <p> 609 * Overrides the resource-level {@link Rest#observability()} setting for this specific operation. 610 * 611 * <ul class='values'> 612 * <li><js>"true"</js> — strict opt-in; requires a wired observability backend. 613 * <li><js>"false"</js> — explicit opt-out; short-circuits the observability block. 614 * <li><js>""</js> (default) — inherits the resource-level setting. 615 * </ul> 616 * 617 * <h5 class='section'>See Also:</h5><ul> 618 * <li class='ja'>{@link RestOp#observability()} 619 * </ul> 620 * 621 * @return The annotation value. 622 * @since 10.0.0 623 */ 624 String observability() default ""; 625 626 /** 627 * Per-operation override for {@link Rest#asyncCompletionExecutor() @Rest(asyncCompletionExecutor)}. 628 * 629 * <p> 630 * Names the {@link java.util.concurrent.Executor} bean used to route completion callbacks for this 631 * specific operation through a dedicated thread pool. Empty string (default) inherits from 632 * {@link Rest#asyncCompletionExecutor()}. 633 * 634 * <h5 class='section'>See Also:</h5><ul> 635 * <li class='ja'>{@link RestOp#asyncCompletionExecutor()} 636 * <li class='ja'>{@link Rest#asyncCompletionExecutor()} 637 * </ul> 638 * 639 * @return The annotation value. 640 * @since 10.0.0 641 */ 642 String asyncCompletionExecutor() default ""; 643 644 /** 645 * Per-operation metric name override. Empty string (default) uses the recorder's own name derivation. 646 * 647 * <h5 class='section'>See Also:</h5><ul> 648 * <li class='ja'>{@link RestOp#metricName()} 649 * </ul> 650 * 651 * @return The annotation value. 652 * @since 10.0.0 653 */ 654 String metricName() default ""; 655 656 /** 657 * Per-operation metric tags. Format: comma-separated {@code key=value} pairs. 658 * Empty string (default) means no additional tags. 659 * 660 * <h5 class='section'>See Also:</h5><ul> 661 * <li class='ja'>{@link RestOp#metricTags()} 662 * </ul> 663 * 664 * @return The annotation value. 665 * @since 10.0.0 666 */ 667 String metricTags() default ""; 668 669 /** 670 * Supported accept media types. 671 * 672 * <p> 673 * Overrides the media types inferred from the serializers that identify what media types can be produced by the resource. 674 * 675 * <h5 class='section'>Notes:</h5><ul> 676 * <li class='note'> 677 * Supports <a class="doclink" href="https://juneau.apache.org/docs/topics/RestServerSvlVariables">REST Server SVL Variables</a> 678 * (e.g. <js>"$S{mySystemProperty}"</js>). 679 * </ul> 680 * 681 * <h5 class='section'>See Also:</h5><ul> 682 * <li class='jm'>{@link RestOpContext#getSupportedAcceptTypes()} 683 * </ul> 684 * 685 * @return The annotation value. 686 */ 687 String[] produces() default {}; 688 689 /** 690 * Allowed serializer session option keys for this operation (ordered merge, prefix {@code -key} removes a key). 691 * 692 * <p> 693 * Comma-delimited list of session property keys that clients may send via the <js>"X-Juneau-Serializer-Options"</js> 694 * header or <js>"juneauSerializerOptions"</js> query parameter. 695 * Merged on top of resource-level {@link Rest#allowedSerializerOptions()} values. 696 * Use {@link #noInherit()} to replace rather than extend the resource-level list. 697 * 698 * <h5 class='section'>See Also:</h5><ul> 699 * <li class='link'><a class="doclink" href="https://juneau.apache.org/docs/topics/SessionOptions#safe-properties">Safe Properties</a> 700 * </ul> 701 * 702 * @return The annotation value. 703 */ 704 String[] allowedSerializerOptions() default {}; 705 706 /** 707 * Allowed parser session option keys for this operation (ordered merge, prefix {@code -key} removes a key). 708 * 709 * <p> 710 * Comma-delimited list of session property keys that clients may send via the <js>"X-Juneau-Parser-Options"</js> 711 * header or <js>"juneauParserOptions"</js> query parameter. 712 * Merged on top of resource-level {@link Rest#allowedParserOptions()} values. 713 * Use {@link #noInherit()} to replace rather than extend the resource-level list. 714 * 715 * <h5 class='section'>See Also:</h5><ul> 716 * <li class='link'><a class="doclink" href="https://juneau.apache.org/docs/topics/SessionOptions#safe-properties">Safe Properties</a> 717 * </ul> 718 * 719 * @return The annotation value. 720 */ 721 String[] allowedParserOptions() default {}; 722 723 /** 724 * Property names for which less-derived contributions are NOT inherited. 725 * 726 * <p> 727 * Accepted values: {@code "allowedSerializerOptions"}, {@code "allowedParserOptions"}, 728 * {@code "problemDetails"}, {@code "debugMarshalling"}. 729 * Prevents the named property from inheriting values from the enclosing {@code @Rest} annotation. 730 * The {@code noInherit} attribute itself is never inherited. 731 * 732 * <h5 class='section'>See Also:</h5><ul> 733 * <li class='link'><a class="doclink" href="https://juneau.apache.org/docs/topics/SessionOptions">Session Options via HTTP</a> 734 * </ul> 735 * 736 * @return The annotation value. 737 */ 738 String[] noInherit() default {}; 739 740 /** 741 * Role guard. 742 * 743 * <p> 744 * An expression defining if a user with the specified roles are allowed to access this method. 745 * 746 * <h5 class='section'>Example:</h5> 747 * <p class='bjava'> 748 * <jk>public class</jk> MyResource <jk>extends</jk> BasicRestServlet { 749 * 750 * <ja>@RestPatch</ja>( 751 * path=<js>"/foo"</js>, 752 * roleGuard=<js>"ROLE_ADMIN || (ROLE_READ_WRITE && ROLE_SPECIAL)"</js> 753 * ) 754 * <jk>public</jk> Object doPost() { 755 * } 756 * } 757 * </p> 758 * 759 * <h5 class='section'>Notes:</h5><ul> 760 * <li class='note'> 761 * Supports any of the following expression constructs: 762 * <ul> 763 * <li><js>"foo"</js> - Single arguments. 764 * <li><js>"foo,bar,baz"</js> - Multiple OR'ed arguments. 765 * <li><js>"foo | bar | baz"</js> - Multiple OR'ed arguments, pipe syntax. 766 * <li><js>"foo || bar || baz"</js> - Multiple OR'ed arguments, Java-OR syntax. 767 * <li><js>"fo*"</js> - Patterns including <js>'*'</js> and <js>'?'</js>. 768 * <li><js>"fo* & *oo"</js> - Multiple AND'ed arguments, ampersand syntax. 769 * <li><js>"fo* && *oo"</js> - Multiple AND'ed arguments, Java-AND syntax. 770 * <li><js>"fo* || (*oo || bar)"</js> - Parenthesis. 771 * </ul> 772 * <li class='note'> 773 * AND operations take precedence over OR operations (as expected). 774 * <li class='note'> 775 * Whitespace is ignored. 776 * <li class='note'> 777 * <jk>null</jk> or empty expressions always match as <jk>false</jk>. 778 * <li class='note'> 779 * If patterns are used, you must specify the list of declared roles using {@link #rolesDeclared()}. 780 * <li class='note'> 781 * Supports <a class="doclink" href="https://juneau.apache.org/docs/topics/RestServerSvlVariables">REST Server SVL Variables</a> 782 * (e.g. <js>"$L{my.localized.variable}"</js>). 783 * <li class='note'> 784 * When defined on parent/child classes and methods, ALL guards within the hierarchy must pass. 785 * </ul> 786 * 787 * 788 * @return The annotation value. 789 */ 790 String roleGuard() default ""; 791 792 /** 793 * Declared roles. 794 * 795 * <p> 796 * A comma-delimited list of all possible user roles. 797 * 798 * <p> 799 * Used in conjunction with {@link #roleGuard()} is used with patterns. 800 * 801 * <h5 class='section'>Example:</h5> 802 * <p class='bjava'> 803 * <jk>public class</jk> MyResource <jk>extends</jk> BasicRestServlet { 804 * 805 * <ja>@RestPatch</ja>( 806 * path=<js>"/foo"</js>, 807 * rolesDeclared=<js>"ROLE_ADMIN,ROLE_READ_WRITE,ROLE_READ_ONLY,ROLE_SPECIAL"</js>, 808 * roleGuard=<js>"ROLE_ADMIN || (ROLE_READ_WRITE && ROLE_SPECIAL)"</js> 809 * ) 810 * <jk>public</jk> Object doPost() { 811 * } 812 * } 813 * </p> 814 * 815 * 816 * @return The annotation value. 817 */ 818 String rolesDeclared() default ""; 819 820 /** 821 * Specifies the serializers for marshalling POJOs into response bodies for this method. 822 * 823 * <p> 824 * Serializer are used to convert POJOs to HTTP response bodies. 825 * <br>Any of the Juneau framework serializers can be used in this setting. 826 * <br>The serializer selected is based on the request <c>Accept</c> header matched against the values returned by the following method 827 * using a best-match algorithm: 828 * <ul class='javatree'> 829 * <li class='jm'>{@link Serializer#getMediaTypeRanges()} 830 * </ul> 831 * 832 * <p> 833 * This value overrides serializers specified at the class level using {@link Rest#serializers()}. 834 * The {@link org.apache.juneau.marshall.serializer.SerializerSet.Inherit SerializerSet.Inherit} class can be used to include values from the parent class. 835 * 836 * <h5 class='section'>Example:</h5> 837 * <p class='bjava'> 838 * <jc>// Define a REST resource that can produce JSON and HTML.</jc> 839 * <ja>@Rest</ja>( 840 * serializers={ 841 * JsonParser.<jk>class</jk>, 842 * HtmlParser.<jk>class</jk> 843 * } 844 * ) 845 * <jk>public class</jk> MyResource { 846 * 847 * <jc>// Define a REST method that can also produce XML.</jc> 848 * <ja>@RestPatch</ja>( 849 * parsers={ 850 * SerializerSet.Inherit.<jk>class</jk>, XmlParser.<jk>class</jk> 851 * } 852 * ) 853 * <jk>public</jk> MyBean doPost() { 854 * ... 855 * } 856 * } 857 * </p> 858 * 859 * <p> 860 * For programmatic equivalents, contribute a {@link SerializerSet} bean via 861 * {@link Bean @Bean(name="serializers")} (use methodScope to scope to specific operation methods). 862 * 863 * <h5 class='section'>See Also:</h5><ul> 864 * <li class='link'><a class="doclink" href="https://juneau.apache.org/docs/topics/Marshalling">Marshalling</a> 865 * </ul> 866 * 867 * @return The annotation value. 868 */ 869 Class<? extends Serializer>[] serializers() default {}; 870 871 /** 872 * Optional summary for the exposed API. 873 * 874 * <p> 875 * This summary is used in the following locations: 876 * <ul class='spaced-list'> 877 * <li> 878 * The value returned by {@link Operation#getSummary()} in the auto-generated swagger. 879 * <li> 880 * The <js>"$RS{operationSummary}"</js> variable. 881 * <li> 882 * The summary of the method in the Swagger page. 883 * </ul> 884 * 885 * <h5 class='section'>Notes:</h5><ul> 886 * <li class='note'> 887 * Corresponds to the swagger field <c>/paths/{path}/{method}/summary</c>. 888 * <li class='note'> 889 * Supports <a class="doclink" href="https://juneau.apache.org/docs/topics/RestServerSvlVariables">REST Server SVL Variables</a> 890 * (e.g. <js>"$L{my.localized.variable}"</js>). 891 * </ul> 892 * 893 * @return The annotation value. 894 */ 895 String summary() default ""; 896 897 /** 898 * Provides swagger-specific metadata on this method. 899 * 900 * <p> 901 * Used to populate the auto-generated OPTIONS swagger documentation. 902 * 903 * <p> 904 * The format of this annotation is JSON when all individual parts are concatenated. 905 * <br>The starting and ending <js>'{'</js>/<js>'}'</js> characters around the entire value are optional. 906 * 907 * <h5 class='section'>Example:</h5> 908 * <p class='bjava'> 909 * <ja>@RestPatch</ja>( 910 * path=<js>"/{propertyName}"</js>, 911 * 912 * <jc>// Swagger info.</jc> 913 * swagger={ 914 * <js>"parameters:["</js>, 915 * <js>"{name:'propertyName',in:'path',description:'The system property name.'},"</js>, 916 * <js>"{in:'body',description:'The new system property value.'}"</js>, 917 * <js>"],"</js>, 918 * <js>"responses:{"</js>, 919 * <js>"302: {headers:{Location:{description:'The root URL of this resource.'}}},"</js>, 920 * <js>"403: {description:'User is not an admin.'}"</js>, 921 * <js>"}"</js> 922 * } 923 * ) 924 * </p> 925 * 926 * <h5 class='section'>Notes:</h5><ul> 927 * <li class='note'> 928 * The format is <a class="doclink" href="https://juneau.apache.org/docs/topics/JuneauBeanSwagger2">juneau-bean-swagger-v2</a>. 929 * <br>Multiple lines are concatenated with newlines. 930 * <li class='note'> 931 * The starting and ending <js>'{'</js>/<js>'}'</js> characters around the entire value are optional. 932 * <li class='note'> 933 * These values are superimposed on top of any Swagger JSON file present for the resource in the classpath. 934 * <li class='note'> 935 * Supports <a class="doclink" href="https://juneau.apache.org/docs/topics/RestServerSvlVariables">REST Server SVL Variables</a> 936 * (e.g. <js>"$L{my.localized.variable}"</js>). 937 * </ul> 938 * 939 * <h5 class='section'>See Also:</h5><ul> 940 * <li class='ja'>{@link OpSwagger} 941 * <li class='jc'>{@link SwaggerProvider} 942 * </ul> 943 * 944 * @return The annotation value. 945 */ 946 OpSwagger swagger() default @OpSwagger; 947 948 /** 949 * REST method path. 950 * 951 * <p> 952 * Can be used to provide a shortened form for the {@link #path()} value. 953 * 954 * <p> 955 * The following examples are considered equivalent. 956 * <p class='bjava'> 957 * <jc>// Normal form</jc> 958 * <ja>@RestPatch</ja>(path=<js>"/{propertyName}"</js>) 959 * 960 * <jc>// Shortened form</jc> 961 * <ja>@RestPatch</ja>(<js>"/{propertyName}"</js>) 962 * </p> 963 * 964 * @return The annotation value. 965 */ 966 String value() default ""; 967}