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.marshall.encoders.*; 027import org.apache.juneau.marshall.parser.*; 028import org.apache.juneau.marshall.serializer.*; 029import org.apache.juneau.rest.server.converter.*; 030import org.apache.juneau.rest.server.guard.*; 031import org.apache.juneau.rest.server.matcher.*; 032import org.apache.juneau.rest.server.servlet.*; 033import org.apache.juneau.rest.server.swagger.*; 034 035/** 036 * Identifies a REST PUT operation Java method on a {@link RestServlet} implementation class. 037 * 038 * <p> 039 * This is a specialized subtype of <c><ja>{@link RestOp @RestOp}(method=<jsf>PUT</jsf>)</c>. 040 * 041 * <h5 class='section'>See Also:</h5><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 RestPut { 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>@RestPut</ja>(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>@RestPut</ja>(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>@RestPut</ja>(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>@RestPut</ja>(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>@RestPut</ja>(path=<js>"/foobar"</js>, clientVersion=<js>"[1.1,2.0)"</js>) 093 * <ja>@MarshalledConfig</ja>(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 * 110 * @return The annotation value. 111 */ 112 String clientVersion() default ""; 113 114 /** 115 * Supported content media types. 116 * 117 * <p> 118 * Overrides the media types inferred from the parsers that identify what media types can be consumed by the resource. 119 * 120 * <h5 class='section'>Notes:</h5><ul> 121 * <li class='note'> 122 * Supports <a class="doclink" href="https://juneau.apache.org/docs/topics/RestServerSvlVariables">REST Server SVL Variables</a> 123 * (e.g. <js>"$S{mySystemProperty}"</js>). 124 * </ul> 125 * 126 * <h5 class='section'>See Also:</h5><ul> 127 * <li class='jm'>{@link RestOpContext#getSupportedContentTypes()} 128 * </ul> 129 * 130 * @return The annotation value. 131 */ 132 String[] consumes() default {}; 133 134 /** 135 * Class-level response converters. 136 * 137 * <p> 138 * Associates one or more {@link RestConverter converters} with this method. 139 * 140 * 141 * @return The annotation value. 142 */ 143 Class<? extends RestConverter>[] converters() default {}; 144 145 /** 146 * Default <c>Accept</c> header. 147 * 148 * <p> 149 * The default value for the <c>Accept</c> header if not specified on a request. 150 * 151 * <p> 152 * This is a shortcut for using {@link #defaultRequestHeaders()} for just this specific header. 153 * 154 * @return The annotation value. 155 */ 156 String defaultAccept() default ""; 157 158 /** 159 * Default character encoding. 160 * 161 * <p> 162 * The default character encoding for the request and response if not specified on the request. 163 * 164 * <h5 class='section'>Notes:</h5><ul> 165 * <li class='note'> 166 * Supports <a class="doclink" href="https://juneau.apache.org/docs/topics/RestServerSvlVariables">REST Server SVL Variables</a> 167 * (e.g. <js>"$S{mySystemProperty}"</js>). 168 * </ul> 169 * 170 * <h5 class='section'>See Also:</h5><ul> 171 * <li class='ja'>{@link Rest#defaultCharset} 172 * </ul> 173 * 174 * @return The annotation value. 175 */ 176 String defaultCharset() default ""; 177 178 /** 179 * Default <c>Content-Type</c> header. 180 * 181 * <p> 182 * The default value for the <c>Content-Type</c> header if not specified on a request. 183 * 184 * <p> 185 * This is a shortcut for using {@link #defaultRequestHeaders()} for just this specific header. 186 * 187 * @return The annotation value. 188 */ 189 String defaultContentType() default ""; 190 191 /** 192 * Default request attributes. 193 * 194 * <p> 195 * Specifies default values for request attributes if they're not already set on the request. 196 * 197 * <p> 198 * Affects values returned by the following methods: 199 * <ul> 200 * <li class='jm'>{@link RestRequest#getAttribute(String)}. 201 * <li class='jm'>{@link RestRequest#getAttributes()}. 202 * </ul> 203 * 204 * <h5 class='section'>Example:</h5> 205 * <p class='bjava'> 206 * <jc>// Defined via annotation resolving to a config file setting with default value.</jc> 207 * <ja>@Rest</ja>(defaultRequestAttributes={<js>"Foo=bar"</js>, <js>"Baz: $C{REST/myAttributeValue}"</js>}) 208 * <jk>public class</jk> MyResource { 209 * 210 * <jc>// Override at the method level.</jc> 211 * <ja>@RestGet</ja>(defaultRequestAttributes={<js>"Foo: bar"</js>}) 212 * <jk>public</jk> Object myMethod() {...} 213 * } 214 * </p> 215 * 216 * </ul> 217 * <h5 class='section'>Notes:</h5><ul> 218 * <li class='note'> 219 * Supports <a class="doclink" href="https://juneau.apache.org/docs/topics/RestServerSvlVariables">REST Server SVL Variables</a> 220 * (e.g. <js>"$L{my.localized.variable}"</js>). 221 * </ul> 222 * 223 * <h5 class='section'>See Also:</h5><ul> * <li class='ja'>{@link Rest#defaultRequestAttributes()} 224 * </ul> 225 * 226 * @return The annotation value. 227 */ 228 String[] defaultRequestAttributes() default {}; 229 230 /** 231 * Specifies default values for form-data parameters. 232 * 233 * <p> 234 * Strings are of the format <js>"name=value"</js>. 235 * 236 * <p> 237 * Affects values returned by {@link RestRequest#getFormParam(String)} when the parameter is not present on the 238 * request. 239 * 240 * <h5 class='section'>Example:</h5> 241 * <p class='bjava'> 242 * <ja>@RestPut</ja>(path=<js>"/*"</js>, defaultRequestFormData={<js>"foo=bar"</js>}) 243 * <jk>public</jk> String doPut(<ja>@FormData</ja>(<js>"foo"</js>) String <jv>foo</jv>) {...} 244 * </p> 245 * 246 * <h5 class='section'>Notes:</h5><ul> 247 * <li class='note'> 248 * You can use either <js>':'</js> or <js>'='</js> as the key/value delimiter. 249 * <li class='note'> 250 * Key and value is trimmed of whitespace. 251 * <li class='note'> 252 * Supports <a class="doclink" href="https://juneau.apache.org/docs/topics/RestServerSvlVariables">REST Server SVL Variables</a> 253 * (e.g. <js>"$S{mySystemProperty}"</js>). 254 * </ul> 255 * 256 * @return The annotation value. 257 */ 258 String[] defaultRequestFormData() default {}; 259 260 /** 261 * Default request headers. 262 * 263 * <p> 264 * Specifies default values for request headers if they're not passed in through the request. 265 * 266 * <h5 class='section'>Example:</h5> 267 * <p class='bjava'> 268 * <jc>// Assume "text/json" Accept value when Accept not specified</jc> 269 * <ja>@RestPut</ja>(path=<js>"/*"</js>, defaultRequestHeaders={<js>"Accept: text/json"</js>}) 270 * <jk>public</jk> String doPut() {...} 271 * </p> 272 * 273 * <h5 class='section'>Notes:</h5><ul> 274 * <li class='note'> 275 * Supports <a class="doclink" href="https://juneau.apache.org/docs/topics/RestServerSvlVariables">REST Server SVL Variables</a> 276 * (e.g. <js>"$S{mySystemProperty}"</js>). 277 * </ul> 278 * 279 * 280 * @return The annotation value. 281 */ 282 String[] defaultRequestHeaders() default {}; 283 284 /** 285 * Specifies default values for query parameters. 286 * 287 * <p> 288 * Strings are of the format <js>"name=value"</js>. 289 * 290 * <p> 291 * Affects values returned by {@link RestRequest#getQueryParam(String)} when the parameter is not present on the request. 292 * 293 * <h5 class='section'>Example:</h5> 294 * <p class='bjava'> 295 * <ja>@RestPut</ja>(path=<js>"/*"</js>, defaultRequestQueryData={<js>"foo=bar"</js>}) 296 * <jk>public</jk> String doPut(<ja>@Query</ja>(<js>"foo"</js>) String <jv>foo</jv>) {...} 297 * </p> 298 * 299 * <h5 class='section'>Notes:</h5><ul> 300 * <li class='note'> 301 * You can use either <js>':'</js> or <js>'='</js> as the key/value delimiter. 302 * <li class='note'> 303 * Key and value is trimmed of whitespace. 304 * <li class='note'> 305 * Supports <a class="doclink" href="https://juneau.apache.org/docs/topics/RestServerSvlVariables">REST Server SVL Variables</a> 306 * (e.g. <js>"$S{mySystemProperty}"</js>). 307 * </ul> 308 * 309 * @return The annotation value. 310 */ 311 String[] defaultRequestQueryData() default {}; 312 313 /** 314 * Default response headers. 315 * 316 * <p> 317 * Specifies default values for response headers if they're not overwritten during the request. 318 * 319 * <h5 class='section'>Example:</h5> 320 * <p class='bjava'> 321 * <jc>// Assume "text/json" Accept value when Accept not specified</jc> 322 * <ja>@RestPut</ja>(path=<js>"/*"</js>, defaultResponseHeaders={<js>"Content-Type: text/json"</js>}) 323 * <jk>public</jk> String doPut() {...} 324 * </p> 325 * 326 * <h5 class='section'>Notes:</h5><ul> 327 * <li class='note'> 328 * Supports <a class="doclink" href="https://juneau.apache.org/docs/topics/RestServerSvlVariables">REST Server SVL Variables</a> 329 * (e.g. <js>"$S{mySystemProperty}"</js>). 330 * </ul> 331 * 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 * <h5 class='section'>Notes:</h5><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 * <h5 class='section'>Example:</h5> 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>@RestPut</ja>( 385 * encoders={ 386 * EncoderSet.Inherit.<jk>class</jk>, MyEncoder.<jk>class</jk> 387 * } 388 * ) 389 * <jk>public void</jk> doPut(MyBean <jv>bean</jv>) { 390 * ... 391 * } 392 * } 393 * </p> 394 * 395 * <p> 396 * For programmatic equivalents, contribute a {@link EncoderSet} bean via 397 * {@link org.apache.juneau.commons.inject.Bean @Bean(name="encoders")} (use methodScope to scope to specific operation methods). 398 * 399 * <h5 class='section'>See Also:</h5><ul> 400 * <li class='link'><a class="doclink" href="https://juneau.apache.org/docs/topics/RestServerEncoders">Encoders in REST servers</a> 401 * </ul> 402 * 403 * @return The annotation value. 404 */ 405 Class<? extends Encoder>[] encoders() default {}; 406 407 /** 408 * Method-level guards. 409 * 410 * <p> 411 * Associates one or more {@link RestGuard RestGuards} with this method. 412 * 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 * <h5 class='section'>See Also:</h5><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 * <h5 class='section'>Example:</h5> 444 * <p class='bjava'> 445 * <ja>@RestPut</ja>( 446 * maxInput=<js>"100M"</js> 447 * ) 448 * </p> 449 * 450 * <h5 class='section'>Notes:</h5><ul> 451 * <li class='note'> 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 * <h5 class='section'>See Also:</h5><ul> 457 * <li class='ja'>{@link Rest#maxInput} 458 * </ul> 459 * 460 * @return The annotation value. 461 */ 462 String maxInput() default ""; 463 464 /** 465 * Specifies the parsers for converting HTTP request bodies into POJOs for this method. 466 * 467 * <p> 468 * Parsers are used to convert the content of HTTP requests into POJOs. 469 * <br>Any of the Juneau framework parsers can be used in this setting. 470 * <br>The parser selected is based on the request <c>Content-Type</c> header matched against the values returned by the following method 471 * using a best-match algorithm: 472 * <ul class='javatree'> 473 * <li class='jm'>{@link Parser#getMediaTypes()} 474 * </ul> 475 * 476 * <p> 477 * This value overrides parsers specified at the class level using {@link Rest#parsers()}. 478 * The {@link org.apache.juneau.marshall.parser.ParserSet.Inherit ParserSet.Inherit} class can be used to include values from the parent class. 479 * 480 * <h5 class='section'>Example:</h5> 481 * <p class='bjava'> 482 * <jc>// Define a REST resource that can consume JSON and HTML.</jc> 483 * <ja>@Rest</ja>( 484 * parsers={ 485 * JsonParser.<jk>class</jk>, 486 * HtmlParser.<jk>class</jk> 487 * } 488 * ) 489 * <jk>public class</jk> MyResource { 490 * 491 * <jc>// Define a REST method that can also consume XML.</jc> 492 * <ja>@RestPut</ja>( 493 * parsers={ 494 * ParserSet.Inherit.<jk>class</jk>, XmlParser.<jk>class</jk> 495 * } 496 * ) 497 * <jk>public void</jk> doPut(MyBean <jv>bean</jv>) { 498 * ... 499 * } 500 * } 501 * </p> 502 * 503 * <p> 504 * For programmatic equivalents, contribute a {@link ParserSet} bean via 505 * {@link org.apache.juneau.commons.inject.Bean @Bean(name="parsers")} (use methodScope to scope to specific operation methods). 506 * 507 * <h5 class='section'>See Also:</h5><ul> 508 * <li class='link'><a class="doclink" href="https://juneau.apache.org/docs/topics/Marshalling">Marshalling</a> 509 * </ul> 510 * 511 * @return The annotation value. 512 */ 513 Class<?>[] parsers() default {}; 514 515 /** 516 * Optional path pattern for the specified method. 517 * 518 * <p> 519 * Appending <js>"/*"</js> to the end of the path pattern will make it match any remainder too. 520 * <br>Not appending <js>"/*"</js> to the end of the pattern will cause a 404 (Not found) error to occur if the exact 521 * pattern is not found. 522 * 523 * <p> 524 * The path can contain variables that get resolved to {@link org.apache.juneau.http.Path @Path} parameters. 525 * 526 * <h5 class='figure'>Examples:</h5> 527 * <p class='bjava'> 528 * <ja>@RestPut</ja>(path=<js>"/myurl/{foo}/{bar}/{baz}/*"</js>) 529 * </p> 530 * <p class='bjava'> 531 * <ja>@RestPut</ja>(path=<js>"/myurl/{0}/{1}/{2}/*"</js>) 532 * </p> 533 * 534 * <p> 535 * If you do not specify a path name, then the path name is inferred from the Java method name. 536 * 537 * <h5 class='figure'>Example:</h5> 538 * <p class='bjava'> 539 * <jc>// Path is assumed to be "/foo".</jc> 540 * <ja>@RestPut</ja> 541 * <jk>public void</jk> foo() {...} 542 * </p> 543 * 544 * <p> 545 * Note that you can also use {@link #value()} to specify the path. 546 * 547 * <h5 class='section'>See Also:</h5><ul> 548 * <li class='ja'>{@link org.apache.juneau.http.Path} 549 * </ul> 550 * 551 * @return The annotation value. 552 */ 553 String[] path() default {}; 554 555 /** 556 * Per-operation override for {@link Rest#problemDetails() @Rest(problemDetails)}. 557 * 558 * <p> 559 * When set on a {@code @RestPut} method, this value takes precedence over the resource-level 560 * {@code @Rest(problemDetails)} attribute for this operation. Tri-state semantics: 561 * 562 * <ul class='values'> 563 * <li><js>"true"</js> — enable problem-details responses for this operation. 564 * <li><js>"false"</js> — disable problem-details responses for this operation (overrides an 565 * opted-in resource). 566 * <li><js>""</js> (default) — inherit from {@link Rest#problemDetails()}. 567 * </ul> 568 * 569 * <h5 class='section'>Notes:</h5><ul> 570 * <li class='note'> 571 * Supports <a class="doclink" href="https://juneau.apache.org/docs/topics/RestServerSvlVariables">REST Server SVL Variables</a> 572 * (e.g. <js>"$L{my.localized.variable}"</js>). 573 * </ul> 574 * 575 * <h5 class='section'>See Also:</h5><ul> 576 * <li class='ja'>{@link Rest#problemDetails()} 577 * </ul> 578 * 579 * @return The annotation value. 580 */ 581 String problemDetails() default ""; 582 583 /** 584 * Per-operation override for {@link Rest#debugMarshalling() @Rest(debugMarshalling)}. 585 * 586 * <p> 587 * When set on a {@code @RestPut} method, this value takes precedence over the resource-level 588 * {@code @Rest(debugMarshalling)} attribute for this operation. Tri-state semantics: 589 * 590 * <ul class='values'> 591 * <li><js>"true"</js> — enable marshalling debug for this operation. 592 * <li><js>"false"</js> — disable marshalling debug for this operation (overrides an opted-in resource). 593 * <li><js>""</js> (default) — inherit from {@link Rest#debugMarshalling()}. 594 * </ul> 595 * 596 * <h5 class='section'>See Also:</h5><ul> 597 * <li class='ja'>{@link Rest#debugMarshalling()} 598 * </ul> 599 * 600 * @return The annotation value. 601 */ 602 String debugMarshalling() default ""; 603 604 /** 605 * Per-operation observability opt-in / opt-out control. 606 * 607 * <p> 608 * Overrides the resource-level {@link Rest#observability()} setting for this specific operation. 609 * 610 * <ul class='values'> 611 * <li><js>"true"</js> — strict opt-in; requires a wired observability backend. 612 * <li><js>"false"</js> — explicit opt-out; short-circuits the observability block. 613 * <li><js>""</js> (default) — inherits the resource-level setting. 614 * </ul> 615 * 616 * <h5 class='section'>See Also:</h5><ul> 617 * <li class='ja'>{@link RestOp#observability()} 618 * </ul> 619 * 620 * @return The annotation value. 621 * @since 10.0.0 622 */ 623 String observability() default ""; 624 625 /** 626 * Per-operation override for {@link Rest#asyncCompletionExecutor() @Rest(asyncCompletionExecutor)}. 627 * 628 * <p> 629 * Names the {@link java.util.concurrent.Executor} bean used to route completion callbacks for this 630 * specific operation through a dedicated thread pool. Empty string (default) inherits from 631 * {@link Rest#asyncCompletionExecutor()}. 632 * 633 * <h5 class='section'>See Also:</h5><ul> 634 * <li class='ja'>{@link RestOp#asyncCompletionExecutor()} 635 * <li class='ja'>{@link Rest#asyncCompletionExecutor()} 636 * </ul> 637 * 638 * @return The annotation value. 639 * @since 10.0.0 640 */ 641 String asyncCompletionExecutor() default ""; 642 643 /** 644 * Per-operation metric name override. Empty string (default) uses the recorder's own name derivation. 645 * 646 * <h5 class='section'>See Also:</h5><ul> 647 * <li class='ja'>{@link RestOp#metricName()} 648 * </ul> 649 * 650 * @return The annotation value. 651 * @since 10.0.0 652 */ 653 String metricName() default ""; 654 655 /** 656 * Per-operation metric tags. Format: comma-separated {@code key=value} pairs. 657 * Empty string (default) means no additional tags. 658 * 659 * <h5 class='section'>See Also:</h5><ul> 660 * <li class='ja'>{@link RestOp#metricTags()} 661 * </ul> 662 * 663 * @return The annotation value. 664 * @since 10.0.0 665 */ 666 String metricTags() default ""; 667 668 /** 669 * Supported accept media types. 670 * 671 * <p> 672 * Overrides the media types inferred from the serializers that identify what media types can be produced by the resource. 673 * 674 * <h5 class='section'>Notes:</h5><ul> 675 * <li class='note'> 676 * Supports <a class="doclink" href="https://juneau.apache.org/docs/topics/RestServerSvlVariables">REST Server SVL Variables</a> 677 * (e.g. <js>"$S{mySystemProperty}"</js>). 678 * </ul> 679 * 680 * <h5 class='section'>See Also:</h5><ul> 681 * <li class='jm'>{@link RestOpContext#getSupportedAcceptTypes()} 682 * </ul> 683 * 684 * @return The annotation value. 685 */ 686 String[] produces() default {}; 687 688 /** 689 * Allowed serializer session option keys for this operation (ordered merge, prefix {@code -key} removes a key). 690 * 691 * <p> 692 * Comma-delimited list of session property keys that clients may send via the <js>"X-Juneau-Serializer-Options"</js> 693 * header or <js>"juneauSerializerOptions"</js> query parameter. 694 * Merged on top of resource-level {@link Rest#allowedSerializerOptions()} values. 695 * Use {@link #noInherit()} to replace rather than extend the resource-level list. 696 * 697 * <h5 class='section'>See Also:</h5><ul> 698 * <li class='link'><a class="doclink" href="https://juneau.apache.org/docs/topics/SessionOptions#safe-properties">Safe Properties</a> 699 * </ul> 700 * 701 * @return The annotation value. 702 */ 703 String[] allowedSerializerOptions() default {}; 704 705 /** 706 * Allowed parser session option keys for this operation (ordered merge, prefix {@code -key} removes a key). 707 * 708 * <p> 709 * Comma-delimited list of session property keys that clients may send via the <js>"X-Juneau-Parser-Options"</js> 710 * header or <js>"juneauParserOptions"</js> query parameter. 711 * Merged on top of resource-level {@link Rest#allowedParserOptions()} values. 712 * Use {@link #noInherit()} to replace rather than extend the resource-level list. 713 * 714 * <h5 class='section'>See Also:</h5><ul> 715 * <li class='link'><a class="doclink" href="https://juneau.apache.org/docs/topics/SessionOptions#safe-properties">Safe Properties</a> 716 * </ul> 717 * 718 * @return The annotation value. 719 */ 720 String[] allowedParserOptions() default {}; 721 722 /** 723 * Property names for which less-derived contributions are NOT inherited. 724 * 725 * <p> 726 * Accepted values: {@code "allowedSerializerOptions"}, {@code "allowedParserOptions"}, 727 * {@code "problemDetails"}, {@code "debugMarshalling"}. 728 * Prevents the named property from inheriting values from the enclosing {@code @Rest} annotation. 729 * The {@code noInherit} attribute itself is never inherited. 730 * 731 * <h5 class='section'>See Also:</h5><ul> 732 * <li class='link'><a class="doclink" href="https://juneau.apache.org/docs/topics/SessionOptions">Session Options via HTTP</a> 733 * </ul> 734 * 735 * @return The annotation value. 736 */ 737 String[] noInherit() default {}; 738 739 /** 740 * Role guard. 741 * 742 * <p> 743 * An expression defining if a user with the specified roles are allowed to access this method. 744 * 745 * <h5 class='section'>Example:</h5> 746 * <p class='bjava'> 747 * <jk>public class</jk> MyResource <jk>extends</jk> BasicRestServlet { 748 * 749 * <ja>@RestPut</ja>( 750 * path=<js>"/foo"</js>, 751 * roleGuard=<js>"ROLE_ADMIN || (ROLE_READ_WRITE && ROLE_SPECIAL)"</js> 752 * ) 753 * <jk>public</jk> Object doPut() { 754 * } 755 * } 756 * </p> 757 * 758 * <h5 class='section'>Notes:</h5><ul> 759 * <li class='note'> 760 * Supports any of the following expression constructs: 761 * <ul> 762 * <li><js>"foo"</js> - Single arguments. 763 * <li><js>"foo,bar,baz"</js> - Multiple OR'ed arguments. 764 * <li><js>"foo | bar | baz"</js> - Multiple OR'ed arguments, pipe syntax. 765 * <li><js>"foo || bar || baz"</js> - Multiple OR'ed arguments, Java-OR syntax. 766 * <li><js>"fo*"</js> - Patterns including <js>'*'</js> and <js>'?'</js>. 767 * <li><js>"fo* & *oo"</js> - Multiple AND'ed arguments, ampersand syntax. 768 * <li><js>"fo* && *oo"</js> - Multiple AND'ed arguments, Java-AND syntax. 769 * <li><js>"fo* || (*oo || bar)"</js> - Parenthesis. 770 * </ul> 771 * <li class='note'> 772 * AND operations take precedence over OR operations (as expected). 773 * <li class='note'> 774 * Whitespace is ignored. 775 * <li class='note'> 776 * <jk>null</jk> or empty expressions always match as <jk>false</jk>. 777 * <li class='note'> 778 * If patterns are used, you must specify the list of declared roles using {@link #rolesDeclared()}. 779 * <li class='note'> 780 * Supports <a class="doclink" href="https://juneau.apache.org/docs/topics/RestServerSvlVariables">REST Server SVL Variables</a> 781 * (e.g. <js>"$L{my.localized.variable}"</js>). 782 * <li class='note'> 783 * When defined on parent/child classes and methods, ALL guards within the hierarchy must pass. 784 * </ul> 785 * 786 * 787 * @return The annotation value. 788 */ 789 String roleGuard() default ""; 790 791 /** 792 * Declared roles. 793 * 794 * <p> 795 * A comma-delimited list of all possible user roles. 796 * 797 * <p> 798 * Used in conjunction with {@link #roleGuard()} is used with patterns. 799 * 800 * <h5 class='section'>Example:</h5> 801 * <p class='bjava'> 802 * <jk>public class</jk> MyResource <jk>extends</jk> BasicRestServlet { 803 * 804 * <ja>@RestPut</ja>( 805 * path=<js>"/foo"</js>, 806 * rolesDeclared=<js>"ROLE_ADMIN,ROLE_READ_WRITE,ROLE_READ_ONLY,ROLE_SPECIAL"</js>, 807 * roleGuard=<js>"ROLE_ADMIN || (ROLE_READ_WRITE && ROLE_SPECIAL)"</js> 808 * ) 809 * <jk>public</jk> Object doPut() { 810 * } 811 * } 812 * </p> 813 * 814 * 815 * @return The annotation value. 816 */ 817 String rolesDeclared() default ""; 818 819 /** 820 * Specifies the serializers for marshalling POJOs into response bodies for this method. 821 * 822 * <p> 823 * Serializer are used to convert POJOs to HTTP response bodies. 824 * <br>Any of the Juneau framework serializers can be used in this setting. 825 * <br>The serializer selected is based on the request <c>Accept</c> header matched against the values returned by the following method 826 * using a best-match algorithm: 827 * <ul class='javatree'> 828 * <li class='jm'>{@link Serializer#getMediaTypeRanges()} 829 * </ul> 830 * 831 * <p> 832 * This value overrides serializers specified at the class level using {@link Rest#serializers()}. 833 * The {@link org.apache.juneau.marshall.serializer.SerializerSet.Inherit SerializerSet.Inherit} class can be used to include values from the parent class. 834 * 835 * <h5 class='section'>Example:</h5> 836 * <p class='bjava'> 837 * <jc>// Define a REST resource that can produce JSON and HTML.</jc> 838 * <ja>@Rest</ja>( 839 * serializers={ 840 * JsonParser.<jk>class</jk>, 841 * HtmlParser.<jk>class</jk> 842 * } 843 * ) 844 * <jk>public class</jk> MyResource { 845 * 846 * <jc>// Define a REST method that can also produce XML.</jc> 847 * <ja>@RestPut</ja>( 848 * parsers={ 849 * SerializerSet.Inherit.<jk>class</jk>, XmlParser.<jk>class</jk> 850 * } 851 * ) 852 * <jk>public</jk> MyBean doPut() { 853 * ... 854 * } 855 * } 856 * </p> 857 * 858 * <p> 859 * For programmatic equivalents, contribute a {@link SerializerSet} bean via 860 * {@link org.apache.juneau.commons.inject.Bean @Bean(name="serializers")} (use methodScope to scope to specific operation methods). 861 * 862 * <h5 class='section'>See Also:</h5><ul> 863 * <li class='link'><a class="doclink" href="https://juneau.apache.org/docs/topics/Marshalling">Marshalling</a> 864 * </ul> 865 * 866 * @return The annotation value. 867 */ 868 Class<? extends Serializer>[] serializers() default {}; 869 870 /** 871 * Optional summary for the exposed API. 872 * 873 * <p> 874 * This summary is used in the following locations: 875 * <ul class='spaced-list'> 876 * <li> 877 * The value returned by {@link Operation#getSummary()} in the auto-generated swagger. 878 * <li> 879 * The <js>"$RS{operationSummary}"</js> variable. 880 * <li> 881 * The summary of the method in the Swagger page. 882 * </ul> 883 * 884 * <h5 class='section'>Notes:</h5><ul> 885 * <li class='note'> 886 * Corresponds to the swagger field <c>/paths/{path}/{method}/summary</c>. 887 * <li class='note'> 888 * Supports <a class="doclink" href="https://juneau.apache.org/docs/topics/RestServerSvlVariables">REST Server SVL Variables</a> 889 * (e.g. <js>"$L{my.localized.variable}"</js>). 890 * </ul> 891 * 892 * @return The annotation value. 893 */ 894 String summary() default ""; 895 896 /** 897 * Provides swagger-specific metadata on this method. 898 * 899 * <p> 900 * Used to populate the auto-generated OPTIONS swagger documentation. 901 * 902 * <p> 903 * The format of this annotation is JSON when all individual parts are concatenated. 904 * <br>The starting and ending <js>'{'</js>/<js>'}'</js> characters around the entire value are optional. 905 * 906 * <h5 class='section'>Example:</h5> 907 * <p class='bjava'> 908 * <ja>@RestPut</ja>( 909 * path=<js>"/{propertyName}"</js>, 910 * 911 * <jc>// Swagger info.</jc> 912 * swagger={ 913 * <js>"parameters:["</js>, 914 * <js>"{name:'propertyName',in:'path',description:'The system property name.'},"</js>, 915 * <js>"{in:'body',description:'The new system property value.'}"</js>, 916 * <js>"],"</js>, 917 * <js>"responses:{"</js>, 918 * <js>"302: {headers:{Location:{description:'The root URL of this resource.'}}},"</js>, 919 * <js>"403: {description:'User is not an admin.'}"</js>, 920 * <js>"}"</js> 921 * } 922 * ) 923 * </p> 924 * 925 * <h5 class='section'>Notes:</h5><ul> 926 * <li class='note'> 927 * The format is <a class="doclink" href="https://juneau.apache.org/docs/topics/JuneauBeanSwagger2">juneau-bean-swagger-v2</a>. 928 * <br>Multiple lines are concatenated with newlines. 929 * <li class='note'> 930 * The starting and ending <js>'{'</js>/<js>'}'</js> characters around the entire value are optional. 931 * <li class='note'> 932 * These values are superimposed on top of any Swagger JSON file present for the resource in the classpath. 933 * <li class='note'> 934 * Supports <a class="doclink" href="https://juneau.apache.org/docs/topics/RestServerSvlVariables">REST Server SVL Variables</a> 935 * (e.g. <js>"$L{my.localized.variable}"</js>). 936 * </ul> 937 * 938 * <h5 class='section'>See Also:</h5><ul> 939 * <li class='ja'>{@link OpSwagger} 940 * <li class='jc'>{@link SwaggerProvider} 941 * </ul> 942 * 943 * @return The annotation value. 944 */ 945 OpSwagger swagger() default @OpSwagger; 946 947 /** 948 * REST method path. 949 * 950 * <p> 951 * Can be used to provide a shortened form for the {@link #path()} value. 952 * 953 * <p> 954 * The following examples are considered equivalent. 955 * <p class='bjava'> 956 * <jc>// Normal form</jc> 957 * <ja>@RestPut</ja>(path=<js>"/{propertyName}"</js>) 958 * 959 * <jc>// Shortened form</jc> 960 * <ja>@RestPut</ja>(<js>"/{propertyName}"</js>) 961 * </p> 962 * 963 * @return The annotation value. 964 */ 965 String value() default ""; 966}