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