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