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 &mdash; 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>*&#47;*</c>, which browsers send by default) is
055 * treated as <c>*&#47;*</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 * &mdash; or any client that omits <c>Accept</c> &mdash; 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&amp;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 &quot;not specified.&quot;
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 &mdash; 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} &mdash; guards, role guards, part serializer/parser, and a
308    * handful of default-scalar settings &mdash; 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=&#123;...&#125;)} 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 &mdash; 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 &mdash; guards, role
414    * guards, serializers, default headers, mount path, etc. &mdash; 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    * &mdash; 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} &mdash; 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 &mdash; 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 *&#47;*}).
895    * </ul>
896    *
897    * <ul class='values'>
898    *    <li><js>"true"</js> &mdash; enable problem-details responses for this resource.
899    *    <li><js>"false"</js> &mdash; disable problem-details responses for this resource (overrides an inherited
900    *       {@code "true"} from a parent {@code @Rest}).
901    *    <li><js>""</js> (default) &mdash; 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 &mdash; 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> &mdash; enable marshalling debug for this resource.
940    *    <li><js>"false"</js> &mdash; disable marshalling debug for this resource (overrides an inherited
941    *       {@code "true"} from a parent {@code @Rest}).
942    *    <li><js>""</js> (default) &mdash; 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> &mdash; enable virtual-thread dispatch on Java 21+ (silently disabled on older JVMs).
983    *    <li><js>"false"</js> &mdash; explicitly disable.
984    *    <li><js>""</js> (default) &mdash; 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> &mdash; 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> &mdash; 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) &mdash; 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&lt;Order&gt; 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 &mdash; 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 &mdash; see
1519    *       {@link RestContext#getPaths()} for the full precedence order (programmatic &gt; getter &gt; 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 &mdash; 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 &mdash; 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 &mdash; 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 &amp;&amp; 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* &amp; *oo"</js> - Multiple AND'ed arguments, ampersand syntax.
1705    *          <li><js>"fo* &amp;&amp; *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 &amp;&amp; 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>*&#47;*</c>, which browsers send by default) is treated as <c>*&#47;*</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 &mdash; 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>"&lt;h1&gt;${RS:siteName}&lt;/h1&gt;"</js>,
1827    *          <js>"&lt;h2&gt;${RS:title}&lt;/h2&gt;"</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}