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