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.annotation; 018 019import static java.lang.annotation.ElementType.*; 020import static java.lang.annotation.RetentionPolicy.*; 021 022import java.lang.annotation.*; 023import java.nio.charset.*; 024import java.util.*; 025 026import org.apache.juneau.*; 027import org.apache.juneau.annotation.*; 028import org.apache.juneau.config.*; 029import org.apache.juneau.cp.*; 030import org.apache.juneau.encoders.*; 031import org.apache.juneau.httppart.*; 032import org.apache.juneau.parser.*; 033import org.apache.juneau.rest.*; 034import org.apache.juneau.rest.arg.*; 035import org.apache.juneau.rest.converter.*; 036import org.apache.juneau.rest.debug.*; 037import org.apache.juneau.rest.guard.*; 038import org.apache.juneau.rest.httppart.*; 039import org.apache.juneau.rest.logger.*; 040import org.apache.juneau.rest.processor.*; 041import org.apache.juneau.rest.servlet.*; 042import org.apache.juneau.rest.staticfile.*; 043import org.apache.juneau.rest.swagger.*; 044import org.apache.juneau.serializer.*; 045 046/** 047 * Used to denote that a class is a REST resource and to associate metadata on it. 048 * 049 * <p> 050 * Usually used on a subclass of {@link RestServlet}, but can be used to annotate any class that you want to expose as 051 * a REST resource. 052 * 053 * <h5 class='section'>See Also:</h5><ul> 054 * <li class='link'><a class="doclink" href="https://juneau.apache.org/docs/topics/RestAnnotatedClassBasics">@Rest-Annotated Class Basics</a> 055 056 * </ul> 057 */ 058@Target(TYPE) 059@Retention(RUNTIME) 060@Inherited 061@ContextApply({RestAnnotation.RestContextApply.class,RestAnnotation.RestOpContextApply.class}) 062@AnnotationGroup(Rest.class) 063public @interface Rest { 064 065 /** 066 * Disable content URL parameter. 067 * 068 * <p> 069 * When enabled, the HTTP content content on PUT and POST requests can be passed in as text using the <js>"content"</js> 070 * URL parameter. 071 * <br> 072 * For example: 073 * <p class='burlenc'> 074 * ?content=(name='John%20Smith',age=45) 075 * </p> 076 * 077 * <h5 class='section'>Notes:</h5><ul> 078 * <li class='note'> 079 * Supports <a class="doclink" href="https://juneau.apache.org/docs/topics/RestServerSvlVariables">SVL Variables</a> 080 * (e.g. <js>"$L{my.localized.variable}"</js>). 081 * </ul> 082 * 083 * <h5 class='section'>See Also:</h5><ul> 084 * <li class='jm'>{@link org.apache.juneau.rest.RestContext.Builder#disableContentParam()} 085 * </ul> 086 * 087 * @return The annotation value. 088 */ 089 String disableContentParam() default ""; 090 091 /** 092 * Allowed header URL parameters. 093 * 094 * <p> 095 * When specified, allows headers such as <js>"Accept"</js> and <js>"Content-Type"</js> to be passed in as URL query 096 * parameters. 097 * <br> 098 * For example: 099 * <p class='burlenc'> 100 * ?Accept=text/json&Content-Type=text/json 101 * </p> 102 * 103 * <h5 class='section'>Notes:</h5><ul> 104 * <li class='note'> 105 * Supports <a class="doclink" href="https://juneau.apache.org/docs/topics/RestServerSvlVariables">SVL Variables</a> 106 * (e.g. <js>"$L{my.localized.variable}"</js>). 107 * <li class='note'> 108 * Use <js>"*"</js> to represent all methods. 109 * <li class='note'> 110 * Use <js>"NONE"</js> (case insensitive) to suppress inheriting a value from a parent class. 111 * </ul> 112 * 113 * <h5 class='section'>See Also:</h5><ul> 114 * <li class='jm'>{@link org.apache.juneau.rest.RestContext.Builder#allowedHeaderParams(String)} 115 * </ul> 116 * 117 * @return The annotation value. 118 */ 119 String allowedHeaderParams() default ""; 120 121 /** 122 * Allowed method headers. 123 * 124 * <p> 125 * A comma-delimited list of HTTP method names that are allowed to be passed as values in an <c>X-Method</c> HTTP header 126 * to override the real HTTP method name. 127 * <p> 128 * Allows you to override the actual HTTP method with a simulated method. 129 * <br>For example, if an HTTP Client API doesn't support <c>PATCH</c> but does support <c>POST</c> (because 130 * <c>PATCH</c> is not part of the original HTTP spec), you can add a <c>X-Method: PATCH</c> header on a normal 131 * <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. 132 * 133 * <h5 class='section'>Notes:</h5><ul> 134 * <li class='note'> 135 * Supports <a class="doclink" href="https://juneau.apache.org/docs/topics/RestServerSvlVariables">SVL Variables</a> 136 * (e.g. <js>"$L{my.localized.variable}"</js>). 137 * <li class='note'> 138 * Method names are case-insensitive. 139 * <li class='note'> 140 * Use <js>"*"</js> to represent all methods. 141 * <li class='note'> 142 * Use <js>"NONE"</js> (case insensitive) to suppress inheriting a value from a parent class. 143 * </ul> 144 * 145 * @return The annotation value. 146 */ 147 String allowedMethodHeaders() default ""; 148 149 /** 150 * Allowed method parameters. 151 * 152 * <p> 153 * When specified, the HTTP method can be overridden by passing in a <js>"method"</js> URL parameter on a regular 154 * GET request. 155 * <br> 156 * For example: 157 * <p class='burlenc'> 158 * ?method=OPTIONS 159 * </p> 160 * 161 * <h5 class='section'>Notes:</h5><ul> 162 * <li class='note'> 163 * Supports <a class="doclink" href="https://juneau.apache.org/docs/topics/RestServerSvlVariables">SVL Variables</a> 164 * (e.g. <js>"$L{my.localized.variable}"</js>). 165 * <li class='note'> 166 * Use <js>"*"</js> to represent all methods. 167 * <li class='note'> 168 * Use <js>"NONE"</js> (case insensitive) to suppress inheriting a value from a parent class. 169 * </ul> 170 * 171 * <h5 class='section'>See Also:</h5><ul> 172 * <li class='jm'>{@link org.apache.juneau.rest.RestContext.Builder#allowedMethodParams(String)} 173 * </ul> 174 * 175 * @return The annotation value. 176 */ 177 String allowedMethodParams() default ""; 178 179 /** 180 * Specifies the logger to use for logging of HTTP requests and responses. 181 * 182 * <h5 class='section'>Notes:</h5><ul> 183 * <li class='note'> 184 * The default call logger if not specified is {@link CallLogger}. 185 * <li class='note'> 186 * The resource class itself will be used if it implements the {@link CallLogger} interface and not 187 * explicitly overridden via this annotation. 188 * <li class='note'> 189 * The implementation must have one of the following constructors: 190 * <ul> 191 * <li><code><jk>public</jk> T(RestContext)</code> 192 * <li><code><jk>public</jk> T()</code> 193 * <li><code><jk>public static</jk> T <jsm>create</jsm>(RestContext)</code> 194 * <li><code><jk>public static</jk> T <jsm>create</jsm>()</code> 195 * </ul> 196 * <li class='note'> 197 * Inner classes of the REST resource class are allowed. 198 * </ul> 199 * 200 * <h5 class='section'>See Also:</h5><ul> 201 * <li class='jm'>{@link org.apache.juneau.rest.RestContext.Builder#callLogger()} 202 * <li class='link'><a class="doclink" href="https://juneau.apache.org/docs/topics/RestServerLoggingAndDebugging">Logging / Debugging</a> 203 * </ul> 204 * 205 * @return The annotation value. 206 */ 207 Class<? extends CallLogger> callLogger() default CallLogger.Void.class; 208 209 /** 210 * The resolver used for resolving instances of child resources and various other beans including: 211 * <ul> 212 * <li>{@link CallLogger} 213 * <li>{@link SwaggerProvider} 214 * <li>{@link FileFinder} 215 * <li>{@link StaticFiles} 216 * </ul> 217 * 218 * <p> 219 * Note that the <c>SpringRestServlet</c> classes uses the <c>SpringBeanStore</c> class to allow for any 220 * Spring beans to be injected into your REST resources. 221 * 222 * @return The annotation value. 223 */ 224 Class<? extends BeanStore> beanStore() default BeanStore.Void.class; 225 226 /** 227 * REST children. 228 * 229 * <p> 230 * Defines children of this resource. 231 * 232 * <h5 class='section'>Inheritance Rules</h5> 233 * <ul> 234 * <li>Children on child are combined with those on parent class. 235 * <li>Children are list parent-to-child in the order they appear in the annotation. 236 * </ul> 237 * 238 * <h5 class='section'>See Also:</h5><ul> 239 * <li class='jm'>{@link org.apache.juneau.rest.RestContext.Builder#children(Object...)} 240 * </ul> 241 * 242 * @return The annotation value. 243 */ 244 Class<?>[] children() default {}; 245 246 /** 247 * Client version header. 248 * 249 * <p> 250 * Specifies the name of the header used to denote the client version on HTTP requests. 251 * 252 * <h5 class='section'>Notes:</h5><ul> 253 * <li class='note'> 254 * Supports <a class="doclink" href="https://juneau.apache.org/docs/topics/RestServerSvlVariables">SVL Variables</a> 255 * (e.g. <js>"$L{my.localized.variable}"</js>). 256 * </ul> 257 * 258 * <h5 class='section'>See Also:</h5><ul> 259 * <li class='jm'>{@link org.apache.juneau.rest.RestContext.Builder#clientVersionHeader(String)} 260 * </ul> 261 * 262 * @return The annotation value. 263 */ 264 String clientVersionHeader() default ""; 265 266 /** 267 * Optional location of configuration file for this servlet. 268 * 269 * <p> 270 * The configuration file . 271 * 272 * <h5 class='section'>Inheritance Rules</h5> 273 * <ul> 274 * <li>Config file is searched for in child-to-parent order. 275 * </ul> 276 * 277 * <h5 class='section'>Notes:</h5><ul> 278 * <li class='note'> 279 * Supports <a class="doclink" href="https://juneau.apache.org/docs/topics/RestServerSvlVariables">SVL Variables</a> 280 * (e.g. <js>"$L{my.localized.variable}"</js>). 281 * <li class='note'> 282 * Use the keyword <c>SYSTEM_DEFAULT</c> to refer to the system default configuration 283 * returned by the {@link Config#getSystemDefault()}. 284 * </ul> 285 * 286 * <h5 class='section'>See Also:</h5><ul> 287 * <li class='jm'>{@link org.apache.juneau.rest.RestContext.Builder#config(Config)} 288 * </ul> 289 * 290 * @return The annotation value. 291 */ 292 String config() default ""; 293 294 /** 295 * Supported content media types. 296 * 297 * <p> 298 * Overrides the media types inferred from the parsers that identify what media types can be consumed by the resource. 299 * 300 * <h5 class='section'>Notes:</h5><ul> 301 * <li class='note'> 302 * Supports <a class="doclink" href="https://juneau.apache.org/docs/topics/RestServerSvlVariables">SVL Variables</a> 303 * (e.g. <js>"$L{my.localized.variable}"</js>). 304 * </ul> 305 * 306 * <h5 class='section'>See Also:</h5><ul> 307 * <li class='jm'>{@link org.apache.juneau.rest.RestContext.Builder#consumes(MediaType...)} 308 * </ul> 309 * 310 * @return The annotation value. 311 */ 312 String[] consumes() default {}; 313 314 /** 315 * Class-level response converters. 316 * 317 * <p> 318 * Associates one or more {@link RestConverter converters} with a resource class. 319 * 320 * <h5 class='section'>Inheritance Rules</h5> 321 * <ul> 322 * <li>Converters on child are combined with those on parent class. 323 * <li>Converters are executed child-to-parent in the order they appear in the annotation. 324 * <li>Converters on methods are executed before those on classes. 325 * </ul> 326 * 327 * <h5 class='section'>See Also:</h5><ul> 328 * <li class='jm'>{@link org.apache.juneau.rest.RestOpContext.Builder#converters()} - Registering converters with REST resources. 329 * </ul> 330 * 331 * @return The annotation value. 332 */ 333 Class<? extends RestConverter>[] converters() default {}; 334 335 /** 336 * Enable debug mode. 337 * 338 * <p> 339 * Enables the following: 340 * <ul class='spaced-list'> 341 * <li> 342 * HTTP request/response bodies are cached in memory for logging purposes. 343 * <li> 344 * HTTP requests/responses are logged to the registered {@link CallLogger}. 345 * </ul> 346 * 347 * <ul class='values'> 348 * <li><js>"true"</js> - Debug is enabled for all requests. 349 * <li><js>"false"</js> - Debug is disabled for all requests. 350 * <li><js>"conditional"</js> - Debug is enabled only for requests that have a <c class='snippet'>Debug: true</c> header. 351 * </ul> 352 * 353 * <h5 class='section'>Notes:</h5><ul> 354 * <li class='note'> 355 * Supports <a class="doclink" href="https://juneau.apache.org/docs/topics/RestServerSvlVariables">SVL Variables</a> 356 * (e.g. <js>"$L{my.localized.variable}"</js>). 357 * <li class='note'> 358 * These debug settings can be overridden by the {@link Rest#debugOn()} annotation or at runtime by directly 359 * calling {@link RestRequest#setDebug()}. 360 * </ul> 361 * 362 * <h5 class='section'>See Also:</h5><ul> 363 * <li class='jm'>{@link org.apache.juneau.rest.RestContext.Builder#debugEnablement()} 364 * </ul> 365 * 366 * @return The annotation value. 367 */ 368 String debug() default ""; 369 370 /** 371 * Debug enablement bean. 372 * 373 * TODO 374 * 375 * <h5 class='section'>See Also:</h5><ul> 376 * <li class='jm'>{@link org.apache.juneau.rest.RestContext.Builder#debugEnablement()} 377 * </ul> 378 * 379 * @return The annotation value. 380 */ 381 Class<? extends DebugEnablement> debugEnablement() default DebugEnablement.Void.class; 382 383 /** 384 * Enable debug mode on specified classes/methods. 385 * 386 * <p> 387 * Enables the following: 388 * <ul class='spaced-list'> 389 * <li> 390 * HTTP request/response bodies are cached in memory for logging purposes on matching classes and methods. 391 * <li> 392 * HTTP requests/responses are logged to the registered {@link CallLogger}. 393 * </ul> 394 * 395 * <p> 396 * Consists of a comma-delimited list of strings of the following forms: 397 * <ul> 398 * <li><js>"class-identifier"</js> - Enable debug on the specified class. 399 * <li><js>"class-identifier=[true|false|conditional]"</js> - Explicitly enable debug on the specified class. 400 * <li><js>"method-identifier"</js> - Enable debug on the specified class. 401 * <li><js>"method-identifier=[true|false|conditional]"</js> - Explicitly enable debug on the specified class. 402 * </ul> 403 * 404 * <p> 405 * Class identifiers can be any of the following forms: 406 * <ul> 407 * <li>Fully qualified: 408 * <ul> 409 * <li><js>"com.foo.MyClass"</js> 410 * </ul> 411 * <li>Fully qualified inner class: 412 * <ul> 413 * <li><js>"com.foo.MyClass$Inner1$Inner2"</js> 414 * </ul> 415 * <li>Simple: 416 * <ul> 417 * <li><js>"MyClass"</js> 418 * </ul> 419 * <li>Simple inner: 420 * <ul> 421 * <li><js>"MyClass$Inner1$Inner2"</js> 422 * <li><js>"Inner1$Inner2"</js> 423 * <li><js>"Inner2"</js> 424 * </ul> 425 * </ul> 426 * 427 * <p> 428 * Method identifiers can be any of the following forms: 429 * <ul> 430 * <li>Fully qualified with args: 431 * <ul> 432 * <li><js>"com.foo.MyClass.myMethod(String,int)"</js> 433 * <li><js>"com.foo.MyClass.myMethod(java.lang.String,int)"</js> 434 * <li><js>"com.foo.MyClass.myMethod()"</js> 435 * </ul> 436 * <li>Fully qualified: 437 * <ul> 438 * <li><js>"com.foo.MyClass.myMethod"</js> 439 * </ul> 440 * <li>Simple with args: 441 * <ul> 442 * <li><js>"MyClass.myMethod(String,int)"</js> 443 * <li><js>"MyClass.myMethod(java.lang.String,int)"</js> 444 * <li><js>"MyClass.myMethod()"</js> 445 * </ul> 446 * <li>Simple: 447 * <ul> 448 * <li><js>"MyClass.myMethod"</js> 449 * </ul> 450 * <li>Simple inner class: 451 * <ul> 452 * <li><js>"MyClass$Inner1$Inner2.myMethod"</js> 453 * <li><js>"Inner1$Inner2.myMethod"</js> 454 * <li><js>"Inner2.myMethod"</js> 455 * </ul> 456 * </ul> 457 * 458 * <h5 class='figure'>Example:</h5> 459 * <p class='bjava'> 460 * <jc>// Turn on debug per-request on the class and always on the doX() method</jc>. 461 * <ja>@Rest</ja>( 462 * debugOn=<js>"MyResource=conditional,MyResource.doX=true"</js> 463 * ) 464 * <jk>public class</jk> MyResource { 465 * 466 * <ja>@RestGet</ja> 467 * <jk>public void</jk> String getX() { 468 * ... 469 * } 470 * </p> 471 * 472 * <p> 473 * A more-typical scenario is to pull this setting from an external source such as system property or environment 474 * variable: 475 * 476 * <h5 class='figure'>Example:</h5> 477 * <p class='bjava'> 478 * <ja>@Rest</ja>( 479 * debugOn=<js>"$E{DEBUG_ON_SETTINGS}"</js> 480 * ) 481 * <jk>public class</jk> MyResource {...} 482 * </p> 483 * 484 * <h5 class='section'>Notes:</h5><ul> 485 * <li class='note'> 486 * Supports <a class="doclink" href="https://juneau.apache.org/docs/topics/RestServerSvlVariables">SVL Variables</a> 487 * (e.g. <js>"$L{my.localized.variable}"</js>). 488 * <li class='note'> 489 * These debug settings override the settings define via {@link Rest#debug()} and {@link RestOp#debug()}. 490 * <li class='note'> 491 * These debug settings can be overridden at runtime by directly calling {@link RestRequest#setDebug()}. 492 * </ul> 493 * 494 * @return The annotation value. 495 */ 496 String debugOn() default ""; 497 498 /** 499 * Default <c>Accept</c> header. 500 * 501 * <p> 502 * The default value for the <c>Accept</c> header if not specified on a request. 503 * 504 * <p> 505 * This is a shortcut for using {@link #defaultRequestHeaders()} for just this specific header. 506 * 507 * <h5 class='section'>Notes:</h5><ul> 508 * <li class='note'> 509 * Supports <a class="doclink" href="https://juneau.apache.org/docs/topics/RestServerSvlVariables">SVL Variables</a> 510 * (e.g. <js>"$L{my.localized.variable}"</js>). 511 * </ul> 512 * 513 * @return The annotation value. 514 */ 515 String defaultAccept() default ""; 516 517 /** 518 * Default character encoding. 519 * 520 * <p> 521 * The default character encoding for the request and response if not specified on the request. 522 * 523 * <h5 class='section'>Notes:</h5><ul> 524 * <li class='note'> 525 * Supports <a class="doclink" href="https://juneau.apache.org/docs/topics/RestServerSvlVariables">SVL Variables</a> 526 * (e.g. <js>"$L{my.localized.variable}"</js>). 527 * </ul> 528 * 529 * <h5 class='section'>See Also:</h5><ul> 530 * <li class='jm'>{@link org.apache.juneau.rest.RestContext.Builder#defaultCharset(Charset)} 531 * <li class='jm'>{@link org.apache.juneau.rest.RestOpContext.Builder#defaultCharset(Charset)} 532 * <li class='ja'>{@link RestOp#defaultCharset} 533 * <li class='ja'>{@link RestGet#defaultCharset} 534 * <li class='ja'>{@link RestPut#defaultCharset} 535 * <li class='ja'>{@link RestPost#defaultCharset} 536 * <li class='ja'>{@link RestDelete#defaultCharset} 537 * </ul> 538 * 539 * @return The annotation value. 540 */ 541 String defaultCharset() default ""; 542 543 /** 544 * Default <c>Content-Type</c> header. 545 * 546 * <p> 547 * The default value for the <c>Content-Type</c> header if not specified on a request. 548 * 549 * <p> 550 * This is a shortcut for using {@link #defaultRequestHeaders()} for just this specific header. 551 * 552 * <h5 class='section'>Notes:</h5><ul> 553 * <li class='note'> 554 * Supports <a class="doclink" href="https://juneau.apache.org/docs/topics/RestServerSvlVariables">SVL Variables</a> 555 * (e.g. <js>"$L{my.localized.variable}"</js>). 556 * </ul> 557 * 558 * @return The annotation value. 559 */ 560 String defaultContentType() default ""; 561 562 /** 563 * Default request attributes. 564 * 565 * <p> 566 * Specifies default values for request attributes if they're not already set on the request. 567 * 568 * <p> 569 * Affects values returned by the following methods: 570 * <ul> 571 * <li class='jm'>{@link RestRequest#getAttribute(String)}. 572 * <li class='jm'>{@link RestRequest#getAttributes()}. 573 * </ul> 574 * 575 * <h5 class='section'>Example:</h5> 576 * <p class='bjava'> 577 * <jc>// Defined via annotation resolving to a config file setting with default value.</jc> 578 * <ja>@Rest</ja>(defaultRequestAttributes={<js>"Foo=bar"</js>, <js>"Baz: $C{REST/myAttributeValue}"</js>}) 579 * <jk>public class</jk> MyResource { 580 * 581 * <jc>// Override at the method level.</jc> 582 * <ja>@RestGet</ja>(defaultRequestAttributes={<js>"Foo: bar"</js>}) 583 * <jk>public</jk> Object myMethod() {...} 584 * } 585 * </p> 586 * 587 * <h5 class='section'>Notes:</h5><ul> 588 * <li class='note'> 589 * Supports <a class="doclink" href="https://juneau.apache.org/docs/topics/RestServerSvlVariables">SVL Variables</a> 590 * (e.g. <js>"$L{my.localized.variable}"</js>). 591 * </ul> 592 * 593 * <h5 class='section'>See Also:</h5><ul> 594 * <li class='jm'>{@link org.apache.juneau.rest.RestContext.Builder#defaultRequestAttributes(NamedAttribute...)} 595 * <li class='ja'>{@link RestOp#defaultRequestAttributes()} 596 * <li class='ja'>{@link RestGet#defaultRequestAttributes()} 597 * <li class='ja'>{@link RestPut#defaultRequestAttributes()} 598 * <li class='ja'>{@link RestPost#defaultRequestAttributes()} 599 * <li class='ja'>{@link RestDelete#defaultRequestAttributes()} 600 * </ul> 601 * 602 * @return The annotation value. 603 */ 604 String[] defaultRequestAttributes() default {}; 605 606 /** 607 * Default request headers. 608 * 609 * <p> 610 * Specifies default values for request headers if they're not passed in through the request. 611 * 612 * <h5 class='section'>Notes:</h5><ul> 613 * <li class='note'> 614 * Supports <a class="doclink" href="https://juneau.apache.org/docs/topics/RestServerSvlVariables">SVL Variables</a> 615 * (e.g. <js>"$L{my.localized.variable}"</js>). 616 * </ul> 617 * 618 * <h5 class='section'>See Also:</h5><ul> 619 * <li class='jm'>{@link org.apache.juneau.rest.RestContext.Builder#defaultRequestHeaders(org.apache.http.Header...)} 620 * </ul> 621 * 622 * @return The annotation value. 623 */ 624 String[] defaultRequestHeaders() default {}; 625 626 /** 627 * Default response headers. 628 * 629 * <p> 630 * Specifies default values for response headers if they're not set after the Java REST method is called. 631 * 632 * <h5 class='section'>Notes:</h5><ul> 633 * <li class='note'> 634 * Supports <a class="doclink" href="https://juneau.apache.org/docs/topics/RestServerSvlVariables">SVL Variables</a> 635 * (e.g. <js>"$L{my.localized.variable}"</js>). 636 * </ul> 637 * 638 * <h5 class='section'>See Also:</h5><ul> 639 * <li class='jm'>{@link org.apache.juneau.rest.RestContext.Builder#defaultResponseHeaders(org.apache.http.Header...)} 640 * </ul> 641 * 642 * @return The annotation value. 643 */ 644 String[] defaultResponseHeaders() default {}; 645 646 /** 647 * Optional servlet description. 648 * 649 * <p> 650 * It is used to populate the Swagger description field. 651 * 652 * <h5 class='section'>Inheritance Rules</h5> 653 * <ul> 654 * <li>Description is searched for in child-to-parent order. 655 * </ul> 656 * 657 * <h5 class='section'>Notes:</h5><ul> 658 * <li class='note'> 659 * Supports <a class="doclink" href="https://juneau.apache.org/docs/topics/RestServerSvlVariables">SVL Variables</a> 660 * (e.g. <js>"$L{my.localized.variable}"</js>). 661 * <li class='note'> 662 * The format is plain-text. 663 * <br>Multiple lines are concatenated with newlines. 664 * </ul> 665 * 666 * @return The annotation value. 667 */ 668 String[] description() default {}; 669 670 /** 671 * Specifies the compression encoders for this resource. 672 * 673 * <p> 674 * Encoders are used to enable various kinds of compression (e.g. <js>"gzip"</js>) on requests and responses. 675 * 676 * <p> 677 * Encoders are automatically inherited from {@link Rest#encoders()} annotations on parent classes with the encoders on child classes 678 * prepended to the encoder group. 679 * The {@link org.apache.juneau.encoders.EncoderSet.NoInherit} class can be used to prevent inheriting from the parent class. 680 * 681 * <h5 class='section'>Example:</h5> 682 * <p class='bjava'> 683 * <jc>// Define a REST resource that handles GZIP compression.</jc> 684 * <ja>@Rest</ja>( 685 * encoders={ 686 * GzipEncoder.<jk>class</jk> 687 * } 688 * ) 689 * <jk>public class</jk> MyResource { 690 * ... 691 * } 692 * </p> 693 * 694 * <p> 695 * The encoders can also be tailored at the method level using {@link RestOp#encoders()} (and related annotations). 696 * 697 * <p> 698 * The programmatic equivalent to this annotation is: 699 * <p class='bjava'> 700 * RestContext.Builder <jv>builder</jv> = RestContext.<jsm>create</jsm>(<jv>resource</jv>); 701 * <jv>builder</jv>.getEncoders().add(<jv>classes</jv>); 702 * </p> 703 * 704 * <h5 class='section'>Inheritance Rules</h5> 705 * <ul> 706 * <li>Encoders on child are combined with those on parent class. 707 * </ul> 708 * 709 * <h5 class='section'>See Also:</h5><ul> 710 * <li class='link'><a class="doclink" href="https://juneau.apache.org/docs/topics/RestServerEncoders">Encoders</a> 711 * </ul> 712 * 713 * @return The annotation value. 714 */ 715 Class<? extends Encoder>[] encoders() default {}; 716 717 /** 718 * Class-level guards. 719 * 720 * <p> 721 * Associates one or more {@link RestGuard RestGuards} with all REST methods defined in this class. 722 * 723 * <h5 class='section'>Inheritance Rules</h5> 724 * <ul> 725 * <li>Guards on child are combined with those on parent class. 726 * <li>Guards are executed child-to-parent in the order they appear in the annotation. 727 * <li>Guards on methods are executed before those on classes. 728 * </ul> 729 * 730 * <h5 class='section'>See Also:</h5><ul> 731 * <li class='jm'>{@link org.apache.juneau.rest.RestOpContext.Builder#guards()} 732 * </ul> 733 * 734 * @return The annotation value. 735 */ 736 Class<? extends RestGuard>[] guards() default {}; 737 738 /** 739 * The maximum allowed input size (in bytes) on HTTP requests. 740 * 741 * <p> 742 * Useful for alleviating DoS attacks by throwing an exception when too much input is received instead of resulting 743 * in out-of-memory errors which could affect system stability. 744 * 745 * <h5 class='section'>Notes:</h5><ul> 746 * <li class='note'> 747 * Supports <a class="doclink" href="https://juneau.apache.org/docs/topics/RestServerSvlVariables">SVL Variables</a> 748 * (e.g. <js>"$L{my.localized.variable}"</js>). 749 * </ul> 750 * 751 * <h5 class='section'>See Also:</h5><ul> 752 * <li class='jm'>{@link org.apache.juneau.rest.RestContext.Builder#maxInput(String)} 753 * <li class='jm'>{@link org.apache.juneau.rest.RestOpContext.Builder#maxInput(String)} 754 * <li class='ja'>{@link RestOp#maxInput} 755 * <li class='ja'>{@link RestPost#maxInput} 756 * <li class='ja'>{@link RestPut#maxInput} 757 * </ul> 758 * 759 * @return The annotation value. 760 */ 761 String maxInput() default ""; 762 763 /** 764 * Messages. 765 * 766 * Identifies the location of the resource bundle for this class. 767 * 768 * <p> 769 * There are two possible formats: 770 * <ul> 771 * <li>A simple string - Represents the {@link org.apache.juneau.cp.Messages.Builder#name(String) name} of the resource bundle. 772 * <br><br><i>Example:</i> 773 * <p class='bjava'> 774 * <jc>// Bundle name is Messages.properties.</jc> 775 * <ja>@Rest</ja>(messages=<js>"Messages"</js>) 776 * </p> 777 * <li>Simplified JSON - Represents parameters for the {@link org.apache.juneau.cp.Messages.Builder} class. 778 * <br><br><i>Example:</i> 779 * <p class='bjava'> 780 * <jc>// Bundles can be found in two packages.</jc> 781 * <ja>@Rest</ja>(messages=<js>"{name:'Messages',baseNames:['{package}.{name}','{package}.i18n.{name}']"</js>) 782 * </p> 783 * </ul> 784 * 785 * <p> 786 * If the bundle name is not specified, the class name of the resource object is used. 787 * 788 * <h5 class='section'>Notes:</h5><ul> 789 * <li class='note'> 790 * Supports <a class="doclink" href="https://juneau.apache.org/docs/topics/RestServerSvlVariables">SVL Variables</a> 791 * (e.g. <js>"$L{my.localized.variable}"</js>). 792 * </ul> 793 * 794 * @return The annotation value. 795 */ 796 String messages() default ""; 797 798 /** 799 * Dynamically apply this annotation to the specified classes. 800 * 801 * <h5 class='section'>See Also:</h5><ul> 802 * <li class='link'><a class="doclink" href="https://juneau.apache.org/docs/topics/DynamicallyAppliedAnnotations">Dynamically Applied Annotations</a> 803 * </ul> 804 * 805 * @return The annotation value. 806 */ 807 String[] on() default {}; 808 809 /** 810 * Dynamically apply this annotation to the specified classes. 811 * 812 * <p> 813 * Identical to {@link #on()} except allows you to specify class objects instead of a strings. 814 * 815 * <h5 class='section'>See Also:</h5><ul> 816 * <li class='link'><a class="doclink" href="https://juneau.apache.org/docs/topics/DynamicallyAppliedAnnotations">Dynamically Applied Annotations</a> 817 * </ul> 818 * 819 * @return The annotation value. 820 */ 821 Class<?>[] onClass() default {}; 822 823 /** 824 * Specifies the parsers for converting HTTP request bodies into POJOs. 825 * 826 * <p> 827 * Parsers are used to convert the content of HTTP requests into POJOs. 828 * <br>Any of the Juneau framework parsers can be used in this setting. 829 * <br>The parser selected is based on the request <c>Content-Type</c> header matched against the values returned by the following method 830 * using a best-match algorithm: 831 * <ul class='javatree'> 832 * <li class='jm'>{@link Parser#getMediaTypes()} 833 * </ul> 834 * 835 * <p> 836 * Parsers are automatically inherited from {@link Rest#parsers()} annotations on parent classes with the parsers on child classes 837 * prepended to the parser group. 838 * The {@link org.apache.juneau.parser.ParserSet.NoInherit} class can be used to prevent inheriting from the parent class. 839 * 840 * <h5 class='section'>Example:</h5> 841 * <p class='bjava'> 842 * <jc>// Define a REST resource that can consume JSON and XML.</jc> 843 * <ja>@Rest</ja>( 844 * parsers={ 845 * JsonParser.<jk>class</jk>, 846 * XmlParser.<jk>class</jk> 847 * } 848 * ) 849 * <jk>public class</jk> MyResource { 850 * ... 851 * } 852 * </p> 853 * 854 * <p> 855 * The parsers can also be tailored at the method level using {@link RestOp#parsers()} (and related annotations). 856 * 857 * <p> 858 * The programmatic equivalent to this annotation is: 859 * <p class='bjava'> 860 * RestContext.Builder <jv>builder</jv> = RestContext.<jsm>create</jsm>(<jv>resource</jv>); 861 * <jv>builder</jv>.getParsers().add(<jv>classes</jv>); 862 * </p> 863 * 864 * <h5 class='section'>Inheritance Rules</h5> 865 * <ul> 866 * <li>Parsers on child override those on parent class. 867 * <li>{@link org.apache.juneau.parser.ParserSet.Inherit} class can be used to inherit and augment values from parent. 868 * <li>{@link org.apache.juneau.parser.ParserSet.NoInherit} class can be used to suppress inheriting from parent. 869 * <li>Parsers on methods take precedence over those on classes. 870 * </ul> 871 * 872 * <h5 class='section'>See Also:</h5><ul> 873 * <li class='link'><a class="doclink" href="https://juneau.apache.org/docs/topics/Marshalling">Marshalling</a> 874 * </ul> 875 * 876 * @return The annotation value. 877 */ 878 Class<?>[] parsers() default {}; 879 880 /** 881 * HTTP part parser. 882 * 883 * <p> 884 * Specifies the {@link HttpPartParser} to use for parsing headers, query/form parameters, and URI parts. 885 * 886 * @return The annotation value. 887 */ 888 Class<? extends HttpPartParser> partParser() default HttpPartParser.Void.class; 889 890 /** 891 * HTTP part serializer. 892 * 893 * <p> 894 * Specifies the {@link HttpPartSerializer} to use for serializing headers, query/form parameters, and URI parts. 895 * 896 * @return The annotation value. 897 */ 898 Class<? extends HttpPartSerializer> partSerializer() default HttpPartSerializer.Void.class; 899 900 /** 901 * Resource path. 902 * 903 * <p> 904 * Used in the following situations: 905 * <ul class='spaced-list'> 906 * <li> 907 * On child resources (resource classes attached to parents via the {@link #children()} annotation) to identify 908 * the subpath used to access the child resource relative to the parent. 909 * <li> 910 * On top-level {@link RestServlet} classes deployed as Spring beans when <c>JuneauRestInitializer</c> is being used. 911 * </ul> 912 * 913 * <h5 class='topic'>On child resources</h5> 914 * <p> 915 * The typical usage is to define a path to a child resource relative to the parent resource. 916 * 917 * <h5 class='figure'>Example:</h5> 918 * <p class='bjava'> 919 * <ja>@Rest</ja>( 920 * children={ChildResource.<jk>class</jk>} 921 * ) 922 * <jk>public class</jk> TopLevelResource <jk>extends</jk> BasicRestServlet {...} 923 * 924 * <ja>@Rest</ja>( 925 * path=<js>"/child"</js>, 926 * children={GrandchildResource.<jk>class</jk>} 927 * ) 928 * <jk>public class</jk> ChildResource {...} 929 * 930 * <ja>@Rest</ja>( 931 * path=<js>"/grandchild"</js> 932 * ) 933 * <jk>public class</jk> GrandchildResource { 934 * <ja>@RestGet</ja>(<js>"/"</js>) 935 * <jk>public</jk> String sayHello() { 936 * <jk>return</jk> <js>"Hello!"</js>; 937 * } 938 * } 939 * </p> 940 * <p> 941 * In the example above, assuming the <c>TopLevelResource</c> servlet is deployed to path <c>/myContext/myServlet</c>, 942 * then the <c>sayHello</c> method is accessible through the URI <c>/myContext/myServlet/child/grandchild</c>. 943 * 944 * <p> 945 * Note that in this scenario, the <c>path</c> attribute is not defined on the top-level resource. 946 * Specifying the path on the top-level resource has no effect, but can be used for readability purposes. 947 * 948 * <h5 class='topic'>Path variables</h5> 949 * <p> 950 * The path can contain variables that get resolved to {@link org.apache.juneau.http.annotation.Path @Path} parameters 951 * or access through the {@link RestRequest#getPathParams()} method. 952 * 953 * <h5 class='figure'>Example:</h5> 954 * <p class='bjava'> 955 * <ja>@Rest</ja>( 956 * path=<js>"/myResource/{foo}/{bar}"</js> 957 * ) 958 * <jk>public class</jk> MyResource <jk>extends</jk> BasicRestServlet { 959 * 960 * <ja>@RestGet</ja>(<js>"/{baz}"</js>) 961 * <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>) { 962 * ... 963 * } 964 * } 965 * </p> 966 * 967 * <p> 968 * Variables can be used on either top-level or child resources and can be defined on multiple levels. 969 * 970 * <p> 971 * All variables in the path must be specified or else the target will not resolve and a <c>404</c> will result. 972 * 973 * <p> 974 * When variables are used on a path of a top-level resource deployed as a Spring bean in a Spring Boot application, 975 * the first part of the URL must be a literal which will be used as the servlet path of the registered servlet. 976 * 977 * <h5 class='section'>Notes:</h5><ul> 978 * <li class='note'> 979 * The leading slash is optional. <js>"/myResource"</js> and <js>"myResource"</js> is equivalent. 980 * <li class='note'> 981 * The paths <js>"/myResource"</js> and <js>"/myResource/*"</js> are equivalent. 982 * <li class='note'> 983 * Paths must not end with <js>"/"</js> (per the servlet spec). 984 * </ul> 985 * 986 * <h5 class='section'>Inheritance Rules</h5> 987 * <ul> 988 * <li>Path is searched for in child-to-parent order. 989 * </ul> 990 * 991 * <h5 class='section'>See Also:</h5><ul> 992 * <li class='jm'>{@link org.apache.juneau.rest.RestContext.Builder#path(String)} 993 * </ul> 994 * 995 * @return The annotation value. 996 */ 997 String path() default ""; 998 999 /** 1000 * Supported accept media types. 1001 * 1002 * <p> 1003 * Overrides the media types inferred from the serializers that identify what media types can be produced by the resource. 1004 * 1005 * <h5 class='section'>Notes:</h5><ul> 1006 * <li class='note'> 1007 * Supports <a class="doclink" href="https://juneau.apache.org/docs/topics/RestServerSvlVariables">SVL Variables</a> 1008 * (e.g. <js>"$L{my.localized.variable}"</js>). 1009 * </ul> 1010 * 1011 * <h5 class='section'>See Also:</h5><ul> 1012 * <li class='jm'>{@link org.apache.juneau.rest.RestContext.Builder#produces(MediaType...)} 1013 * </ul> 1014 * 1015 * @return The annotation value. 1016 */ 1017 String[] produces() default {}; 1018 1019 /** 1020 * Render response stack traces in responses. 1021 * 1022 * <p> 1023 * Render stack traces in HTTP response bodies when errors occur. 1024 * 1025 * <h5 class='section'>Notes:</h5><ul> 1026 * <li class='note'> 1027 * Supports <a class="doclink" href="https://juneau.apache.org/docs/topics/RestServerSvlVariables">SVL Variables</a> 1028 * (e.g. <js>"$L{my.localized.variable}"</js>). 1029 * </ul> 1030 * 1031 * @return The annotation value. 1032 */ 1033 String renderResponseStackTraces() default ""; 1034 1035 /** 1036 * Response processors. 1037 * 1038 * <p> 1039 * Specifies a list of {@link ResponseProcessor} classes that know how to convert POJOs returned by REST methods or 1040 * set via {@link RestResponse#setContent(Object)} into appropriate HTTP responses. 1041 * 1042 * <h5 class='section'>See Also:</h5><ul> 1043 * <li class='jm'>{@link org.apache.juneau.rest.RestContext.Builder#responseProcessors()} 1044 * </ul> 1045 * 1046 * @return The annotation value. 1047 */ 1048 Class<? extends ResponseProcessor>[] responseProcessors() default {}; 1049 1050 /** 1051 * REST children class. 1052 * 1053 * <p> 1054 * Allows you to extend the {@link RestChildren} class to modify how any of the methods are implemented. 1055 * 1056 * <h5 class='section'>See Also:</h5><ul> 1057 * <li class='jm'>{@link org.apache.juneau.rest.RestContext.Builder#restChildrenClass(Class)} 1058 * </ul> 1059 * 1060 * @return The annotation value. 1061 */ 1062 Class<? extends RestChildren> restChildrenClass() default RestChildren.Void.class; 1063 1064 /** 1065 * REST methods class. 1066 * 1067 * <p> 1068 * Allows you to extend the {@link RestOperations} class to modify how any of the methods are implemented. 1069 * 1070 * <h5 class='section'>See Also:</h5><ul> 1071 * <li class='jm'>{@link org.apache.juneau.rest.RestContext.Builder#restOperationsClass(Class)} 1072 * </ul> 1073 * 1074 * @return The annotation value. 1075 */ 1076 Class<? extends RestOperations> restOperationsClass() default RestOperations.Void.class; 1077 1078 /** 1079 * Java REST operation method parameter resolvers. 1080 * 1081 * <p> 1082 * By default, the Juneau framework will automatically Java method parameters of various types (e.g. 1083 * <c>RestRequest</c>, <c>Accept</c>, <c>Reader</c>). 1084 * <br>This setting allows you to provide your own resolvers for your own class types that you want resolved. 1085 * 1086 * <h5 class='section'>See Also:</h5><ul> 1087 * <li class='jm'>{@link org.apache.juneau.rest.RestContext.Builder#restOpArgs(Class...)} 1088 * </ul> 1089 * 1090 * @return The annotation value. 1091 */ 1092 Class<? extends RestOpArg>[] restOpArgs() default {}; 1093 1094 /** 1095 * Role guard. 1096 * 1097 * <p> 1098 * An expression defining if a user with the specified roles are allowed to access methods on this class. 1099 * 1100 * <p> 1101 * This is a shortcut for specifying {@link RestOp#roleGuard()} on all the REST operations on a class. 1102 * 1103 * <h5 class='section'>Example:</h5> 1104 * <p class='bjava'> 1105 * <ja>@Rest</ja>( 1106 * path=<js>"/foo"</js>, 1107 * roleGuard=<js>"ROLE_ADMIN || (ROLE_READ_WRITE && ROLE_SPECIAL)"</js> 1108 * ) 1109 * <jk>public class</jk> MyResource <jk>extends</jk> BasicRestServlet { 1110 * ... 1111 * } 1112 * </p> 1113 * 1114 * <h5 class='section'>Notes:</h5><ul> 1115 * <li class='note'> 1116 * Supports any of the following expression constructs: 1117 * <ul> 1118 * <li><js>"foo"</js> - Single arguments. 1119 * <li><js>"foo,bar,baz"</js> - Multiple OR'ed arguments. 1120 * <li><js>"foo | bar | baz"</js> - Multiple OR'ed arguments, pipe syntax. 1121 * <li><js>"foo || bar || baz"</js> - Multiple OR'ed arguments, Java-OR syntax. 1122 * <li><js>"fo*"</js> - Patterns including <js>'*'</js> and <js>'?'</js>. 1123 * <li><js>"fo* & *oo"</js> - Multiple AND'ed arguments, ampersand syntax. 1124 * <li><js>"fo* && *oo"</js> - Multiple AND'ed arguments, Java-AND syntax. 1125 * <li><js>"fo* || (*oo || bar)"</js> - Parenthesis. 1126 * </ul> 1127 * <li> 1128 * AND operations take precedence over OR operations (as expected). 1129 * <li> 1130 * Whitespace is ignored. 1131 * <li> 1132 * <jk>null</jk> or empty expressions always match as <jk>false</jk>. 1133 * <li> 1134 * If patterns are used, you must specify the list of declared roles using {@link #rolesDeclared()} or {@link org.apache.juneau.rest.RestOpContext.Builder#rolesDeclared(String...)}. 1135 * <li> 1136 * Supports <a class="doclink" href="https://juneau.apache.org/docs/topics/RestServerSvlVariables">SVL Variables</a> 1137 * (e.g. <js>"$L{my.localized.variable}"</js>). 1138 * </ul> 1139 * 1140 * <h5 class='section'>See Also:</h5><ul> 1141 * <li class='jm'>{@link org.apache.juneau.rest.RestOpContext.Builder#roleGuard(String)} 1142 * </ul> 1143 * 1144 * @return The annotation value. 1145 */ 1146 String roleGuard() default ""; 1147 1148 /** 1149 * Declared roles. 1150 * 1151 * <p> 1152 * A comma-delimited list of all possible user roles. 1153 * 1154 * <p> 1155 * Used in conjunction with {@link #roleGuard()} is used with patterns. 1156 * 1157 * <p> 1158 * This is a shortcut for specifying {@link RestOp#rolesDeclared()} on all the REST operations on a class. 1159 * 1160 * <h5 class='section'>Example:</h5> 1161 * <p class='bjava'> 1162 * <ja>@Rest</ja>( 1163 * rolesDeclared=<js>"ROLE_ADMIN,ROLE_READ_WRITE,ROLE_READ_ONLY,ROLE_SPECIAL"</js>, 1164 * roleGuard=<js>"ROLE_ADMIN || (ROLE_READ_WRITE && ROLE_SPECIAL)"</js> 1165 * ) 1166 * <jk>public class</jk> MyResource <jk>extends</jk> BasicRestServlet { 1167 * ... 1168 * } 1169 * </p> 1170 * 1171 * <h5 class='section'>See Also:</h5><ul> 1172 * <li class='jm'>{@link org.apache.juneau.rest.RestOpContext.Builder#rolesDeclared(String...)} 1173 * </ul> 1174 * 1175 * @return The annotation value. 1176 */ 1177 String rolesDeclared() default ""; 1178 1179 /** 1180 * Specifies the serializers for POJOs into HTTP response bodies. 1181 * 1182 * <p> 1183 * Serializer are used to convert POJOs to HTTP response bodies. 1184 * <br>Any of the Juneau framework serializers can be used in this setting. 1185 * <br>The serializer selected is based on the request <c>Accept</c> header matched against the values returned by the following method 1186 * using a best-match algorithm: 1187 * <ul class='javatree'> 1188 * <li class='jm'>{@link Serializer#getMediaTypeRanges()} 1189 * </ul> 1190 * 1191 * <p> 1192 * Serializers are automatically inherited from {@link Rest#serializers()} annotations on parent classes with the serializers on child classes 1193 * prepended to the serializer group. 1194 * The {@link org.apache.juneau.serializer.SerializerSet.NoInherit} class can be used to prevent inheriting from the parent class. 1195 * 1196 * <h5 class='section'>Example:</h5> 1197 * <p class='bjava'> 1198 * <jc>// Define a REST resource that can produce JSON and XML.</jc> 1199 * <ja>@Rest</ja>( 1200 * serializers={ 1201 * JsonParser.<jk>class</jk>, 1202 * XmlParser.<jk>class</jk> 1203 * } 1204 * ) 1205 * <jk>public class</jk> MyResource { 1206 * ... 1207 * } 1208 * </p> 1209 * 1210 * <p> 1211 * The serializers can also be tailored at the method level using {@link RestOp#serializers()} (and related annotations). 1212 * 1213 * <p> 1214 * The programmatic equivalent to this annotation is: 1215 * <p class='bjava'> 1216 * RestContext.Builder <jv>builder</jv> = RestContext.<jsm>create</jsm>(<jv>resource</jv>); 1217 * <jv>builder</jv>.getSerializers().add(<jv>classes</jv>); 1218 * </p> 1219 * 1220 * <h5 class='section'>Inheritance Rules</h5> 1221 * <ul> 1222 * <li>Serializers on child override those on parent class. 1223 * <li>{@link org.apache.juneau.serializer.SerializerSet.Inherit} class can be used to inherit and augment values from parent. 1224 * <li>{@link org.apache.juneau.serializer.SerializerSet.NoInherit} class can be used to suppress inheriting from parent. 1225 * <li>Serializers on methods take precedence over those on classes. 1226 * </ul> 1227 * 1228 * <h5 class='section'>See Also:</h5><ul> 1229 * <li class='link'><a class="doclink" href="https://juneau.apache.org/docs/topics/Marshalling">Marshalling</a> 1230 * </ul> 1231 * 1232 * @return The annotation value. 1233 */ 1234 Class<? extends Serializer>[] serializers() default {}; 1235 1236 /** 1237 * Optional site name. 1238 * 1239 * <p> 1240 * The site name is intended to be a title that can be applied to the entire site. 1241 * 1242 * <p> 1243 * One possible use is if you want to add the same title to the top of all pages by defining a header on a 1244 * common parent class like so: 1245 * <p class='bjava'> 1246 * <ja>@HtmlDocConfig</ja>( 1247 * header={ 1248 * <js>"<h1>$RS{siteName}</h1>"</js>, 1249 * <js>"<h2>$RS{title}</h2>"</js> 1250 * } 1251 * ) 1252 * </p> 1253 * 1254 * <h5 class='section'>Notes:</h5><ul> 1255 * <li class='note'> 1256 * Supports <a class="doclink" href="https://juneau.apache.org/docs/topics/RestServerSvlVariables">SVL Variables</a> 1257 * (e.g. <js>"$L{my.localized.variable}"</js>). 1258 * </ul> 1259 * 1260 * @return The annotation value. 1261 */ 1262 String siteName() default ""; 1263 1264 /** 1265 * Static files. 1266 * 1267 * <p> 1268 * Used to retrieve localized files to be served up as static files through the REST API via the following 1269 * predefined methods: 1270 * <ul class='javatree'> 1271 * <li class='jm'>{@link BasicRestObject#getHtdoc(String, Locale)}. 1272 * <li class='jm'>{@link BasicRestServlet#getHtdoc(String, Locale)}. 1273 * </ul> 1274 * 1275 * <p> 1276 * The static file finder can be accessed through the following methods: 1277 * <ul class='javatree'> 1278 * <li class='jm'>{@link RestContext#getStaticFiles()} 1279 * <li class='jm'>{@link RestRequest#getStaticFiles()} 1280 * </ul> 1281 * 1282 * <h5 class='section'>Inheritance Rules</h5> 1283 * <ul> 1284 * <li>Static files on child are combined with those on parent class. 1285 * <li>Static files are are executed child-to-parent in the order they appear in the annotation. 1286 * </ul> 1287 * 1288 * @return The annotation value. 1289 */ 1290 Class<? extends StaticFiles> staticFiles() default StaticFiles.Void.class; 1291 1292 /** 1293 * Provides swagger-specific metadata on this resource. 1294 * 1295 * <p> 1296 * Used to populate the auto-generated OPTIONS swagger documentation. 1297 * 1298 * <h5 class='section'>Example:</h5> 1299 * <p class='bjava'> 1300 * <ja>@Rest</ja>( 1301 * path=<js>"/addressBook"</js>, 1302 * 1303 * <jc>// Swagger info.</jc> 1304 * swagger=@Swagger({ 1305 * <js>"contact:{name:'John Smith',email:'john@smith.com'},"</js>, 1306 * <js>"license:{name:'Apache 2.0',url:'http://www.apache.org/licenses/LICENSE-2.0.html'},"</js>, 1307 * <js>"version:'2.0',</js>, 1308 * <js>"termsOfService:'You are on your own.',"</js>, 1309 * <js>"tags:[{name:'Java',description:'Java utility',externalDocs:{description:'Home page',url:'http://juneau.apache.org'}}],"</js>, 1310 * <js>"externalDocs:{description:'Home page',url:'http://juneau.apache.org'}"</js> 1311 * }) 1312 * ) 1313 * </p> 1314 * 1315 * <h5 class='section'>See Also:</h5><ul> 1316 * <li class='ja'>{@link Swagger} 1317 * </ul> 1318 * 1319 * @return The annotation value. 1320 */ 1321 Swagger swagger() default @Swagger; 1322 1323 /** 1324 * Swagger provider. 1325 * 1326 * <h5 class='section'>See Also:</h5><ul> 1327 * <li class='jm'>{@link org.apache.juneau.rest.RestContext.Builder#swaggerProvider(Class)} 1328 * </ul> 1329 * 1330 * @return The annotation value. 1331 */ 1332 Class<? extends SwaggerProvider> swaggerProvider() default SwaggerProvider.Void.class; 1333 1334 /** 1335 * Optional servlet title. 1336 * 1337 * <p> 1338 * It is used to populate the Swagger title field. 1339 * 1340 * <h5 class='section'>Inheritance Rules</h5> 1341 * <ul> 1342 * <li>Label is searched for in child-to-parent order. 1343 * </ul> 1344 * 1345 * <h5 class='section'>Notes:</h5><ul> 1346 * <li class='note'> 1347 * Supports <a class="doclink" href="https://juneau.apache.org/docs/topics/RestServerSvlVariables">SVL Variables</a> 1348 * (e.g. <js>"$L{my.localized.variable}"</js>). 1349 * <li class='note'> 1350 * Corresponds to the swagger field <c>/info/title</c>. 1351 * </ul> 1352 * 1353 * @return The annotation value. 1354 */ 1355 String[] title() default {}; 1356 1357 /** 1358 * Resource authority path. 1359 * 1360 * <p> 1361 * Overrides the authority path value for this resource and any child resources. 1362 * 1363 * <h5 class='section'>Notes:</h5><ul> 1364 * <li class='note'> 1365 * Supports <a class="doclink" href="https://juneau.apache.org/docs/topics/RestServerSvlVariables">SVL Variables</a> 1366 * (e.g. <js>"$L{my.localized.variable}"</js>). 1367 * </ul> 1368 * 1369 * <h5 class='section'>See Also:</h5><ul> 1370 * <li class='jm'>{@link org.apache.juneau.rest.RestContext.Builder#uriAuthority(String)} 1371 * </ul> 1372 * 1373 * @return The annotation value. 1374 */ 1375 String uriAuthority() default ""; 1376 1377 /** 1378 * Resource context path. 1379 * 1380 * <p> 1381 * Overrides the context path value for this resource and any child resources. 1382 * 1383 * <h5 class='section'>Notes:</h5><ul> 1384 * <li class='note'> 1385 * Supports <a class="doclink" href="https://juneau.apache.org/docs/topics/RestServerSvlVariables">SVL Variables</a> 1386 * (e.g. <js>"$L{my.localized.variable}"</js>). 1387 * </ul> 1388 * 1389 * <h5 class='section'>See Also:</h5><ul> 1390 * <li class='jm'>{@link org.apache.juneau.rest.RestContext.Builder#uriContext(String)} 1391 * </ul> 1392 * 1393 * @return The annotation value. 1394 */ 1395 String uriContext() default ""; 1396 1397 /** 1398 * URI-resolution relativity. 1399 * 1400 * <p> 1401 * Specifies how relative URIs should be interpreted by serializers. 1402 * 1403 * <p> 1404 * See {@link UriResolution} for possible values. 1405 * 1406 * <h5 class='section'>Notes:</h5><ul> 1407 * <li class='note'> 1408 * Supports <a class="doclink" href="https://juneau.apache.org/docs/topics/RestServerSvlVariables">SVL Variables</a> 1409 * (e.g. <js>"$L{my.localized.variable}"</js>). 1410 * </ul> 1411 * 1412 * <h5 class='section'>See Also:</h5><ul> 1413 * <li class='jm'>{@link org.apache.juneau.rest.RestContext.Builder#uriRelativity(UriRelativity)} 1414 * </ul> 1415 * 1416 * @return The annotation value. 1417 */ 1418 String uriRelativity() default ""; 1419 1420 /** 1421 * URI-resolution. 1422 * 1423 * <p> 1424 * Specifies how relative URIs should be interpreted by serializers. 1425 * 1426 * <p> 1427 * See {@link UriResolution} for possible values. 1428 * 1429 * <h5 class='section'>Notes:</h5><ul> 1430 * <li class='note'> 1431 * Supports <a class="doclink" href="https://juneau.apache.org/docs/topics/RestServerSvlVariables">SVL Variables</a> 1432 * (e.g. <js>"$L{my.localized.variable}"</js>). 1433 * </ul> 1434 * 1435 * <h5 class='section'>See Also:</h5><ul> 1436 * <li class='jm'>{@link org.apache.juneau.rest.RestContext.Builder#uriResolution(UriResolution)} 1437 * </ul> 1438 * 1439 * @return The annotation value. 1440 */ 1441 String uriResolution() default ""; 1442}