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