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