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