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