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.commons.*; 025import org.apache.juneau.config.*; 026import org.apache.juneau.http.*; 027import org.apache.juneau.marshall.*; 028import org.apache.juneau.marshall.encoders.*; 029import org.apache.juneau.marshall.httppart.*; 030import org.apache.juneau.marshall.parser.*; 031import org.apache.juneau.marshall.serializer.*; 032import org.apache.juneau.rest.server.arg.*; 033import org.apache.juneau.rest.server.auth.*; 034import org.apache.juneau.rest.server.converter.*; 035import org.apache.juneau.rest.server.guard.*; 036import org.apache.juneau.rest.server.openapi.*; 037import org.apache.juneau.rest.server.processor.*; 038import org.apache.juneau.rest.server.servlet.*; 039import org.apache.juneau.rest.server.staticfile.*; 040import org.apache.juneau.rest.server.swagger.*; 041 042/** 043 * Used to denote that a class is a REST resource and to associate metadata on it. 044 * 045 * <p> 046 * Usually used on a subclass of {@link RestServlet}, but can be used to annotate any class that you want to expose as 047 * a REST resource. 048 * 049 * <h2 class='section'>Default response format (content negotiation):</h2> 050 * <p> 051 * The response format is <b>not</b> hardwired to JSON. The serializer used to render a response body is chosen by 052 * ordinary HTTP content negotiation — the request's <c>Accept</c> header is best-matched against the media types 053 * of the configured {@link #serializers() serializers} (see {@link Serializer#getMediaTypeRanges()}). A request that 054 * sends no <c>Accept</c> header (or a non-specific one such as <c>*/*</c>, which browsers send by default) is 055 * treated as <c>*/*</c> and matches the <b>first</b> serializer in the set. 056 * 057 * <p> 058 * In the default configuration ({@link BasicRestServlet} / {@link BasicRestResource}, via 059 * {@link org.apache.juneau.rest.server.config.BasicUniversalConfig}) the serializer set lists HTML first, so a browser 060 * — or any client that omits <c>Accept</c> — receives <b>HTML</b>, not JSON. To always get JSON, send an 061 * explicit <c>Accept: application/json</c> header. See {@link #serializers()} for how serializer ordering determines 062 * this default. 063 * 064 * <h2 class='section'>See Also:</h2><ul> 065 * <li class='link'><a class="doclink" href="https://juneau.apache.org/docs/topics/RestAnnotatedClasses">@Rest-Annotated Class</a> 066 067 * </ul> 068 */ 069@Target(TYPE) 070@Retention(RUNTIME) 071@Inherited 072@AnnotationGroup(Rest.class) 073public @interface Rest { 074 075 /** 076 * Allowed header URL parameters. 077 * 078 * <p> 079 * When specified, allows headers such as <js>"Accept"</js> and <js>"Content-Type"</js> to be passed in as URL query 080 * parameters. 081 * <br> 082 * For example: 083 * <p class='burlenc'> 084 * ?Accept=text/json&Content-Type=text/json 085 * </p> 086 * 087 * <h4 class='section'>Notes:</h4><ul> 088 * <li class='note'> 089 * Supports <a class="doclink" href="https://juneau.apache.org/docs/topics/RestServerSvlVariables">REST Server SVL Variables</a> 090 * (e.g. <js>"${L:my.localized.variable}"</js>). 091 * <li class='note'> 092 * Use <js>"*"</js> to represent all methods. 093 * <li class='note'> 094 * Use <js>"NONE"</js> (case insensitive) to suppress inheriting a value from a parent class. 095 * </ul> 096 * 097 * @return The annotation value. 098 */ 099 String allowedHeaderParams() default ""; 100 101 /** 102 * Allowed method headers. 103 * 104 * <p> 105 * A comma-delimited list of HTTP method names that are allowed to be passed as values in an <c>X-Method</c>, 106 * <c>X-HTTP-Method-Override</c>, <c>X-HTTP-Method</c> or <c>X-Method-Override</c> HTTP header to override the real HTTP 107 * method name. All four headers share this list; when more than one is sent they are tried in that order. 108 * <p> 109 * Allows you to override the actual HTTP method with a simulated method. 110 * <br>For example, if an HTTP Client API doesn't support <c>PATCH</c> but does support <c>POST</c> (because 111 * <c>PATCH</c> is not part of the original HTTP spec), you can add a <c>X-Method: PATCH</c> header on a normal 112 * <c>HTTP POST /foo</c> request call which will make the HTTP call look like a <c>PATCH</c> request in any of the REST APIs. 113 * 114 * <h4 class='section'>Notes:</h4><ul> 115 * <li class='note'> 116 * Supports <a class="doclink" href="https://juneau.apache.org/docs/topics/RestServerSvlVariables">REST Server SVL Variables</a> 117 * (e.g. <js>"${L:my.localized.variable}"</js>). 118 * <li class='note'> 119 * Method names are case-insensitive. 120 * <li class='note'> 121 * Use <js>"*"</js> to represent all methods. 122 * <li class='note'> 123 * Use <js>"NONE"</js> (case insensitive) to suppress inheriting a value from a parent class. 124 * <li class='note'> 125 * Once the list admits at least one method, override claims must agree: a request whose override headers (or 126 * <c>method</c> query parameter) name more than one distinct method is refused with <c>400</c>, whether or not the 127 * list admits them. 128 * <li class='note'> 129 * On a safe request (<c>GET</c>, <c>HEAD</c>, <c>OPTIONS</c>, <c>TRACE</c>), an override is honored only when it names 130 * another safe method or an operation declared {@link RestOp#read() read=true}; anything else is refused with 131 * <c>405</c>. Overrides on a <c>POST</c> are unaffected. 132 * </ul> 133 * 134 * @return The annotation value. 135 */ 136 String allowedMethodHeaders() default ""; 137 138 /** 139 * Allowed response headers. 140 * 141 * <p> 142 * A comma-delimited list of response header names that a client may ask the server to add to its own response by 143 * passing them in an <c>x-response-headers</c> request header (or query parameter, when allowed) in URL-encoded 144 * object notation. 145 * <br> 146 * For example: 147 * <p class='bcode'> 148 * x-response-headers: X-Custom=hi 149 * </p> 150 * 151 * <p> 152 * This feature is off by default (empty list); when the request carries an <c>x-response-headers</c> value, it is 153 * ignored unless the header name appears in this list. 154 * <br>The headers <c>Set-Cookie</c>, <c>Location</c>, <c>Content-Security-Policy</c> and <c>Content-Type</c> can 155 * never be set this way, regardless of this list. 156 * 157 * <h4 class='section'>Notes:</h4><ul> 158 * <li class='note'> 159 * Supports <a class="doclink" href="https://juneau.apache.org/docs/topics/RestServerSvlVariables">REST Server SVL Variables</a> 160 * (e.g. <js>"${L:my.localized.variable}"</js>). 161 * <li class='note'> 162 * Header names are case-insensitive. 163 * <li class='note'> 164 * Use <js>"NONE"</js> (case insensitive) to suppress inheriting a value from a parent class. 165 * </ul> 166 * 167 * @return The annotation value. 168 */ 169 String allowedResponseHeaders() default ""; 170 171 /** 172 * Allow cross-site requests for unsafe methods. 173 * 174 * <p> 175 * By default, requests using a method other than <c>GET</c>, <c>HEAD</c>, <c>OPTIONS</c> or <c>TRACE</c> are 176 * rejected with a <c>403</c> when the <c>Sec-Fetch-Site</c> header is <c>cross-site</c>, or when an <c>Origin</c> 177 * header is present and does not match the <c>Host</c> header. 178 * <br>Requests carrying neither header (for example, non-browser clients) are not affected. 179 * <br>This check is on by default; no other authentication or CSRF filter is registered unless the application adds one. 180 * 181 * <h4 class='section'>Notes:</h4><ul> 182 * <li class='note'> 183 * Supports <a class="doclink" href="https://juneau.apache.org/docs/topics/RestServerSvlVariables">REST Server SVL Variables</a> 184 * (e.g. <js>"${L:my.localized.variable}"</js>). 185 * </ul> 186 * 187 * @return The annotation value. 188 */ 189 String allowCrossSite() default ""; 190 191 /** 192 * Trusted origins for cross-site checks. 193 * 194 * <p> 195 * A comma-delimited list of origins (e.g. <js>"https://app.example.com"</js>). 196 * A request using an unsafe method whose <c>Origin</c> header does not match the <c>Host</c> header is still accepted 197 * when the origin is in this list. 198 * <br>The <c>X-Forwarded-Host</c> header is only honoured in place of <c>Host</c> when its value is the authority 199 * (host and optional port) of one of the listed origins. 200 * <br>The default is an empty list. Use {@link #allowCrossSite()} to turn the check off entirely. 201 * 202 * <h4 class='section'>Notes:</h4><ul> 203 * <li class='note'> 204 * Supports <a class="doclink" href="https://juneau.apache.org/docs/topics/RestServerSvlVariables">REST Server SVL Variables</a> 205 * (e.g. <js>"${L:my.localized.variable}"</js>). 206 * <li class='note'> 207 * Origins are compared case-insensitively. 208 * </ul> 209 * 210 * @return The annotation value. 211 */ 212 String allowedOrigins() default ""; 213 214 /** 215 * Allowed method parameters. 216 * 217 * <p> 218 * When specified, the HTTP method can be overridden by passing in a <js>"method"</js> URL parameter. 219 * <br> 220 * For example: 221 * <p class='burlenc'> 222 * ?method=OPTIONS 223 * </p> 224 * <p> 225 * On a safe request (<c>GET</c>, <c>HEAD</c>, <c>OPTIONS</c>, <c>TRACE</c>), which is what a link or a typed URL sends, 226 * the parameter may only name another safe method or a custom method whose operation is declared 227 * {@link RestOp#read() read=true}. Anything else, for example <c>GET /foo?method=DELETE</c>, is refused with 228 * <c>405 Method Not Allowed</c>, so a link can never trigger a write. On a <c>POST</c>, the parameter may name any 229 * method in this list. 230 * 231 * <h4 class='section'>Notes:</h4><ul> 232 * <li class='note'> 233 * Supports <a class="doclink" href="https://juneau.apache.org/docs/topics/RestServerSvlVariables">REST Server SVL Variables</a> 234 * (e.g. <js>"${L:my.localized.variable}"</js>). 235 * <li class='note'> 236 * Use <js>"*"</js> to represent all methods. 237 * <li class='note'> 238 * Use <js>"NONE"</js> (case insensitive) to suppress inheriting a value from a parent class. 239 * </ul> 240 * 241 * @return The annotation value. 242 */ 243 String allowedMethodParams() default ""; 244 245 /** 246 * Resource-level authenticator. 247 * 248 * <p> 249 * Resolves the {@link java.security.Principal} and roles for requests to this resource and its descendant child 250 * resources (inherited unless cut off via {@code noInherit={"authenticator"}}), so that {@code roleGuard} / 251 * {@link RoleBasedRestGuard} / {@link Auth @Auth} 252 * / {@code isUserInRole} resolve against the computed identity. 253 * 254 * <h4 class='section'>Notes:</h4><ul> 255 * <li class='note'> 256 * The implementation is instantiated through the resource's bean store (constructor injection). 257 * <li class='note'> 258 * The default {@link org.apache.juneau.rest.server.auth.RestAuthenticator.Null RestAuthenticator.Null} sentinel means "not specified." 259 * </ul> 260 * 261 * <h4 class='section'>See Also:</h4><ul> 262 * <li class='link'><a class="doclink" href="https://juneau.apache.org/docs/topics/RestServerAuthenticator">REST Authenticator — Resource-Level Authentication</a> 263 * </ul> 264 * 265 * @return The annotation value. 266 * @since 10.0.0 267 */ 268 Class<? extends RestAuthenticator> authenticator() default RestAuthenticator.Null.class; 269 270 /** 271 * REST children. 272 * 273 * <p> 274 * Defines children of this resource. Each child resource is mounted under its own URL subtree (per the 275 * child's own {@code @Rest(path=...)} / {@code @Rest(paths=...)}) and constructs its own {@link RestContext}. 276 * 277 * <h4 class='section'>Children vs. mixins (resolution semantics)</h4> 278 * <p> 279 * Children are <b>isolated from the parent's resolution chain</b> by design — a child's serializers, parsers, 280 * guards, hooks, etc. are all resolved against the child's own {@link RestContext} only, NOT walked 281 * through the parent. This is the opposite of how {@link #mixins() mixins} resolve. See the 282 * <a class="doclink" href="https://juneau.apache.org/docs/topics/RestServerMixinSubContexts#mixin-vs-child-divergence">Mixin-vs-child divergence</a> 283 * topic for the rationale (children own their lifecycle and are externally mounted; mixins are inline composers 284 * sharing the host's URL namespace and resolution chain). 285 * 286 * <h4 class='section'>Inheritance Rules</h4> 287 * <ul> 288 * <li>Children on child are combined with those on parent class. 289 * <li>Children are list parent-to-child in the order they appear in the annotation. 290 * </ul> 291 * 292 * <h4 class='section'>See Also:</h4><ul> 293 * <li class='link'><a class="doclink" href="https://juneau.apache.org/docs/topics/ChildResources">Child Resources</a> 294 * <li class='link'><a class="doclink" href="https://juneau.apache.org/docs/topics/RestServerMixinSubContexts">REST Server — Mixin Sub-Contexts</a> (for the mixin-vs-child divergence) 295 * </ul> 296 * 297 * @return The annotation value. 298 */ 299 Class<?>[] children() default {}; 300 301 /** 302 * Rich child definitions — the host-side seed form of {@link #children()}. 303 * 304 * <p> 305 * Each {@link Child @Child} entry names a child class (via {@link Child#type()}) <b>and</b> lets the host 306 * seed a curated set of {@code @Rest}-level settings onto that child's otherwise-isolated 307 * {@link RestContext} — guards, role guards, part serializer/parser, and a 308 * handful of default-scalar settings — without editing the child class. 309 * 310 * <p> 311 * Unlike {@link #mixinDefs() mixinDefs}, this does not override an inherited chain (children never inherit 312 * from the host); it seeds settings onto an isolated context. Additive-security seed members ({@code guards}, 313 * {@code converters}, {@code roleGuard}, {@code rolesDeclared}) can't be removed or weakened by the child; 314 * the remaining scalar seed members are a fallback the child's own explicit {@code @Rest} declaration wins 315 * over. See {@link Child} for the full semantics. 316 * 317 * <h4 class='section'>Example:</h4> 318 * <p class='bjava'> 319 * <ja>@Rest</ja>( 320 * childrenDefs=<ja>@Child</ja>(type=FooChild.<jk>class</jk>, maxInput=<js>"10M"</js>) 321 * ) 322 * <jk>public class</jk> MyResource { ... } 323 * </p> 324 * 325 * <p> 326 * This attribute is additive to {@link #children()}: bare-class entries in {@code children()} and rich 327 * entries here are discovered together (bare classes first, then {@code childrenDefs}). A 328 * {@code @Child(type=X.class)} with no seed members is the exact equivalent of a bare 329 * {@code children=X.class} entry. 330 * 331 * <h4 class='section'>See Also:</h4><ul> 332 * <li class='ja'>{@link Child} 333 * <li class='jm'>{@link #children()} 334 * <li class='link'><a class="doclink" href="https://juneau.apache.org/docs/topics/ChildResources#host-side-seeding-with-child-1000">Host-side seeding with @Child (10.0.0)</a> 335 * </ul> 336 * 337 * @return The annotation value. 338 * @since 10.0.0 339 */ 340 Child[] childrenDefs() default {}; 341 342 /** 343 * REST mixins. 344 * 345 * <p> 346 * Defines operation-provider classes whose {@link RestOp @RestOp}-group methods should be composed into this 347 * resource. 348 * 349 * <p> 350 * Mixin methods are discovered the same way as local operation methods and surface under this resource's URL 351 * namespace. On path/method collisions, local methods on this resource win over mixin methods. 352 * 353 * <h4 class='section'>Per-mixin RestContext + host-to-mixin inheritance (since 10.0.0)</h4> 354 * <p> 355 * Each mixin class is elevated to its own {@link RestContext} parent-linked to this host's {@link RestContext}. 356 * The mixin's class-level {@code @Rest(...)} configuration applies to its own endpoints, with inheritance from 357 * the host: 358 * <ul> 359 * <li><b>List-shaped properties</b> ({@code serializers}, {@code parsers}, {@code encoders}, {@code converters}, 360 * {@code responseProcessors}, {@code restOpArgs}, {@code guards}) — host's chain runs first, then the mixin's 361 * appended. Host endpoints see only the host's chain. 362 * <li><b>Replace-shaped properties</b> ({@code partSerializer}, {@code partParser}) — the mixin's value wins 363 * over the host's for mixin endpoints when declared; otherwise the host's value is inherited. 364 * <li><b>{@code messages}</b> — the mixin's bundle is chained as a child of the host's via 365 * {@link org.apache.juneau.marshall.cp.Messages#chain Messages.chain(child, parent)} so mixin keys win and missing 366 * keys fall through to the host. 367 * <li><b>Lifecycle hooks</b> ({@code @RestStartCall}, {@code @RestEndCall}, {@code @RestPreCall}, 368 * {@code @RestPostCall}, {@code @RestDestroy}) — dual-fire host-then-mixin for mixin-endpoint requests; 369 * host-only for host-endpoint requests. 370 * </ul> 371 * 372 * <p> 373 * Use {@link #noInherit() @Rest(noInherit={...})} on a mixin class to cut off inheritance for a specific 374 * property — same token set as the host's {@code noInherit} machinery (e.g. {@code "serializers"}, 375 * {@code "guards"}, {@code "messages"}). 376 * 377 * <h4 class='section'>Mixins vs. children</h4> 378 * <p> 379 * Mixins are inline composers that share the host's URL namespace and inherit from the host's resolution chain. 380 * {@link #children() Children} are independently-mounted resources isolated from the host's resolution chain. 381 * See the 382 * <a class="doclink" href="https://juneau.apache.org/docs/topics/RestServerMixinSubContexts#mixin-vs-child-divergence">Mixin-vs-child divergence</a> 383 * topic for the rationale. 384 * 385 * <h4 class='section'>Inheritance Rules</h4> 386 * <ul> 387 * <li>Mixins on child are combined with those on parent class. 388 * <li>Mixins are listed parent-to-child in the order they appear in the annotation. 389 * <li>Transitive mixins ({@code A} mixes in {@code B}) parent-link flat to the host — both {@code A} and 390 * {@code B} get {@code parentContext = host}, never an {@code A → B} chain. 391 * </ul> 392 * 393 * <p> 394 * For host-side per-mixin setting overrides (applying guards / serializers / a mount path / etc. to a 395 * specific mixin's endpoints without editing the mixin class), see the rich {@link #mixinDefs() mixinDefs} 396 * companion attribute. 397 * 398 * <h4 class='section'>See Also:</h4><ul> 399 * <li class='jma'>{@link #mixinDefs()} 400 * <li class='link'><a class="doclink" href="https://juneau.apache.org/docs/topics/RestServerComposition">REST Server — Mixins and Multi-Mount Paths</a> 401 * <li class='link'><a class="doclink" href="https://juneau.apache.org/docs/topics/RestServerMixinSubContexts">REST Server — Mixin Sub-Contexts</a> 402 * </ul> 403 * 404 * @return The annotation value. 405 */ 406 Class<?>[] mixins() default {}; 407 408 /** 409 * Rich mixin definitions — the host-side override form of {@link #mixins()}. 410 * 411 * <p> 412 * Each {@link Mixin @Mixin} entry names a mixin class (via {@link Mixin#type()}) <b>and</b> lets the host 413 * override selected {@code @Rest}-level settings for that mixin's mixed-in endpoints — guards, role 414 * guards, serializers, default headers, mount path, etc. — without subclassing or editing the mixin 415 * class. 416 * 417 * <h4 class='section'>Example:</h4> 418 * <p class='bjava'> 419 * <ja>@Rest</ja>( 420 * mixinDefs=<ja>@Mixin</ja>(type=FooMixin.<jk>class</jk>, guards=AdminGuard.<jk>class</jk>) 421 * ) 422 * <jk>public class</jk> MyResource { ... } 423 * </p> 424 * 425 * <p> 426 * This attribute is additive to {@link #mixins()}: bare-class entries in {@code mixins()} and rich entries 427 * here are discovered together (bare classes first, then {@code mixinDefs}). A {@code @Mixin(type=X.class)} 428 * with no overrides is the exact equivalent of a bare {@code mixins=X.class} entry. 429 * 430 * <h4 class='section'>See Also:</h4><ul> 431 * <li class='ja'>{@link Mixin} 432 * <li class='jm'>{@link #mixins()} 433 * </ul> 434 * 435 * @return The annotation value. 436 * @since 10.0.0 437 */ 438 Mixin[] mixinDefs() default {}; 439 440 /** 441 * Mixin-declared opt-in: fold this class's own {@link #responseProcessors() responseProcessors} into the 442 * <b>host</b> resource's chain whenever this class is composed as a mixin via a plain 443 * {@link #mixins() @Rest(mixins=...)} reference. 444 * 445 * <p> 446 * By default ({@code false}) a mixin's {@code responseProcessors} apply only to the mixin's own endpoints 447 * — a host's own {@code @RestOp} methods see only the host's chain (the standard {@link #mixins() mixin} 448 * inheritance rule "host's chain runs first, then the mixin's appended; host endpoints see only the host's 449 * chain"). Setting this to {@code true} <b>on the mixin class itself</b> makes a plain 450 * {@code @Rest(mixins=ThisClass.class)} reference additionally append this class's own 451 * {@code responseProcessors} to the end of the host's own chain, so the host's own endpoints pick them up too. 452 * 453 * <p> 454 * This is the mixin-declared, response-processor-scoped counterpart to 455 * {@link Mixin#mergeIntoHost() @Mixin(mergeIntoHost=true)} (which is host-declared and folds <i>all</i> 456 * list-shaped attributes). Unlike {@code mergeIntoHost}, this directive lives with the mixin and folds 457 * <b>only</b> {@code responseProcessors} — never {@code guards}, {@code serializers}, or any other 458 * list-shaped attribute. It is intended for view-renderer mixins (e.g. {@code FreemarkerMixin}) so that 459 * declaring the mixin is enough to route the host's own {@code View} returns through the renderer. 460 * 461 * <p> 462 * Strictly opt-in and non-silent: it has no effect for a mixin that leaves it {@code false}, so existing 463 * mixins keep today's scoping exactly. Same-class de-duplication applies, so a response processor the host 464 * already declares is not added twice. 465 * 466 * @return The annotation value. 467 * @since 10.0.0 468 */ 469 boolean mergeResponseProcessorsIntoHost() default false; 470 471 /** 472 * Client version header. 473 * 474 * <p> 475 * Specifies the name of the header used to denote the client version on HTTP requests. 476 * 477 * <h4 class='section'>Notes:</h4><ul> 478 * <li class='note'> 479 * Supports <a class="doclink" href="https://juneau.apache.org/docs/topics/RestServerSvlVariables">REST Server SVL Variables</a> 480 * (e.g. <js>"${L:my.localized.variable}"</js>). 481 * </ul> 482 * 483 * @return The annotation value. 484 */ 485 String clientVersionHeader() default ""; 486 487 /** 488 * Optional location of configuration file for this servlet. 489 * 490 * <p> 491 * The configuration file . 492 * 493 * <h4 class='section'>Inheritance Rules</h4> 494 * <ul> 495 * <li>Config file is searched for in child-to-parent order. 496 * </ul> 497 * 498 * <h4 class='section'>Notes:</h4><ul> 499 * <li class='note'> 500 * Supports <a class="doclink" href="https://juneau.apache.org/docs/topics/RestServerSvlVariables">REST Server SVL Variables</a> 501 * (e.g. <js>"${L:my.localized.variable}"</js>). 502 * <li class='note'> 503 * Use the keyword <c>SYSTEM_DEFAULT</c> to refer to the system default configuration 504 * returned by the {@link Config#getSystemDefault()}. 505 * </ul> 506 * 507 * @return The annotation value. 508 */ 509 String config() default ""; 510 511 /** 512 * Eagerly initializes framework-managed memoizers during {@link RestContext} construction. 513 * 514 * <p> 515 * When enabled, framework bean memoizers and operation/child-context memoizers are force-fired inside the 516 * constructor try/catch so startup-time configuration errors fail fast. 517 * 518 * <p> 519 * This setting is disabled by default. 520 * 521 * <ul class='values'> 522 * <li><js>"true"</js> - Force eager initialization during context construction. 523 * <li><js>"false"</js> - Keep initialization lazy until first use (default). 524 * </ul> 525 * 526 * <h4 class='section'>Notes:</h4><ul> 527 * <li class='note'> 528 * Supports <a class="doclink" href="https://juneau.apache.org/docs/topics/RestServerSvlVariables">REST Server SVL Variables</a> 529 * (e.g. <js>"${L:my.localized.variable}"</js>). 530 * </ul> 531 * 532 * @return The annotation value. 533 */ 534 String eagerInit() default ""; 535 536 /** 537 * Opt this parent resource into deferred (first-invocation) construction of its {@link #children()} sub-resources. 538 * 539 * <p> 540 * When {@code "true"}, the {@link RestContext} instances for all {@code @Rest(children=...)} entries are 541 * <em>not</em> built at parent startup. Instead, each child's routing entry is registered immediately (so URL 542 * matching is fully operational from the first request), but the full {@link RestContext} — including all of its 543 * bean-store setup, memoizers, and lifecycle hooks — is constructed on the first inbound request to that child's 544 * URL prefix. Subsequent requests reuse the already-built context. 545 * 546 * <p> 547 * This is particularly useful when a parent resource exposes heavyweight admin or diagnostic children that are 548 * rarely invoked in production. Setting {@code lazyChildren="true"} on the parent lets the parent boot fast; 549 * each child pays its construction cost only when (and if) it is first accessed. 550 * 551 * <ul class='values'> 552 * <li><js>"true"</js> - Children are constructed on first invocation (deferred). 553 * <li><js>"false"</js> (default) - Children are constructed eagerly at parent startup. 554 * </ul> 555 * 556 * <h4 class='section'>Notes:</h4><ul> 557 * <li class='note'> 558 * The first request to a lazy child pays the full construction cost, which can be significant for 559 * heavyweight children. If predictable first-request latency is required, do not opt in. 560 * <li class='note'> 561 * Concurrent first-requests to the same lazy child are serialized: only one thread runs the construction; 562 * others block until it completes. 563 * <li class='note'> 564 * A lazy child that is never invoked is never constructed. Its lifecycle {@code @RestDestroy} / shutdown 565 * hooks are skipped at parent destruction time. 566 * <li class='note'> 567 * The programmatic knob {@link RestContext.Builder#lazyChildInit(boolean)} overrides this annotation. 568 * <li class='note'> 569 * Supports <a class="doclink" href="https://juneau.apache.org/docs/topics/RestServerSvlVariables">REST Server SVL Variables</a> 570 * (e.g. <js>"${E:LAZY_CHILDREN:false}"</js>). 571 * </ul> 572 * 573 * <h4 class='section'>See Also:</h4><ul> 574 * <li class='jm'>{@link RestContext.Builder#lazyChildInit(boolean)} 575 * <li class='jm'>{@link #children()} 576 * </ul> 577 * 578 * @return The annotation value. 579 */ 580 String lazyChildren() default ""; 581 582 /** 583 * Supported content media types. 584 * 585 * <p> 586 * Overrides the media types inferred from the parsers that identify what media types can be consumed by the resource. 587 * 588 * <h4 class='section'>Notes:</h4><ul> 589 * <li class='note'> 590 * Supports <a class="doclink" href="https://juneau.apache.org/docs/topics/RestServerSvlVariables">REST Server SVL Variables</a> 591 * (e.g. <js>"${L:my.localized.variable}"</js>). 592 * </ul> 593 * 594 * @return The annotation value. 595 */ 596 String[] consumes() default {}; 597 598 /** 599 * Allowed serializer session option keys for this resource (ordered merge, prefix {@code -key} removes a key). 600 * 601 * <p> 602 * Comma-delimited list of session property keys (e.g. <js>"escapeSolidus,maxIndent"</js>) that clients may 603 * send via the <js>"X-Juneau-Serializer-Options"</js> header or <js>"juneauSerializerOptions"</js> query parameter. 604 * Keys not in the effective allowlist cause a {@code 400 Bad Request} response. 605 * 606 * <p> 607 * Entries are merged in application order. A leading hyphen removes a previously added key: <js>"-escapeSolidus"</js>. 608 * Method-level {@link RestGet#allowedSerializerOptions()} values are always merged on top. 609 * Use {@link #noInherit()} to prevent inheriting less-derived contributions. 610 * 611 * <h4 class='section'>See Also:</h4><ul> 612 * <li class='link'><a class="doclink" href="https://juneau.apache.org/docs/topics/SessionOptions#safe-properties">Safe Properties</a> 613 * </ul> 614 * 615 * @return The annotation value. 616 */ 617 String[] allowedSerializerOptions() default {}; 618 619 /** 620 * Allowed parser session option keys for this resource (ordered merge, prefix {@code -key} removes a key). 621 * 622 * <p> 623 * Comma-delimited list of session property keys that clients may send via the <js>"X-Juneau-Parser-Options"</js> 624 * header or <js>"juneauParserOptions"</js> query parameter. Parser options are ignored for operations without 625 * a request-body parser. Keys not in the effective allowlist cause a {@code 400 Bad Request} response. 626 * 627 * <p> 628 * Use {@link #noInherit()} to prevent inheriting less-derived contributions. 629 * 630 * <h4 class='section'>See Also:</h4><ul> 631 * <li class='link'><a class="doclink" href="https://juneau.apache.org/docs/topics/SessionOptions#safe-properties">Safe Properties</a> 632 * </ul> 633 * 634 * @return The annotation value. 635 */ 636 String[] allowedParserOptions() default {}; 637 638 /** 639 * Property names for which less-derived contributions are NOT inherited. 640 * 641 * <p> 642 * Accepted values include {@code "allowedParserOptions"}, {@code "allowedSerializerOptions"}, 643 * {@code "allowedHeaderParams"}, {@code "allowedMethodHeaders"}, {@code "allowedMethodParams"}, 644 * {@code "allowContentParam"}, {@code "renderResponseStackTraces"}, {@code "problemDetails"}, 645 * {@code "debugMarshalling"}, 646 * {@code "eagerInit"}, {@code "lazyChildren"}, {@code "clientVersionHeader"}, 647 * {@code "uriAuthority"}, {@code "uriContext"}, {@code "uriRelativity"}, and {@code "uriResolution"}. 648 * Each entry is SVL-resolved then comma-split. Prevents the named property from inheriting values from 649 * parent {@code @Rest} annotations (router hierarchy). The {@code noInherit} attribute itself is never inherited. 650 * 651 * <h4 class='section'>Mixin sub-contexts (since 10.0.0)</h4> 652 * <p> 653 * On a class declared via {@link #mixins() @Rest(mixins=...)} on a host, {@code noInherit} also blocks the 654 * host-to-mixin inheritance walk for the named property. The token set extends to every contribution list 655 * exposed by {@code @Rest}: {@code "serializers"}, {@code "parsers"}, {@code "encoders"}, {@code "converters"}, 656 * {@code "responseProcessors"}, {@code "restOpArgs"}, {@code "guards"}, 657 * {@code "partSerializer"}, {@code "partParser"}, and 658 * {@code "messages"}. For example, {@code @Rest(noInherit={"guards"})} on a mixin removes the host's guard 659 * chain from the mixin's endpoints (typical pattern for deliberately-unguarded probes like 660 * {@code HealthMixin}). 661 * 662 * <h4 class='section'>See Also:</h4><ul> 663 * <li class='link'><a class="doclink" href="https://juneau.apache.org/docs/topics/SessionOptions">Session Options via HTTP</a> 664 * <li class='link'><a class="doclink" href="https://juneau.apache.org/docs/topics/RestServerMixinSubContexts">REST Server — Mixin Sub-Contexts</a> (for the per-property opt-out semantics) 665 * </ul> 666 * 667 * @return The annotation value. 668 */ 669 String[] noInherit() default {}; 670 671 /** 672 * Class-level response converters. 673 * 674 * <p> 675 * Associates one or more {@link RestConverter converters} with a resource class. 676 * 677 * <h4 class='section'>Inheritance Rules</h4> 678 * <ul> 679 * <li>Converters on child are combined with those on parent class. 680 * <li>Converters are executed child-to-parent in the order they appear in the annotation. 681 * <li>Converters on methods are executed before those on classes. 682 * </ul> 683 * 684 * @return The annotation value. 685 */ 686 Class<? extends RestConverter>[] converters() default {}; 687 688 /** 689 * Default <c>Accept</c> header. 690 * 691 * <p> 692 * The default value for the <c>Accept</c> header if not specified on a request. 693 * 694 * <p> 695 * This is a shortcut for using {@link #defaultRequestHeaders()} for just this specific header. 696 * 697 * <h4 class='section'>Notes:</h4><ul> 698 * <li class='note'> 699 * Supports <a class="doclink" href="https://juneau.apache.org/docs/topics/RestServerSvlVariables">REST Server SVL Variables</a> 700 * (e.g. <js>"${L:my.localized.variable}"</js>). 701 * </ul> 702 * 703 * @return The annotation value. 704 */ 705 String defaultAccept() default ""; 706 707 /** 708 * Default character encoding. 709 * 710 * <p> 711 * The default character encoding for the request and response if not specified on the request. 712 * 713 * <h4 class='section'>Notes:</h4><ul> 714 * <li class='note'> 715 * Supports <a class="doclink" href="https://juneau.apache.org/docs/topics/RestServerSvlVariables">REST Server SVL Variables</a> 716 * (e.g. <js>"${L:my.localized.variable}"</js>). 717 * </ul> 718 * 719 * <h4 class='section'>See Also:</h4><ul> 720 * <li class='ja'>{@link RestOp#defaultCharset} 721 * <li class='ja'>{@link RestGet#defaultCharset} 722 * <li class='ja'>{@link RestPut#defaultCharset} 723 * <li class='ja'>{@link RestPost#defaultCharset} 724 * <li class='ja'>{@link RestDelete#defaultCharset} 725 * </ul> 726 * 727 * @return The annotation value. 728 */ 729 String defaultCharset() default ""; 730 731 /** 732 * Default <c>Content-Type</c> header. 733 * 734 * <p> 735 * The default value for the <c>Content-Type</c> header if not specified on a request. 736 * 737 * <p> 738 * This is a shortcut for using {@link #defaultRequestHeaders()} for just this specific header. 739 * 740 * <h4 class='section'>Notes:</h4><ul> 741 * <li class='note'> 742 * Supports <a class="doclink" href="https://juneau.apache.org/docs/topics/RestServerSvlVariables">REST Server SVL Variables</a> 743 * (e.g. <js>"${L:my.localized.variable}"</js>). 744 * </ul> 745 * 746 * @return The annotation value. 747 */ 748 String defaultContentType() default ""; 749 750 /** 751 * Default request attributes. 752 * 753 * <p> 754 * Specifies default values for request attributes if they're not already set on the request. 755 * 756 * <p> 757 * Affects values returned by the following methods: 758 * <ul> 759 * <li class='jm'>{@link RestRequest#getAttribute(String)}. 760 * <li class='jm'>{@link RestRequest#getAttributes()}. 761 * </ul> 762 * 763 * <h4 class='section'>Example:</h4> 764 * <p class='bjava'> 765 * <jc>// Defined via annotation resolving to a config file setting with default value.</jc> 766 * <ja>@Rest</ja>(defaultRequestAttributes={<js>"Foo=bar"</js>, <js>"Baz: ${C:REST/myAttributeValue}"</js>}) 767 * <jk>public class</jk> MyResource { 768 * 769 * <jc>// Override at the method level.</jc> 770 * <ja>@RestGet</ja>(defaultRequestAttributes={<js>"Foo: bar"</js>}) 771 * <jk>public</jk> Object myMethod() {...} 772 * } 773 * </p> 774 * 775 * <h4 class='section'>Notes:</h4><ul> 776 * <li class='note'> 777 * Supports <a class="doclink" href="https://juneau.apache.org/docs/topics/RestServerSvlVariables">REST Server SVL Variables</a> 778 * (e.g. <js>"${L:my.localized.variable}"</js>). 779 * </ul> 780 * 781 * <h4 class='section'>See Also:</h4><ul> 782 * <li class='ja'>{@link RestOp#defaultRequestAttributes()} 783 * <li class='ja'>{@link RestGet#defaultRequestAttributes()} 784 * <li class='ja'>{@link RestPut#defaultRequestAttributes()} 785 * <li class='ja'>{@link RestPost#defaultRequestAttributes()} 786 * <li class='ja'>{@link RestDelete#defaultRequestAttributes()} 787 * </ul> 788 * 789 * @return The annotation value. 790 */ 791 String[] defaultRequestAttributes() default {}; 792 793 /** 794 * Default request headers. 795 * 796 * <p> 797 * Specifies default values for request headers if they're not passed in through the request. 798 * 799 * <h4 class='section'>Notes:</h4><ul> 800 * <li class='note'> 801 * Supports <a class="doclink" href="https://juneau.apache.org/docs/topics/RestServerSvlVariables">REST Server SVL Variables</a> 802 * (e.g. <js>"${L:my.localized.variable}"</js>). 803 * </ul> 804 * 805 * @return The annotation value. 806 */ 807 String[] defaultRequestHeaders() default {}; 808 809 /** 810 * Default response headers. 811 * 812 * <p> 813 * Specifies default values for response headers if they're not set after the Java REST method is called. 814 * 815 * <h4 class='section'>Notes:</h4><ul> 816 * <li class='note'> 817 * Supports <a class="doclink" href="https://juneau.apache.org/docs/topics/RestServerSvlVariables">REST Server SVL Variables</a> 818 * (e.g. <js>"${L:my.localized.variable}"</js>). 819 * </ul> 820 * 821 * @return The annotation value. 822 */ 823 String[] defaultResponseHeaders() default {}; 824 825 /** 826 * Optional servlet description. 827 * 828 * <p> 829 * It is used to populate the Swagger description field. 830 * 831 * <h4 class='section'>Inheritance Rules</h4> 832 * <ul> 833 * <li>Description is searched for in child-to-parent order. 834 * </ul> 835 * 836 * <h4 class='section'>Notes:</h4><ul> 837 * <li class='note'> 838 * Supports <a class="doclink" href="https://juneau.apache.org/docs/topics/RestServerSvlVariables">REST Server SVL Variables</a> 839 * (e.g. <js>"${L:my.localized.variable}"</js>). 840 * <li class='note'> 841 * The format is plain-text. 842 * <br>Multiple lines are concatenated with newlines. 843 * </ul> 844 * 845 * @return The annotation value. 846 */ 847 String[] description() default {}; 848 849 /** 850 * Allow content URL parameter. 851 * 852 * <p> 853 * When enabled, the HTTP request content on PUT and POST requests can be passed in as text using the 854 * <js>"content"</js> URL parameter, letting a caller exercise an endpoint's body-consuming logic straight from a 855 * URL (handy for a quick manual test or a bookmarked link) without an actual PUT/POST body. 856 * <br> 857 * For example: 858 * <p class='burlenc'> 859 * ?content=(name='John%20Smith',age=45) 860 * </p> 861 * 862 * <p> 863 * This attribute is <jk>false</jk> unless explicitly set, so the override is off by default. 864 * Because the body is supplied through the URL, it bypasses any check an application makes on the request 865 * <c>Content-Type</c> or on custom request headers; only enable it on resources where that is acceptable. 866 * The override is restricted to <c>PUT</c>/<c>POST</c> methods. 867 * 868 * <h4 class='section'>Notes:</h4><ul> 869 * <li class='note'> 870 * Supports <a class="doclink" href="https://juneau.apache.org/docs/topics/RestServerSvlVariables">REST Server SVL Variables</a> 871 * (e.g. <js>"${L:my.localized.variable}"</js>). 872 * </ul> 873 * 874 * @return The annotation value. 875 */ 876 String allowContentParam() default ""; 877 878 /** 879 * Opt the resource into <a class="doclink" href="https://www.rfc-editor.org/rfc/rfc7807">RFC 7807</a> / 880 * <a class="doclink" href="https://www.rfc-editor.org/rfc/rfc9457">RFC 9457</a> 881 * {@code application/problem+json} error responses. 882 * 883 * <p> 884 * When enabled, the resource: 885 * <ul class='spaced-list'> 886 * <li>Emits {@code application/problem+json} for thrown {@code BasicHttpException}s — regardless of the 887 * client's {@code Accept} header. The body is a serialized 888 * {@link org.apache.juneau.bean.rfc7807.Problem} populated from the exception's status code, reason phrase, 889 * and message. 890 * <li>Honors the client's {@code Accept} header on the success path. When a {@code @RestOp} method returns a 891 * {@link org.apache.juneau.bean.rfc7807.Problem} (or throws a 892 * {@link org.apache.juneau.bean.rfc7807.ProblemException}), the 893 * {@link ProblemDetailsProcessor} only serializes it as 894 * {@code application/problem+json} when the {@code Accept} header matches that media type (or {@code */*}). 895 * </ul> 896 * 897 * <ul class='values'> 898 * <li><js>"true"</js> — enable problem-details responses for this resource. 899 * <li><js>"false"</js> — disable problem-details responses for this resource (overrides an inherited 900 * {@code "true"} from a parent {@code @Rest}). 901 * <li><js>""</js> (default) — inherit from the next-most-derived {@code @Rest} in the resource-class 902 * hierarchy. Default behavior (no opt-in anywhere in the chain) is unchanged from prior releases. 903 * </ul> 904 * 905 * <h4 class='section'>Notes:</h4><ul> 906 * <li class='note'> 907 * Supports <a class="doclink" href="https://juneau.apache.org/docs/topics/RestServerSvlVariables">REST Server SVL Variables</a> 908 * (e.g. <js>"${L:my.localized.variable}"</js>). 909 * <li class='note'> 910 * Use {@link #noInherit()} to prevent inheriting an opt-in from a parent {@code @Rest}. 911 * </ul> 912 * 913 * <h4 class='section'>See Also:</h4><ul> 914 * <li class='jc'>{@link org.apache.juneau.bean.rfc7807.Problem} 915 * <li class='jc'>{@link org.apache.juneau.bean.rfc7807.ProblemException} 916 * <li class='jc'>{@link ProblemDetailsProcessor} 917 * </ul> 918 * 919 * @return The annotation value. 920 */ 921 String problemDetails() default ""; 922 923 /** 924 * Opt the resource into REST-driven serializer/parser debug behavior. 925 * 926 * <p> 927 * When enabled, the REST layer forces {@code Context.debug} on the serializer/parser sessions it creates to handle 928 * requests for this resource — engaging recursion-detection-that-throws (a genuine cycle throws 929 * {@code MarshallingRecursionException} instead of being size-guard-truncated), parse-input buffering (parse errors 930 * can quote the offending input), and stack-trace-prefixed marshalling exceptions. 931 * 932 * <p> 933 * This is a <b>behavior</b> switch, independent of the JUL logger level: raising a logger to 934 * {@link java.util.logging.Level#FINE FINE}/{@link java.util.logging.Level#FINEST FINEST} changes logging verbosity 935 * only and never changes marshalling behavior. A serializer/parser configured with {@code Context.debug} directly 936 * is unaffected by this setting. 937 * 938 * <ul class='values'> 939 * <li><js>"true"</js> — enable marshalling debug for this resource. 940 * <li><js>"false"</js> — disable marshalling debug for this resource (overrides an inherited 941 * {@code "true"} from a parent {@code @Rest}). 942 * <li><js>""</js> (default) — inherit from the next-most-derived {@code @Rest} in the resource-class 943 * hierarchy. Default behavior (no opt-in anywhere in the chain) is marshalling debug OFF. 944 * </ul> 945 * 946 * <h4 class='section'>Notes:</h4><ul> 947 * <li class='note'> 948 * Supports <a class="doclink" href="https://juneau.apache.org/docs/topics/RestServerSvlVariables">REST Server SVL Variables</a> 949 * (e.g. <js>"${L:my.localized.variable}"</js>). 950 * <li class='note'> 951 * Use {@link #noInherit()} to prevent inheriting an opt-in from a parent {@code @Rest}. 952 * </ul> 953 * 954 * @return The annotation value. 955 */ 956 String debugMarshalling() default ""; 957 958 /** 959 * Opt this resource into per-request virtual-thread dispatch (Java 21+). 960 * 961 * <p> 962 * When enabled, every {@code @RestOp}-annotated handler invocation on this resource is submitted to a 963 * {@code Executors.newVirtualThreadPerTaskExecutor()} virtual-thread-per-task executor 964 * lazily built by the {@link RestContext}. The platform request thread blocks on 965 * the virtual thread's completion (so the handler's return value, exceptions, and observability hooks are 966 * preserved verbatim), but blocking I/O inside the handler now parks a virtual thread instead of the 967 * carrier — i.e. the carrier thread is freed to service other concurrent requests while the handler is 968 * parked on socket / file / lock waits. Combined with {@link java.util.concurrent.CompletableFuture} 969 * return types ({@code @RestGet} / {@code @RestPost} returning {@code CompletableFuture<T>}) this is the 970 * high-throughput pattern. 971 * 972 * <p> 973 * <b>Graceful degradation on Java 17/18/19/20:</b> the flag is detected during {@code RestContext} 974 * initialization. If the runtime is older than Java 21, a one-shot {@code WARNING} is logged and the 975 * resource falls back to the standard caller-thread dispatch path — no runtime error. 976 * 977 * <p> 978 * Per-{@code @RestOp} overrides are available via {@link RestOp#virtualThreads()}; the op-level setting 979 * takes precedence over the resource-level setting. 980 * 981 * <ul class='values'> 982 * <li><js>"true"</js> — enable virtual-thread dispatch on Java 21+ (silently disabled on older JVMs). 983 * <li><js>"false"</js> — explicitly disable. 984 * <li><js>""</js> (default) — inherit from the next-most-derived {@code @Rest} in the resource-class 985 * hierarchy. 986 * </ul> 987 * 988 * <h4 class='section'>Notes:</h4><ul> 989 * <li class='note'> 990 * Supports <a class="doclink" href="https://juneau.apache.org/docs/topics/RestServerSvlVariables">REST Server SVL Variables</a> 991 * (e.g. <js>"${E:ENABLE_VIRTUAL_THREADS:false}"</js>). 992 * <li class='note'> 993 * Synchronized blocks and JNI calls in handler code <i>pin</i> a virtual thread to its carrier thread 994 * — prefer {@link java.util.concurrent.locks.ReentrantLock} over {@code synchronized} in handlers run 995 * under this flag. 996 * </ul> 997 * 998 * <h4 class='section'>See Also:</h4><ul> 999 * <li class='ja'>{@link RestOp#virtualThreads()} 1000 * </ul> 1001 * 1002 * @return The annotation value. 1003 */ 1004 String virtualThreads() default ""; 1005 1006 /** 1007 * Per-resource observability opt-in / opt-out control. 1008 * 1009 * <p> 1010 * Controls whether the observability block ({@link org.apache.juneau.rest.server.metrics.MetricsRecorder} / 1011 * {@link org.apache.juneau.rest.server.tracing.TracerHook}) fires for operations on this resource. 1012 * Per-operation overrides are available via {@link RestOp#observability()} (and the verb annotations). 1013 * 1014 * <ul class='values'> 1015 * <li><js>"true"</js> — strict opt-in: the resource <em>requires</em> a wired observability backend. 1016 * If neither a {@code @Bean MetricsRecorder} nor a {@code @Bean TracerHook} is registered when the 1017 * {@link RestContext} is built, construction fails with a precise error. 1018 * All operations on this resource have observability enabled. 1019 * <li><js>"false"</js> — explicit opt-out: the observability block is short-circuited for every 1020 * operation on this resource, even when a wired backend is present. Also suppresses 1021 * {@link org.apache.juneau.rest.server.tracing.TraceContextResponseProcessor} header injection for this resource. 1022 * <li><js>""</js> (default) — inherits the existing behavior: the observability block runs per-op, 1023 * but a missing {@code @Bean} silently falls back to the NoOp singleton — no startup error. 1024 * </ul> 1025 * 1026 * <h4 class='section'>Notes:</h4><ul> 1027 * <li class='note'> 1028 * Supports <a class="doclink" href="https://juneau.apache.org/docs/topics/RestServerSvlVariables">REST Server SVL Variables</a> 1029 * (e.g. <js>"${E:ENABLE_OBSERVABILITY:false}"</js>). 1030 * <li class='note'> 1031 * Per-operation overrides via {@link RestOp#observability()} (or verb annotations) take precedence over 1032 * this resource-level setting. 1033 * </ul> 1034 * 1035 * <h4 class='section'>See Also:</h4><ul> 1036 * <li class='ja'>{@link RestOp#observability()} 1037 * <li class='jc'>{@link org.apache.juneau.rest.server.metrics.MetricsRecorder} 1038 * <li class='jc'>{@link org.apache.juneau.rest.server.tracing.TracerHook} 1039 * <li class='link'><a class="doclink" href="https://juneau.apache.org/docs/topics/RestServerObservability">Observability — Micrometer + OpenTelemetry</a> 1040 * </ul> 1041 * 1042 * @return The annotation value. 1043 * @since 10.0.0 1044 */ 1045 String observability() default ""; 1046 1047 /** 1048 * Configurable timeout (milliseconds) applied to {@link java.util.concurrent.CompletableFuture}-returning 1049 * handlers by {@link AsyncResponseProcessor}. Default is 30,000 ms. 1050 * 1051 * <p> 1052 * On timeout, the future is cancelled with {@code mayInterruptIfRunning=true} and the response is 1053 * committed as {@code 504 Gateway Timeout}. Set to {@code "0"} to disable the timeout entirely. 1054 * 1055 * <p> 1056 * Per-{@code @RestOp} overrides are available via {@link RestOp#asyncTimeoutMillis()}; the op-level 1057 * setting takes precedence over the resource-level setting. 1058 * 1059 * <h4 class='section'>Notes:</h4><ul> 1060 * <li class='note'> 1061 * Supports <a class="doclink" href="https://juneau.apache.org/docs/topics/RestServerSvlVariables">REST Server SVL Variables</a> 1062 * (e.g. <js>"${E:ASYNC_TIMEOUT_MS:30000}"</js>). 1063 * </ul> 1064 * 1065 * <h4 class='section'>See Also:</h4><ul> 1066 * <li class='jc'>{@link AsyncResponseProcessor} 1067 * <li class='ja'>{@link RestOp#asyncTimeoutMillis()} 1068 * </ul> 1069 * 1070 * @return The annotation value. 1071 * @since 10.0.0 1072 */ 1073 String asyncTimeoutMillis() default ""; 1074 1075 /** 1076 * Names the {@link java.util.concurrent.Executor} bean used to route {@link java.util.concurrent.CompletableFuture} 1077 * completion callbacks through a dedicated thread pool. 1078 * 1079 * <p> 1080 * When set, the {@link AsyncResponseProcessor} switches from 1081 * {@code future.whenComplete(callback)} to {@code future.whenCompleteAsync(callback, executor)}, so the 1082 * response-handler work runs on the named pool instead of the future's natural completion thread (often an 1083 * I/O-driver or database-callback thread). 1084 * 1085 * <p> 1086 * The value is the {@link org.apache.juneau.commons.inject.Bean#name() @Bean(name=...)} lookup key for an 1087 * {@link java.util.concurrent.Executor} registered in the resource's bean store. Empty string (default) 1088 * means no override — completion callbacks run on the future's natural thread (the existing behavior). 1089 * 1090 * <h4 class='section'>Example:</h4> 1091 * <p class='bjava'> 1092 * <ja>@Rest</ja>(path=<js>"/api"</js>, asyncCompletionExecutor=<js>"myCompletionPool"</js>) 1093 * <jk>public class</jk> ApiResource <jk>extends</jk> RestServlet { 1094 * 1095 * <ja>@Bean</ja>(name=<js>"myCompletionPool"</js>) 1096 * <jk>public</jk> Executor completionPool() { 1097 * <jk>return</jk> Executors.newFixedThreadPool(8); 1098 * } 1099 * 1100 * <ja>@RestGet</ja>(<js>"/orders/{id}"</js>) 1101 * <jk>public</jk> CompletableFuture<Order> getOrder(<ja>@Path</ja> String id) { 1102 * <jk>return</jk> orderService.fetchAsync(id); <jc>// callback runs on myCompletionPool</jc> 1103 * } 1104 * } 1105 * </p> 1106 * 1107 * <p> 1108 * Per-operation overrides are available via {@link RestOp#asyncCompletionExecutor()} (and the verb annotations). 1109 * A reference to a bean name that does not resolve in the bean store causes a startup failure. 1110 * 1111 * <h4 class='section'>Notes:</h4><ul> 1112 * <li class='note'> 1113 * MDC propagation still works when this executor is set — the 1114 * {@link MdcAsyncListener} wraps the callback <em>before</em> it is 1115 * routed through the executor, so the MDC snapshot is restored on whichever thread the executor picks. 1116 * </ul> 1117 * 1118 * <h4 class='section'>See Also:</h4><ul> 1119 * <li class='jc'>{@link AsyncResponseProcessor} 1120 * <li class='ja'>{@link RestOp#asyncCompletionExecutor()} 1121 * </ul> 1122 * 1123 * @return The annotation value. 1124 * @since 10.0.0 1125 */ 1126 String asyncCompletionExecutor() default ""; 1127 1128 /** 1129 * Specifies the compression encoders for this resource. 1130 * 1131 * <p> 1132 * Encoders are used to enable various kinds of compression (e.g. <js>"gzip"</js>) on requests and responses. 1133 * 1134 * <p> 1135 * Encoders are automatically inherited from {@link Rest#encoders()} annotations on parent classes with the encoders on child classes 1136 * prepended to the encoder group. 1137 * The {@link org.apache.juneau.marshall.encoders.EncoderSet.NoInherit EncoderSet.NoInherit} class can be used to prevent inheriting from the parent class. 1138 * 1139 * <h4 class='section'>Example:</h4> 1140 * <p class='bjava'> 1141 * <jc>// Define a REST resource that handles GZIP compression.</jc> 1142 * <ja>@Rest</ja>( 1143 * encoders={ 1144 * GzipEncoder.<jk>class</jk> 1145 * } 1146 * ) 1147 * <jk>public class</jk> MyResource { 1148 * ... 1149 * } 1150 * </p> 1151 * 1152 * <p> 1153 * The encoders can also be tailored at the method level using {@link RestOp#encoders()} (and related annotations). 1154 * 1155 * <p> 1156 * For programmatic equivalents, contribute an {@link EncoderSet} bean via 1157 * {@link org.apache.juneau.commons.inject.Bean @Bean(name="encoders")}. 1158 * 1159 * <h4 class='section'>Inheritance Rules</h4> 1160 * <ul> 1161 * <li>Encoders on child are combined with those on parent class. 1162 * </ul> 1163 * 1164 * <h4 class='section'>See Also:</h4><ul> 1165 * <li class='link'><a class="doclink" href="https://juneau.apache.org/docs/topics/RestServerEncoders">Encoders in REST servers</a> 1166 * </ul> 1167 * 1168 * @return The annotation value. 1169 */ 1170 Class<? extends Encoder>[] encoders() default {}; 1171 1172 /** 1173 * Default form data parameter definitions. 1174 * 1175 * <p> 1176 * Provides default values for {@link FormData @FormData} annotations on method parameters across all methods in this class. 1177 * 1178 * <h4 class='section'>Example:</h4> 1179 * <p class='bjava'> 1180 * <ja>@Rest</ja>( 1181 * formDataParams={ 1182 * <ja>@FormData</ja>(name=<js>"action"</js>, def=<js>"submit"</js>) 1183 * } 1184 * ) 1185 * <jk>public class</jk> MyResource {...} 1186 * </p> 1187 * 1188 * @return The annotation value. 1189 * @since 9.2.0 1190 */ 1191 FormData[] formDataParams() default {}; 1192 1193 /** 1194 * Class-level guards. 1195 * 1196 * <p> 1197 * Associates one or more {@link RestGuard RestGuards} with all REST methods defined in this class. 1198 * 1199 * <h4 class='section'>Inheritance Rules</h4> 1200 * <ul> 1201 * <li>Guards on child are combined with those on parent class. 1202 * <li>Guards are executed child-to-parent in the order they appear in the annotation. 1203 * <li>Guards on methods are executed before those on classes. 1204 * </ul> 1205 * 1206 * @return The annotation value. 1207 */ 1208 Class<? extends RestGuard>[] guards() default {}; 1209 1210 /** 1211 * Default header parameter definitions. 1212 * 1213 * <p> 1214 * Provides default values for {@link Header @Header} annotations on method parameters across all methods in this class. 1215 * 1216 * <h4 class='section'>Example:</h4> 1217 * <p class='bjava'> 1218 * <ja>@Rest</ja>( 1219 * headerParams={ 1220 * <ja>@Header</ja>(name=<js>"Accept-Language"</js>, def=<js>"en-US"</js>), 1221 * <ja>@Header</ja>(name=<js>"X-API-Version"</js>, def=<js>"1.0"</js>) 1222 * } 1223 * ) 1224 * <jk>public class</jk> MyResource {...} 1225 * </p> 1226 * 1227 * @return The annotation value. 1228 * @since 9.2.0 1229 */ 1230 Header[] headerParams() default {}; 1231 1232 /** 1233 * The maximum allowed input size (in bytes) on HTTP requests. 1234 * 1235 * <p> 1236 * Useful for alleviating DoS attacks by throwing an exception when too much input is received instead of resulting 1237 * in out-of-memory errors which could affect system stability. 1238 * 1239 * <p> 1240 * Applies uniformly across body-reading paths, including {@code multipart/form-data} uploads: a request whose 1241 * declared {@code Content-Length} or parsed part sizes exceed this ceiling is rejected with a {@code 413} 1242 * response before (or as soon as) the oversized content would otherwise be buffered. 1243 * 1244 * <h4 class='section'>Notes:</h4><ul> 1245 * <li class='note'> 1246 * Supports <a class="doclink" href="https://juneau.apache.org/docs/topics/RestServerSvlVariables">REST Server SVL Variables</a> 1247 * (e.g. <js>"${L:my.localized.variable}"</js>). 1248 * <li class='note'> 1249 * A value of zero or less is treated as the default (1,000,000 bytes), not as unlimited. 1250 * <li class='note'> 1251 * For {@code multipart/form-data} requests the per-part and per-request size limits, and the in-memory threshold 1252 * before parts spill to disk, come from the servlet container's {@code MultipartConfigElement} (for example 1253 * {@code maxFileSize}, {@code maxRequestSize} and {@code fileSizeThreshold}); configure them there as well. 1254 * </ul> 1255 * 1256 * <h4 class='section'>See Also:</h4><ul> 1257 * <li class='ja'>{@link RestOp#maxInput} 1258 * <li class='ja'>{@link RestPost#maxInput} 1259 * <li class='ja'>{@link RestPut#maxInput} 1260 * </ul> 1261 * 1262 * @return The annotation value. 1263 */ 1264 String maxInput() default ""; 1265 1266 /** 1267 * Messages. 1268 * 1269 * Identifies the location of the resource bundle for this class. 1270 * 1271 * <p> 1272 * There are two possible formats: 1273 * <ul> 1274 * <li>A simple string - Represents the {@link org.apache.juneau.marshall.cp.Messages.Builder#name(String) name} of the resource bundle. 1275 * <br><br><i>Example:</i> 1276 * <p class='bjava'> 1277 * <jc>// Bundle name is Messages.properties.</jc> 1278 * <ja>@Rest</ja>(messages=<js>"Messages"</js>) 1279 * </p> 1280 * <li>Simplified JSON - Represents parameters for the {@link org.apache.juneau.marshall.cp.Messages.Builder} class. 1281 * <br><br><i>Example:</i> 1282 * <p class='bjava'> 1283 * <jc>// Bundles can be found in two packages.</jc> 1284 * <ja>@Rest</ja>(messages=<js>"{name:'Messages',baseNames:['{package}.{name}','{package}.i18n.{name}']"</js>) 1285 * </p> 1286 * </ul> 1287 * 1288 * <p> 1289 * If the bundle name is not specified, the class name of the resource object is used. 1290 * 1291 * <h4 class='section'>Notes:</h4><ul> 1292 * <li class='note'> 1293 * Supports <a class="doclink" href="https://juneau.apache.org/docs/topics/RestServerSvlVariables">REST Server SVL Variables</a> 1294 * (e.g. <js>"${L:my.localized.variable}"</js>). 1295 * </ul> 1296 * 1297 * @return The annotation value. 1298 */ 1299 String messages() default ""; 1300 1301 /** 1302 * Specifies the parsers for converting HTTP request bodies into POJOs. 1303 * 1304 * <p> 1305 * Parsers are used to convert the content of HTTP requests into POJOs. 1306 * <br>Any of the Juneau framework parsers can be used in this setting. 1307 * <br>The parser selected is based on the request <c>Content-Type</c> header matched against the values returned by the following method 1308 * using a best-match algorithm: 1309 * <ul class='javatree'> 1310 * <li class='jm'>{@link Parser#getMediaTypes()} 1311 * </ul> 1312 * 1313 * <p> 1314 * Parsers are automatically inherited from {@link Rest#parsers()} annotations on parent classes with the parsers on child classes 1315 * prepended to the parser group. 1316 * The {@link org.apache.juneau.marshall.parser.ParserSet.NoInherit ParserSet.NoInherit} class can be used to prevent inheriting from the parent class. 1317 * 1318 * <h4 class='section'>Example:</h4> 1319 * <p class='bjava'> 1320 * <jc>// Define a REST resource that can consume JSON and XML.</jc> 1321 * <ja>@Rest</ja>( 1322 * parsers={ 1323 * JsonParser.<jk>class</jk>, 1324 * XmlParser.<jk>class</jk> 1325 * } 1326 * ) 1327 * <jk>public class</jk> MyResource { 1328 * ... 1329 * } 1330 * </p> 1331 * 1332 * <p> 1333 * The parsers can also be tailored at the method level using {@link RestOp#parsers()} (and related annotations). 1334 * 1335 * <p> 1336 * For programmatic equivalents, contribute a {@link ParserSet} bean via 1337 * {@link org.apache.juneau.commons.inject.Bean @Bean(name="parsers")}. 1338 * 1339 * <h4 class='section'>Inheritance Rules</h4> 1340 * <ul> 1341 * <li>Parsers on child override those on parent class. 1342 * <li>{@link org.apache.juneau.marshall.parser.ParserSet.Inherit ParserSet.Inherit} class can be used to inherit and augment values from parent. 1343 * <li>{@link org.apache.juneau.marshall.parser.ParserSet.NoInherit ParserSet.NoInherit} class can be used to suppress inheriting from parent. 1344 * <li>Parsers on methods take precedence over those on classes. 1345 * </ul> 1346 * 1347 * <h4 class='section'>See Also:</h4><ul> 1348 * <li class='link'><a class="doclink" href="https://juneau.apache.org/docs/topics/Marshalling">Marshalling</a> 1349 * </ul> 1350 * 1351 * @return The annotation value. 1352 */ 1353 Class<?>[] parsers() default {}; 1354 1355 /** 1356 * HTTP part parser. 1357 * 1358 * <p> 1359 * Specifies the {@link HttpPartParser} to use for parsing headers, query/form parameters, and URI parts. 1360 * 1361 * @return The annotation value. 1362 */ 1363 Class<? extends HttpPartParser> partParser() default HttpPartParser.Void.class; 1364 1365 /** 1366 * HTTP part serializer. 1367 * 1368 * <p> 1369 * Specifies the {@link HttpPartSerializer} to use for serializing headers, query/form parameters, and URI parts. 1370 * 1371 * @return The annotation value. 1372 */ 1373 Class<? extends HttpPartSerializer> partSerializer() default HttpPartSerializer.Void.class; 1374 1375 /** 1376 * Resource path. 1377 * 1378 * <p> 1379 * Used in the following situations: 1380 * <ul class='spaced-list'> 1381 * <li> 1382 * On child resources (resource classes attached to parents via the {@link #children()} annotation) to identify 1383 * the subpath used to access the child resource relative to the parent. 1384 * <li> 1385 * On top-level {@link RestServlet} classes deployed as Spring beans when <c>JuneauRestInitializer</c> is being used. 1386 * </ul> 1387 * 1388 * <h4 class='topic'>On child resources</h4> 1389 * <p> 1390 * The typical usage is to define a path to a child resource relative to the parent resource. 1391 * 1392 * <h4 class='figure'>Example:</h4> 1393 * <p class='bjava'> 1394 * <ja>@Rest</ja>( 1395 * children={ChildResource.<jk>class</jk>} 1396 * ) 1397 * <jk>public class</jk> TopLevelResource <jk>extends</jk> BasicRestServlet {...} 1398 * 1399 * <ja>@Rest</ja>( 1400 * path=<js>"/child"</js>, 1401 * children={GrandchildResource.<jk>class</jk>} 1402 * ) 1403 * <jk>public class</jk> ChildResource {...} 1404 * 1405 * <ja>@Rest</ja>( 1406 * path=<js>"/grandchild"</js> 1407 * ) 1408 * <jk>public class</jk> GrandchildResource { 1409 * <ja>@RestGet</ja>(<js>"/"</js>) 1410 * <jk>public</jk> String sayHello() { 1411 * <jk>return</jk> <js>"Hello!"</js>; 1412 * } 1413 * } 1414 * </p> 1415 * <p> 1416 * In the example above, assuming the <c>TopLevelResource</c> servlet is deployed to path <c>/myContext/myServlet</c>, 1417 * then the <c>sayHello</c> method is accessible through the URI <c>/myContext/myServlet/child/grandchild</c>. 1418 * 1419 * <p> 1420 * Note that in this scenario, the <c>path</c> attribute is not defined on the top-level resource. 1421 * Specifying the path on the top-level resource has no effect, but can be used for readability purposes. 1422 * 1423 * <h4 class='topic'>Path variables</h4> 1424 * <p> 1425 * The path can contain variables that get resolved to {@link Path @Path} parameters 1426 * or access through the {@link RestRequest#getPathParams()} method. 1427 * 1428 * <h4 class='figure'>Example:</h4> 1429 * <p class='bjava'> 1430 * <ja>@Rest</ja>( 1431 * path=<js>"/myResource/{foo}/{bar}"</js> 1432 * ) 1433 * <jk>public class</jk> MyResource <jk>extends</jk> BasicRestServlet { 1434 * 1435 * <ja>@RestGet</ja>(<js>"/{baz}"</js>) 1436 * <jk>public void</jk> String doX(<ja>@Path</ja> String <jv>foo</jv>, <ja>@Path</ja> <jk>int</jk> <jv>bar</jv>, <ja>@Path</ja> MyPojo <jv>baz</jv>) { 1437 * ... 1438 * } 1439 * } 1440 * </p> 1441 * 1442 * <p> 1443 * Variables can be used on either top-level or child resources and can be defined on multiple levels. 1444 * 1445 * <p> 1446 * All variables in the path must be specified or else the target will not resolve and a <c>404</c> will result. 1447 * 1448 * <p> 1449 * When variables are used on a path of a top-level resource deployed as a Spring bean in a Spring Boot application, 1450 * the first part of the URL must be a literal which will be used as the servlet path of the registered servlet. 1451 * 1452 * <h4 class='section'>Notes:</h4><ul> 1453 * <li class='note'> 1454 * The leading slash is optional. <js>"/myResource"</js> and <js>"myResource"</js> is equivalent. 1455 * <li class='note'> 1456 * The paths <js>"/myResource"</js> and <js>"/myResource/*"</js> are equivalent. 1457 * <li class='note'> 1458 * Paths must not end with <js>"/"</js> (per the servlet spec). 1459 * <li class='note'> 1460 * Effective only when this class is registered directly with the servlet container as a top-level 1461 * resource. When this class is imported as a mixin via {@code @Rest(mixins=...)}, the importing 1462 * host's own {@code path()} or {@link #paths()} governs the mount and this annotation is silently 1463 * ignored — mixin endpoints land in the host's URL namespace. 1464 * </ul> 1465 * 1466 * <h4 class='section'>Inheritance Rules</h4> 1467 * <ul> 1468 * <li>Path is searched for in child-to-parent order. 1469 * </ul> 1470 * 1471 * @return The annotation value. 1472 */ 1473 String path() default ""; 1474 1475 /** 1476 * Additional servlet mount paths. 1477 * 1478 * <p> 1479 * Optional multi-mount companion to {@link #path()} for top-level servlet deployment. 1480 * 1481 * <p> 1482 * When specified, servlet containers may mount this resource on each listed path. 1483 * This is primarily intended for built-in support endpoints such as health probes where multiple exact URLs 1484 * should be served by a single servlet instance. 1485 * 1486 * <h4 class='section'>Runtime substitution (since 10.0.0)</h4> 1487 * <p> 1488 * Each array element is treated as a template: 1489 * <ol> 1490 * <li>The element runs through 1491 * <a class="doclink" href="https://juneau.apache.org/docs/topics/RestServerSvlVariables">REST Server SVL Variables</a> 1492 * variable substitution (e.g. {@code ${C:health.paths}}, {@code ${E:HEALTH_PATHS:/healthz}}, 1493 * {@code ${S:my.system.prop:/healthz}}) using the bootstrap {@link org.apache.juneau.commons.svl.VarResolver 1494 * VarResolver} on the bean store. 1495 * <li>The post-SVL value is split on {@code ,}; each piece is trimmed and empty pieces are dropped. 1496 * A single template element can therefore expand to zero, one, or many mount paths. 1497 * </ol> 1498 * 1499 * <h4 class='figure'>Examples:</h4> 1500 * <p class='bjava'> 1501 * <jc>// 1. Single key resolving to a multi-value config string.</jc> 1502 * <ja>@Rest</ja>(paths={<js>"${C:health.paths}"</js>}) 1503 * 1504 * <jc>// 2. Mix literal + resolved element.</jc> 1505 * <ja>@Rest</ja>(paths={<js>"/api"</js>, <js>"${C:extra.paths}"</js>}) 1506 * 1507 * <jc>// 3. Env var with comma-separated defaults baked in.</jc> 1508 * <ja>@Rest</ja>(paths={<js>"${E:HEALTH_PATHS:/healthz,/readyz}"</js>}) 1509 * </p> 1510 * 1511 * <h4 class='section'>Notes:</h4><ul> 1512 * <li class='note'> 1513 * Paths are normalized to servlet path-specs by the hosting runtime. 1514 * <li class='note'> 1515 * When both {@link #path()} and {@link #paths()} are present, runtimes may use {@link #paths()} for 1516 * top-level mounting and continue using {@link #path()} for child-resource composition. 1517 * <li class='note'> 1518 * The annotation default sits at the lowest rung of the runtime-override resolution chain — see 1519 * {@link RestContext#getPaths()} for the full precedence order (programmatic > getter > annotation). 1520 * <li class='note'> 1521 * An SVL failure (unresolved variable with no default) falls back to the literal element rather than 1522 * throwing during construction. 1523 * <li class='note'> 1524 * Effective only when this class is registered directly with the servlet container as a top-level 1525 * resource. When this class is imported as a mixin via {@code @Rest(mixins=...)}, the importing 1526 * host's own {@link #path()} or {@code paths()} governs the mount and this annotation is silently 1527 * ignored — mixin endpoints land in the host's URL namespace. 1528 * </ul> 1529 * 1530 * @return The annotation value. 1531 */ 1532 String[] paths() default {}; 1533 1534 /** 1535 * Default path parameter definitions. 1536 * 1537 * <p> 1538 * Provides default values for {@link Path @Path} annotations on method parameters across all methods in this class. 1539 * 1540 * <h4 class='section'>Example:</h4> 1541 * <p class='bjava'> 1542 * <ja>@Rest</ja>( 1543 * pathParams={ 1544 * <ja>@Path</ja>(name=<js>"version"</js>, def=<js>"v1"</js>) 1545 * } 1546 * ) 1547 * <jk>public class</jk> MyResource {...} 1548 * </p> 1549 * 1550 * @return The annotation value. 1551 * @since 9.2.0 1552 */ 1553 Path[] pathParams() default {}; 1554 1555 /** 1556 * Supported accept media types. 1557 * 1558 * <p> 1559 * Overrides the media types inferred from the serializers that identify what media types can be produced by the resource. 1560 * 1561 * <h4 class='section'>Notes:</h4><ul> 1562 * <li class='note'> 1563 * Supports <a class="doclink" href="https://juneau.apache.org/docs/topics/RestServerSvlVariables">REST Server SVL Variables</a> 1564 * (e.g. <js>"${L:my.localized.variable}"</js>). 1565 * </ul> 1566 * 1567 * @return The annotation value. 1568 */ 1569 String[] produces() default {}; 1570 1571 /** 1572 * Default query parameter definitions. 1573 * 1574 * <p> 1575 * Provides default values for {@link Query @Query} annotations on method parameters across all methods in this class. 1576 * Values specified here are used as defaults when the same property is not explicitly defined on a method parameter's 1577 * {@link Query @Query} annotation. 1578 * 1579 * <h4 class='section'>Example:</h4> 1580 * <p class='bjava'> 1581 * <jc>// Define common query parameters at class level</jc> 1582 * <ja>@Rest</ja>( 1583 * queryParams={ 1584 * <ja>@Query</ja>(name=<js>"format"</js>, def=<js>"json"</js>, description=<js>"Output format"</js>), 1585 * <ja>@Query</ja>(name=<js>"verbose"</js>, def=<js>"false"</js>, schema=<ja>@Schema</ja>(type=<js>"boolean"</js>)) 1586 * } 1587 * ) 1588 * <jk>public class</jk> MyResource { 1589 * 1590 * <jc>// Method will inherit the default query parameter definitions</jc> 1591 * <ja>@RestGet</ja> 1592 * <jk>public</jk> String doGet(<ja>@Query</ja>(<js>"format"</js>) String format, <ja>@Query</ja>(<js>"verbose"</js>) <jk>boolean</jk> verbose) {...} 1593 * 1594 * <jc>// Can override defaults on a per-method basis</jc> 1595 * <ja>@RestGet</ja> 1596 * <jk>public</jk> String doGet2(<ja>@Query</ja>(name=<js>"format"</js>, def=<js>"xml"</js>) String format) {...} 1597 * } 1598 * </p> 1599 * 1600 * <h4 class='section'>Notes:</h4><ul> 1601 * <li class='note'> 1602 * These defaults apply to validation, parsing, and OpenAPI/Swagger documentation generation. 1603 * <li class='note'> 1604 * Method-level {@link Query @Query} annotations take precedence over class-level definitions. 1605 * <li class='note'> 1606 * The {@link Query#name() name} attribute must be specified for each query definition. 1607 * </ul> 1608 * 1609 * @return The annotation value. 1610 * @since 9.2.0 1611 */ 1612 Query[] queryParams() default {}; 1613 1614 /** 1615 * Render response stack traces in responses. 1616 * 1617 * <p> 1618 * Render stack traces in HTTP response bodies when errors occur. 1619 * 1620 * <p> 1621 * Off by default. Besides the stack trace itself, this same setting also determines whether the 1622 * {@code Thrown} response header is set and whether an error whose exception type wasn't deliberately 1623 * thrown by application code (i.e. not a {@link org.apache.juneau.http.response.BasicHttpException 1624 * BasicHttpException} or one of its subclasses) has its class name/message echoed into the error body. 1625 * Leave this off in production so that an unplanned exception type (a database driver error, a 1626 * file-system exception, and the like) can't incidentally leak implementation detail to the caller; 1627 * turn it on only for local debugging. 1628 * 1629 * <h4 class='section'>Notes:</h4><ul> 1630 * <li class='note'> 1631 * Supports <a class="doclink" href="https://juneau.apache.org/docs/topics/RestServerSvlVariables">REST Server SVL Variables</a> 1632 * (e.g. <js>"${L:my.localized.variable}"</js>). 1633 * </ul> 1634 * 1635 * @return The annotation value. 1636 */ 1637 String renderResponseStackTraces() default ""; 1638 1639 /** 1640 * Response processors. 1641 * 1642 * <p> 1643 * Specifies a list of {@link ResponseProcessor} classes that know how to convert POJOs returned by REST methods or 1644 * set via {@link RestResponse#setContent(Object)} into appropriate HTTP responses. 1645 * 1646 * <p> 1647 * These processors run in order and are the extension point that turns a method's return value into the response 1648 * body. The built-in {@link SerializedPojoProcessor} is the default POJO handler — it runs the 1649 * content-negotiated {@link #serializers() serializer}, so for ordinary POJO returns the effective response format 1650 * is governed by serializer ordering and the request <c>Accept</c> header (see {@link #serializers()}), not by this 1651 * list. 1652 * 1653 * <p> 1654 * A custom view-renderer {@link ResponseProcessor} installed here (for example a template-rendering processor 1655 * contributed by a view mixin — see {@link #mergeResponseProcessorsIntoHost()}) can instead claim a return 1656 * value and render it directly (e.g. as HTML from a template) before serializer negotiation is reached, changing the 1657 * effective response for the returns it handles. 1658 * 1659 * @return The annotation value. 1660 */ 1661 Class<? extends ResponseProcessor>[] responseProcessors() default {}; 1662 1663 /** 1664 * Java REST operation method parameter resolvers. 1665 * 1666 * <p> 1667 * By default, the Juneau framework will automatically Java method parameters of various types (e.g. 1668 * <c>RestRequest</c>, <c>Accept</c>, <c>Reader</c>). 1669 * <br>This setting allows you to provide your own resolvers for your own class types that you want resolved. 1670 * 1671 * @return The annotation value. 1672 */ 1673 Class<? extends RestOpArg>[] restOpArgs() default {}; 1674 1675 /** 1676 * Role guard. 1677 * 1678 * <p> 1679 * An expression defining if a user with the specified roles are allowed to access methods on this class. 1680 * 1681 * <p> 1682 * This is a shortcut for specifying {@link RestOp#roleGuard()} on all the REST operations on a class. 1683 * 1684 * <h4 class='section'>Example:</h4> 1685 * <p class='bjava'> 1686 * <ja>@Rest</ja>( 1687 * path=<js>"/foo"</js>, 1688 * roleGuard=<js>"ROLE_ADMIN || (ROLE_READ_WRITE && ROLE_SPECIAL)"</js> 1689 * ) 1690 * <jk>public class</jk> MyResource <jk>extends</jk> BasicRestServlet { 1691 * ... 1692 * } 1693 * </p> 1694 * 1695 * <h4 class='section'>Notes:</h4><ul> 1696 * <li class='note'> 1697 * Supports any of the following expression constructs: 1698 * <ul> 1699 * <li><js>"foo"</js> - Single arguments. 1700 * <li><js>"foo,bar,baz"</js> - Multiple OR'ed arguments. 1701 * <li><js>"foo | bar | baz"</js> - Multiple OR'ed arguments, pipe syntax. 1702 * <li><js>"foo || bar || baz"</js> - Multiple OR'ed arguments, Java-OR syntax. 1703 * <li><js>"fo*"</js> - Patterns including <js>'*'</js> and <js>'?'</js>. 1704 * <li><js>"fo* & *oo"</js> - Multiple AND'ed arguments, ampersand syntax. 1705 * <li><js>"fo* && *oo"</js> - Multiple AND'ed arguments, Java-AND syntax. 1706 * <li><js>"fo* || (*oo || bar)"</js> - Parenthesis. 1707 * </ul> 1708 * <li> 1709 * AND operations take precedence over OR operations (as expected). 1710 * <li> 1711 * Whitespace is ignored. 1712 * <li> 1713 * <jk>null</jk> or empty expressions always match as <jk>false</jk>. 1714 * <li> 1715 * If patterns are used, you must specify the list of declared roles using {@link #rolesDeclared()}. 1716 * <li> 1717 * Supports <a class="doclink" href="https://juneau.apache.org/docs/topics/RestServerSvlVariables">REST Server SVL Variables</a> 1718 * (e.g. <js>"${L:my.localized.variable}"</js>). 1719 * </ul> 1720 * 1721 * @return The annotation value. 1722 */ 1723 String roleGuard() default ""; 1724 1725 /** 1726 * Declared roles. 1727 * 1728 * <p> 1729 * A comma-delimited list of all possible user roles. 1730 * 1731 * <p> 1732 * Used in conjunction with {@link #roleGuard()} is used with patterns. 1733 * 1734 * <p> 1735 * This is a shortcut for specifying {@link RestOp#rolesDeclared()} on all the REST operations on a class. 1736 * 1737 * <h4 class='section'>Example:</h4> 1738 * <p class='bjava'> 1739 * <ja>@Rest</ja>( 1740 * rolesDeclared=<js>"ROLE_ADMIN,ROLE_READ_WRITE,ROLE_READ_ONLY,ROLE_SPECIAL"</js>, 1741 * roleGuard=<js>"ROLE_ADMIN || (ROLE_READ_WRITE && ROLE_SPECIAL)"</js> 1742 * ) 1743 * <jk>public class</jk> MyResource <jk>extends</jk> BasicRestServlet { 1744 * ... 1745 * } 1746 * </p> 1747 * 1748 * @return The annotation value. 1749 */ 1750 String rolesDeclared() default ""; 1751 1752 /** 1753 * Specifies the serializers for POJOs into HTTP response bodies. 1754 * 1755 * <p> 1756 * Serializer are used to convert POJOs to HTTP response bodies. 1757 * <br>Any of the Juneau framework serializers can be used in this setting. 1758 * <br>The serializer selected is based on the request <c>Accept</c> header matched against the values returned by the following method 1759 * using a best-match algorithm: 1760 * <ul class='javatree'> 1761 * <li class='jm'>{@link Serializer#getMediaTypeRanges()} 1762 * </ul> 1763 * 1764 * <p> 1765 * <b>Ordering determines the default response format.</b> A request that sends no <c>Accept</c> header (or a 1766 * non-specific one such as <c>*/*</c>, which browsers send by default) is treated as <c>*/*</c> and matches 1767 * the <b>first</b> serializer in this list. That is why the default configuration 1768 * ({@link org.apache.juneau.rest.server.config.BasicUniversalConfig}) lists HTML first — so a browser, or any 1769 * client that omits <c>Accept</c>, receives HTML rather than JSON. Order this list deliberately, and send an 1770 * explicit <c>Accept: application/json</c> to force JSON regardless of ordering. 1771 * 1772 * <p> 1773 * Serializers are automatically inherited from {@link Rest#serializers()} annotations on parent classes with the serializers on child classes 1774 * prepended to the serializer group. 1775 * The {@link org.apache.juneau.marshall.serializer.SerializerSet.NoInherit SerializerSet.NoInherit} class can be used to prevent inheriting from the parent class. 1776 * 1777 * <h4 class='section'>Example:</h4> 1778 * <p class='bjava'> 1779 * <jc>// Define a REST resource that can produce JSON and XML.</jc> 1780 * <ja>@Rest</ja>( 1781 * serializers={ 1782 * JsonParser.<jk>class</jk>, 1783 * XmlParser.<jk>class</jk> 1784 * } 1785 * ) 1786 * <jk>public class</jk> MyResource { 1787 * ... 1788 * } 1789 * </p> 1790 * 1791 * <p> 1792 * The serializers can also be tailored at the method level using {@link RestOp#serializers()} (and related annotations). 1793 * 1794 * <p> 1795 * For programmatic equivalents, contribute a {@link SerializerSet} bean via 1796 * {@link org.apache.juneau.commons.inject.Bean @Bean(name="serializers")}. 1797 * 1798 * <h4 class='section'>Inheritance Rules</h4> 1799 * <ul> 1800 * <li>Serializers on child override those on parent class. 1801 * <li>{@link org.apache.juneau.marshall.serializer.SerializerSet.Inherit SerializerSet.Inherit} class can be used to inherit and augment values from parent. 1802 * <li>{@link org.apache.juneau.marshall.serializer.SerializerSet.NoInherit SerializerSet.NoInherit} class can be used to suppress inheriting from parent. 1803 * <li>Serializers on methods take precedence over those on classes. 1804 * </ul> 1805 * 1806 * <h4 class='section'>See Also:</h4><ul> 1807 * <li class='link'><a class="doclink" href="https://juneau.apache.org/docs/topics/Marshalling">Marshalling</a> 1808 * </ul> 1809 * 1810 * @return The annotation value. 1811 */ 1812 Class<? extends Serializer>[] serializers() default {}; 1813 1814 /** 1815 * Optional site name. 1816 * 1817 * <p> 1818 * The site name is intended to be a title that can be applied to the entire site. 1819 * 1820 * <p> 1821 * One possible use is if you want to add the same title to the top of all pages by defining a header on a 1822 * common parent class like so: 1823 * <p class='bjava'> 1824 * <ja>@HtmlDocConfig</ja>( 1825 * header={ 1826 * <js>"<h1>${RS:siteName}</h1>"</js>, 1827 * <js>"<h2>${RS:title}</h2>"</js> 1828 * } 1829 * ) 1830 * </p> 1831 * 1832 * <h4 class='section'>Notes:</h4><ul> 1833 * <li class='note'> 1834 * Supports <a class="doclink" href="https://juneau.apache.org/docs/topics/RestServerSvlVariables">REST Server SVL Variables</a> 1835 * (e.g. <js>"${L:my.localized.variable}"</js>). 1836 * </ul> 1837 * 1838 * @return The annotation value. 1839 */ 1840 String siteName() default ""; 1841 1842 /** 1843 * Static files. 1844 * 1845 * <p> 1846 * Used to retrieve localized files to be served up as static files through the REST API via the following 1847 * predefined methods: 1848 * <ul class='javatree'> 1849 * <li class='jm'>{@code BasicRestResource.getHtdoc(String, Locale)}. 1850 * <li class='jm'>{@code BasicRestServlet.getHtdoc(String, Locale)}. 1851 * </ul> 1852 * 1853 * <p> 1854 * The static file finder can be accessed through the following methods: 1855 * <ul class='javatree'> 1856 * <li class='jm'>{@link RestContext#getStaticFiles()} 1857 * </ul> 1858 * 1859 * <h4 class='section'>Inheritance Rules</h4> 1860 * <ul> 1861 * <li>Static files on child are combined with those on parent class. 1862 * <li>Static files are are executed child-to-parent in the order they appear in the annotation. 1863 * </ul> 1864 * 1865 * @return The annotation value. 1866 */ 1867 Class<? extends StaticFiles> staticFiles() default StaticFiles.Void.class; 1868 1869 /** 1870 * Provides swagger-specific metadata on this resource. 1871 * 1872 * <p> 1873 * Used to populate the auto-generated OPTIONS swagger documentation. 1874 * 1875 * <h4 class='section'>Example:</h4> 1876 * <p class='bjava'> 1877 * <ja>@Rest</ja>( 1878 * path=<js>"/addressBook"</js>, 1879 * 1880 * <jc>// Swagger info.</jc> 1881 * swagger=@Swagger({ 1882 * <js>"contact:{name:'John Smith',email:'john@smith.com'},"</js>, 1883 * <js>"license:{name:'Apache 2.0',url:'http://www.apache.org/licenses/LICENSE-2.0.html'},"</js>, 1884 * <js>"version:'2.0',</js>, 1885 * <js>"termsOfService:'You are on your own.',"</js>, 1886 * <js>"tags:[{name:'Java',description:'Java utility',externalDocs:{description:'Home page',url:'http://juneau.apache.org'}}],"</js>, 1887 * <js>"externalDocs:{description:'Home page',url:'http://juneau.apache.org'}"</js> 1888 * }) 1889 * ) 1890 * </p> 1891 * 1892 * <h4 class='section'>See Also:</h4><ul> 1893 * <li class='ja'>{@link Swagger} 1894 * </ul> 1895 * 1896 * @return The annotation value. 1897 */ 1898 Swagger swagger() default @Swagger; 1899 1900 /** 1901 * Swagger provider. 1902 * 1903 * @return The annotation value. 1904 */ 1905 Class<? extends SwaggerProvider> swaggerProvider() default SwaggerProvider.Void.class; 1906 1907 /** 1908 * OpenAPI 3.1 provider. 1909 * 1910 * <p> 1911 * Sibling of {@link #swaggerProvider()} for the OpenAPI 3.1 emission path. Defaults to 1912 * {@link org.apache.juneau.rest.server.openapi.OpenApiProvider.Void OpenApiProvider.Void} 1913 * which resolves to {@code BasicOpenApiProvider} unless the bean store provides an override. 1914 * 1915 * @return The annotation value. 1916 */ 1917 Class<? extends OpenApiProvider> openApiProvider() default OpenApiProvider.Void.class; 1918 1919 /** 1920 * Optional servlet title. 1921 * 1922 * <p> 1923 * It is used to populate the Swagger title field. 1924 * 1925 * <h4 class='section'>Inheritance Rules</h4> 1926 * <ul> 1927 * <li>Label is searched for in child-to-parent order. 1928 * </ul> 1929 * 1930 * <h4 class='section'>Notes:</h4><ul> 1931 * <li class='note'> 1932 * Supports <a class="doclink" href="https://juneau.apache.org/docs/topics/RestServerSvlVariables">REST Server SVL Variables</a> 1933 * (e.g. <js>"${L:my.localized.variable}"</js>). 1934 * <li class='note'> 1935 * Corresponds to the swagger field <c>/info/title</c>. 1936 * </ul> 1937 * 1938 * @return The annotation value. 1939 */ 1940 String[] title() default {}; 1941 1942 /** 1943 * Resource authority path. 1944 * 1945 * <p> 1946 * Overrides the authority path value for this resource and any child resources. 1947 * 1948 * <h4 class='section'>Notes:</h4><ul> 1949 * <li class='note'> 1950 * Supports <a class="doclink" href="https://juneau.apache.org/docs/topics/RestServerSvlVariables">REST Server SVL Variables</a> 1951 * (e.g. <js>"${L:my.localized.variable}"</js>). 1952 * </ul> 1953 * 1954 * @return The annotation value. 1955 */ 1956 String uriAuthority() default ""; 1957 1958 /** 1959 * Resource context path. 1960 * 1961 * <p> 1962 * Overrides the context path value for this resource and any child resources. 1963 * 1964 * <h4 class='section'>Notes:</h4><ul> 1965 * <li class='note'> 1966 * Supports <a class="doclink" href="https://juneau.apache.org/docs/topics/RestServerSvlVariables">REST Server SVL Variables</a> 1967 * (e.g. <js>"${L:my.localized.variable}"</js>). 1968 * </ul> 1969 * 1970 * @return The annotation value. 1971 */ 1972 String uriContext() default ""; 1973 1974 /** 1975 * URI-resolution relativity. 1976 * 1977 * <p> 1978 * Specifies how relative URIs should be interpreted by serializers. 1979 * 1980 * <p> 1981 * See {@link UriRelativity} for possible values. 1982 * 1983 * <h4 class='section'>Notes:</h4><ul> 1984 * <li class='note'> 1985 * Supports <a class="doclink" href="https://juneau.apache.org/docs/topics/RestServerSvlVariables">REST Server SVL Variables</a> 1986 * (e.g. <js>"${L:my.localized.variable}"</js>). 1987 * </ul> 1988 * 1989 * @return The annotation value. 1990 */ 1991 String uriRelativity() default ""; 1992 1993 /** 1994 * URI-resolution. 1995 * 1996 * <p> 1997 * Specifies how relative URIs should be interpreted by serializers. 1998 * 1999 * <p> 2000 * See {@link UriResolution} for possible values. 2001 * 2002 * <h4 class='section'>Notes:</h4><ul> 2003 * <li class='note'> 2004 * Supports <a class="doclink" href="https://juneau.apache.org/docs/topics/RestServerSvlVariables">REST Server SVL Variables</a> 2005 * (e.g. <js>"${L:my.localized.variable}"</js>). 2006 * </ul> 2007 * 2008 * @return The annotation value. 2009 */ 2010 String uriResolution() default ""; 2011}