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.encoders.*; 024import org.apache.juneau.httppart.*; 025import org.apache.juneau.rest.*; 026import org.apache.juneau.utils.*; 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 juneau-rest-server.Rest} 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 DefaultRestSvlVariables} 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 DefaultRestSvlVariables} 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 DefaultRestSvlVariables} 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 DefaultRestSvlVariables} 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 * <p> 166 * This class handles the basic lifecycle of an HTTP REST call. 167 * 168 * <ul class='seealso'> 169 * <li class='jf'>{@link RestContext#REST_callHandler} 170 * </ul> 171 */ 172 Class<? extends RestCallHandler> callHandler() default RestCallHandler.Null.class; 173 174 /** 175 * REST children. 176 * 177 * <p> 178 * Defines children of this resource. 179 * 180 * <ul class='seealso'> 181 * <li class='jf'>{@link RestContext#REST_children} 182 * </ul> 183 */ 184 Class<?>[] children() default {}; 185 186 /** 187 * Classpath resource finder. 188 * 189 * <p> 190 * Used to retrieve localized files from the classpath. 191 * 192 * <ul class='seealso'> 193 * <li class='jf'>{@link RestContext#REST_classpathResourceFinder} 194 * </ul> 195 */ 196 Class<? extends ClasspathResourceFinder> classpathResourceFinder() default ClasspathResourceFinder.Null.class; 197 198 /** 199 * Client version header. 200 * 201 * <p> 202 * Specifies the name of the header used to denote the client version on HTTP requests. 203 * 204 * <ul class='notes'> 205 * <li> 206 * Supports {@doc DefaultRestSvlVariables} 207 * (e.g. <js>"$L{my.localized.variable}"</js>). 208 * </ul> 209 * 210 * <ul class='seealso'> 211 * <li class='jf'>{@link RestContext#REST_clientVersionHeader} 212 * </ul> 213 */ 214 String clientVersionHeader() default ""; 215 216 /** 217 * Optional location of configuration file for this servlet. 218 * 219 * <p> 220 * The configuration file . 221 * 222 * <ul class='notes'> 223 * <li> 224 * Supports {@doc DefaultRestSvlVariables} 225 * (e.g. <js>"$L{my.localized.variable}"</js>). 226 * <li> 227 * Use the keyword <c>SYSTEM_DEFAULT</c> to refer to the system default configuration 228 * returned by the {@link Config#getSystemDefault()}. 229 * </ul> 230 * 231 * <ul class='seealso'> 232 * <li class='jm'>{@link RestContextBuilder#config(Config)} 233 * </ul> 234 */ 235 String config() default ""; 236 237 /** 238 * Class-level response converters. 239 * 240 * <p> 241 * Associates one or more {@link RestConverter converters} with a resource class. 242 * 243 * <ul class='seealso'> 244 * <li class='jf'>{@link RestContext#REST_converters} 245 * </ul> 246 */ 247 Class<? extends RestConverter>[] converters() default {}; 248 249 /** 250 * Default <c>Accept</c> header. 251 * 252 * <p> 253 * The default value for the <c>Accept</c> header if not specified on a request. 254 * 255 * <p> 256 * This is a shortcut for using {@link #reqHeaders()} for just this specific header. 257 * 258 * <ul class='notes'> 259 * <li> 260 * Supports {@doc DefaultRestSvlVariables} 261 * (e.g. <js>"$L{my.localized.variable}"</js>). 262 * </ul> 263 */ 264 String defaultAccept() default ""; 265 266 /** 267 * Default character encoding. 268 * 269 * <p> 270 * The default character encoding for the request and response if not specified on the request. 271 * 272 * <ul class='notes'> 273 * <li> 274 * Supports {@doc DefaultRestSvlVariables} 275 * (e.g. <js>"$L{my.localized.variable}"</js>). 276 * </ul> 277 * 278 * <ul class='seealso'> 279 * <li class='jf'>{@link RestContext#REST_defaultCharset} 280 * </ul> 281 */ 282 String defaultCharset() default ""; 283 284 /** 285 * Default <c>Content-Type</c> header. 286 * 287 * <p> 288 * The default value for the <c>Content-Type</c> header if not specified on a request. 289 * 290 * <p> 291 * This is a shortcut for using {@link #reqHeaders()} for just this specific header. 292 * 293 * <ul class='notes'> 294 * <li> 295 * Supports {@doc DefaultRestSvlVariables} 296 * (e.g. <js>"$L{my.localized.variable}"</js>). 297 * </ul> 298 */ 299 String defaultContentType() default ""; 300 301 /** 302 * Default request headers. 303 * 304 * <div class='warn'> 305 * <b>Deprecated</b> - Use {@link #reqHeaders()} 306 * </div> 307 */ 308 @Deprecated 309 String[] defaultRequestHeaders() default {}; 310 311 /** 312 * Default response headers. 313 * 314 * <div class='warn'> 315 * <b>Deprecated</b> - Use {@link #resHeaders()} 316 * </div> 317 */ 318 @Deprecated 319 String[] defaultResponseHeaders() default {}; 320 321 /** 322 * Optional servlet description. 323 * 324 * <p> 325 * It is used to populate the Swagger description field. 326 * <br>This value can be retrieved programmatically through the {@link RestRequest#getResourceDescription()} method. 327 * 328 * <ul class='notes'> 329 * <li> 330 * Supports {@doc DefaultRestSvlVariables} 331 * (e.g. <js>"$L{my.localized.variable}"</js>). 332 * <li> 333 * The format is plain-text. 334 * <br>Multiple lines are concatenated with newlines. 335 * </ul> 336 * 337 * <ul class='seealso'> 338 * <li class='jm'>{@link RestInfoProvider#getDescription(RestRequest)} 339 * </ul> 340 */ 341 String[] description() default {}; 342 343 /** 344 * Compression encoders. 345 * 346 * <p> 347 * These can be used to enable various kinds of compression (e.g. <js>"gzip"</js>) on requests and responses. 348 * 349 * <ul class='seealso'> 350 * <li class='jf'>{@link RestContext#REST_encoders} 351 * </ul> 352 */ 353 Class<? extends Encoder>[] encoders() default {}; 354 355 /** 356 * Shortcut for setting {@link #properties()} of simple boolean types. 357 * 358 * <ul class='notes'> 359 * <li> 360 * Supports {@doc DefaultRestSvlVariables} 361 * (e.g. <js>"$L{my.localized.variable}"</js>). 362 * <li> 363 * Setting a flag is equivalent to setting the same property to <js>"true"</js>. 364 * </ul> 365 */ 366 String[] flags() default {}; 367 368 /** 369 * Class-level guards. 370 * 371 * <p> 372 * Associates one or more {@link RestGuard RestGuards} with all REST methods defined in this class. 373 * 374 * <ul class='seealso'> 375 * <li class='jf'>{@link RestContext#REST_guards} 376 * </ul> 377 */ 378 Class<? extends RestGuard>[] guards() default {}; 379 380 /** 381 * Configuration property: REST info provider. 382 * 383 * <p> 384 * Class used to retrieve title/description/swagger information about a resource. 385 * 386 * <ul class='seealso'> 387 * <li class='jf'>{@link RestContext#REST_infoProvider} 388 * </ul> 389 */ 390 Class<? extends RestInfoProvider> infoProvider() default RestInfoProvider.Null.class; 391 392 /** 393 * Specifies the logger to use for logging of HTTP requests and responses. 394 * 395 * <ul class='seealso'> 396 * <li class='jf'>{@link RestContext#REST_callLogger} 397 * <li class='link'>{@doc juneau-rest-server.LoggingAndDebugging} 398 * </ul> 399 */ 400 Class<? extends RestCallLogger> callLogger() default RestCallLogger.Null.class; 401 402 /** 403 * Specifies rules on how to handle logging of HTTP requests/responses. 404 * 405 * <ul class='seealso'> 406 * <li class='jf'>{@link RestContext#REST_callLoggerConfig} 407 * <li class='link'>{@doc juneau-rest-server.LoggingAndDebugging} 408 * </ul> 409 */ 410 Logging logging() default @Logging; 411 412 /** 413 * The maximum allowed input size (in bytes) on HTTP requests. 414 * 415 * <p> 416 * Useful for alleviating DoS attacks by throwing an exception when too much input is received instead of resulting 417 * in out-of-memory errors which could affect system stability. 418 * 419 * <ul class='notes'> 420 * <li> 421 * Supports {@doc DefaultRestSvlVariables} 422 * (e.g. <js>"$L{my.localized.variable}"</js>). 423 * </ul> 424 * 425 * <ul class='seealso'> 426 * <li class='jf'>{@link RestContext#REST_maxInput} 427 * </ul> 428 */ 429 String maxInput() default ""; 430 431 /** 432 * Messages. 433 * 434 * Identifies the location of the resource bundle for this class. 435 * 436 * <ul class='notes'> 437 * <li> 438 * Supports {@doc DefaultRestSvlVariables} 439 * (e.g. <js>"$L{my.localized.variable}"</js>). 440 * </ul> 441 * 442 * <ul class='seealso'> 443 * <li class='jf'>{@link RestContext#REST_messages} 444 * </ul> 445 */ 446 String messages() default ""; 447 448 /** 449 * Configuration property: MIME types. 450 * 451 * <p> 452 * Defines MIME-type file type mappings. 453 * 454 * <ul class='notes'> 455 * <li> 456 * Supports {@doc DefaultRestSvlVariables} 457 * (e.g. <js>"$L{my.localized.variable}"</js>). 458 * </ul> 459 * 460 * <ul class='seealso'> 461 * <li class='jf'>{@link RestContext#REST_mimeTypes} 462 * </ul> 463 */ 464 String[] mimeTypes() default {}; 465 466 /** 467 * Java method parameter resolvers. 468 * 469 * <p> 470 * By default, the Juneau framework will automatically Java method parameters of various types (e.g. 471 * <c>RestRequest</c>, <c>Accept</c>, <c>Reader</c>). 472 * <br>This setting allows you to provide your own resolvers for your own class types that you want resolved. 473 * 474 * <ul class='seealso'> 475 * <li class='jf'>{@link RestContext#REST_paramResolvers} 476 * </ul> 477 */ 478 Class<? extends RestMethodParam>[] paramResolvers() default {}; 479 480 /** 481 * Parsers. 482 * 483 * <p> 484 * If no value is specified, the parsers are inherited from parent class. 485 * <br>Otherwise, this value overrides the parsers defined on the parent class. 486 * 487 * <p> 488 * Use {@link Inherit} to inherit parsers defined on the parent class. 489 * 490 * <p> 491 * Use {@link None} to suppress inheriting parsers defined on the parent class. 492 * 493 * <ul class='seealso'> 494 * <li class='jf'>{@link RestContext#REST_parsers} 495 * </ul> 496 */ 497 Class<?>[] parsers() default {}; 498 499 /** 500 * HTTP part parser. 501 * 502 * <p> 503 * Specifies the {@link HttpPartParser} to use for parsing headers, query/form parameters, and URI parts. 504 * 505 * <ul class='seealso'> 506 * <li class='jf'>{@link RestContext#REST_partParser} 507 * </ul> 508 */ 509 Class<? extends HttpPartParser> partParser() default HttpPartParser.Null.class; 510 511 /** 512 * HTTP part serializer. 513 * 514 * <p> 515 * Specifies the {@link HttpPartSerializer} to use for serializing headers, query/form parameters, and URI parts. 516 * 517 * <ul class='seealso'> 518 * <li class='jf'>{@link RestContext#REST_partSerializer} 519 * </ul> 520 */ 521 Class<? extends HttpPartSerializer> partSerializer() default HttpPartSerializer.Null.class; 522 523 /** 524 * Resource path. 525 * 526 * <p> 527 * Used in the following situations: 528 * <ul class='spaced-list'> 529 * <li> 530 * On child resources (resource classes attached to parents via the {@link #children()} annotation) to identify 531 * the subpath used to access the child resource relative to the parent. 532 * <li> 533 * On top-level {@link RestServlet} classes deployed as Spring beans when <c>JuneauRestInitializer</c> is being used. 534 * </ul> 535 * 536 * <h5 class='topic'>On child resources</h5> 537 * <p> 538 * The typical usage is to define a path to a child resource relative to the parent resource. 539 * 540 * <h5 class='figure'>Example:</h5> 541 * <p class='bpcode'> 542 * <ja>@Rest</ja>( 543 * children={ChildResource.<jk>class</jk>} 544 * ) 545 * <jk>public class</jk> TopLevelResource <jk>extends</jk> BasicRestServlet {...} 546 * 547 * <ja>@Rest</ja>( 548 * path=<js>"/child"</js>, 549 * children={GrandchildResource.<jk>class</jk>} 550 * ) 551 * <jk>public class</jk> ChildResource {...} 552 * 553 * <ja>@Rest</ja>( 554 * path=<js>"/grandchild"</js> 555 * ) 556 * <jk>public class</jk> GrandchildResource { 557 * <ja>@RestMethod</ja>( 558 * path=<js>"/"</js> 559 * ) 560 * <jk>public</jk> String sayHello() { 561 * <jk>return</jk> <js>"Hello!"</js>; 562 * } 563 * } 564 * </p> 565 * <p> 566 * In the example above, assuming the <c>TopLevelResource</c> servlet is deployed to path <c>/myContext/myServlet</c>, 567 * then the <c>sayHello</c> method is accessible through the URI <c>/myContext/myServlet/child/grandchild</c>. 568 * 569 * <p> 570 * Note that in this scenario, the <c>path</c> attribute is not defined on the top-level resource. 571 * Specifying the path on the top-level resource has no effect, but can be used for readability purposes. 572 * 573 * <h5 class='topic'>On top-level resources deployed as Spring beans</h5> 574 * <p> 575 * The path can also be used on top-level resources deployed as Spring beans when used with the <c>JuneauRestInitializer</c> 576 * Spring Boot initializer class: 577 * 578 * <h5 class='figure'>Example:</h5> 579 * <p class='bpcode'> 580 * <ja>@SpringBootApplication</ja> 581 * <ja>@Controller</ja> 582 * <jk>public class</jk> App { 583 * 584 * <jc>// Our entry-point method.</jc> 585 * <jk>public static void</jk> main(String[] args) { 586 * <jk>new</jk> SpringApplicationBuilder(App.<jk>class</jk>) 587 * .initializers(<jk>new</jk> JuneauRestInitializer(App.<jk>class</jk>)) 588 * .run(args); 589 * } 590 * 591 * <jc>// Our top-level servlet.</jc> 592 * <ja>@Bean</ja> 593 * <ja>@JuneauRestRoot</ja> 594 * <jk>public</jk> MyResource getMyResource() { 595 * <jk>return new</jk> MyResource(); 596 * } 597 * } 598 * 599 * <ja>@Rest</ja>( 600 * path=<js>"/myResource"</js> 601 * ) 602 * <jk>public class</jk> MyResource <jk>extends</jk> BasicRestServlet {...} 603 * </p> 604 * 605 * <p> 606 * In this case, the servlet will get registered using the path defined on the resource class. 607 * 608 * <h5 class='topic'>Path variables</h5> 609 * <p> 610 * The path can contain variables that get resolved to {@link org.apache.juneau.http.annotation.Path @Path} parameters 611 * or access through the {@link RestRequest#getPathMatch()} method. 612 * 613 * <h5 class='figure'>Example:</h5> 614 * <p class='bpcode'> 615 * <ja>@Rest</ja>( 616 * path=<js>"/myResource/{foo}/{bar}"</js> 617 * ) 618 * <jk>public class</jk> MyResource <jk>extends</jk> BasicRestServlet { 619 * 620 * <ja>@RestMethod</ja>( 621 * path=<js>"/{baz}"</js> 622 * ) 623 * <jk>public void</jk> String doX(<ja>@Path</ja> String foo, <ja>@Path</ja> <jk>int</jk> bar, <ja>@Path</ja> MyPojo baz) { 624 * ... 625 * } 626 * } 627 * </p> 628 * 629 * <p> 630 * Variables can be used on either top-level or child resources and can be defined on multiple levels. 631 * 632 * <p> 633 * All variables in the path must be specified or else the target will not resolve and a <c>404</c> will result. 634 * 635 * <p> 636 * When variables are used on a path of a top-level resource deployed as a Spring bean in a Spring Boot application, 637 * the first part of the URL must be a literal which will be used as the servlet path of the registered servlet. 638 * 639 * <ul class='notes'> 640 * <li> 641 * The leading slash is optional. <js>"/myResource"</js> and <js>"myResource"</js> is equivalent. 642 * <li> 643 * The paths <js>"/myResource"</js> and <js>"/myResource/*"</js> are equivalent. 644 * <li> 645 * Paths must not end with <js>"/"</js> (per the servlet spec). 646 * </ul> 647 * 648 * <ul class='seealso'> 649 * <li class='jf'>{@link RestContext#REST_path} 650 * </ul> 651 */ 652 String path() default ""; 653 654 /** 655 * Class-level properties. 656 * 657 * <p> 658 * Shortcut to add properties to the bean contexts of all serializers and parsers on all methods in the class. 659 * 660 * <p> 661 * Any of the properties defined on {@link RestContext} or any of the serializers and parsers can be specified. 662 * 663 * <p> 664 * Property values will be converted to the appropriate type. 665 * 666 * <ul class='notes'> 667 * <li> 668 * Supports {@doc DefaultRestSvlVariables} 669 * (e.g. <js>"$L{my.localized.variable}"</js>). 670 * </ul> 671 * 672 * <ul class='seealso'> 673 * <li class='jm'>{@link RestContextBuilder#set(String,Object)} 674 * <li class='jm'>{@link RestContextBuilder#set(java.util.Map)} 675 * </ul> 676 */ 677 Property[] properties() default {}; 678 679 /** 680 * Render response stack traces in responses. 681 * 682 * <p> 683 * Render stack traces in HTTP response bodies when errors occur. 684 * 685 * <ul class='notes'> 686 * <li> 687 * Supports {@doc DefaultRestSvlVariables} 688 * (e.g. <js>"$L{my.localized.variable}"</js>). 689 * </ul> 690 * 691 * <ul class='seealso'> 692 * <li class='jf'>{@link RestContext#REST_renderResponseStackTraces} 693 * </ul> 694 */ 695 String renderResponseStackTraces() default ""; 696 697 /** 698 * Default request attributes. 699 * 700 * <p> 701 * Specifies default values for request attributes if they're not already set on the request. 702 * 703 * <ul class='notes'> 704 * <li> 705 * Supports {@doc DefaultRestSvlVariables} 706 * (e.g. <js>"$L{my.localized.variable}"</js>). 707 * </ul> 708 * 709 * <ul class='seealso'> 710 * <li class='jf'>{@link RestContext#REST_reqAttrs} 711 * </ul> 712 */ 713 String[] reqAttrs() default {}; 714 715 /** 716 * Default request headers. 717 * 718 * <p> 719 * Specifies default values for request headers if they're not passed in through the request. 720 * 721 * <ul class='notes'> 722 * <li> 723 * Supports {@doc DefaultRestSvlVariables} 724 * (e.g. <js>"$L{my.localized.variable}"</js>). 725 * </ul> 726 * 727 * <ul class='seealso'> 728 * <li class='jf'>{@link RestContext#REST_reqHeaders} 729 * </ul> 730 */ 731 String[] reqHeaders() default {}; 732 733 /** 734 * Default response headers. 735 * 736 * <p> 737 * Specifies default values for response headers if they're not set after the Java REST method is called. 738 * 739 * <ul class='notes'> 740 * <li> 741 * Supports {@doc DefaultRestSvlVariables} 742 * (e.g. <js>"$L{my.localized.variable}"</js>). 743 * </ul> 744 * 745 * <ul class='seealso'> 746 * <li class='jf'>{@link RestContext#REST_resHeaders} 747 * </ul> 748 */ 749 String[] resHeaders() default {}; 750 751 /** 752 * REST resource resolver. 753 * 754 * <p> 755 * The resolver used for resolving child resources. 756 * 757 * <ul class='seealso'> 758 * <li class='jf'>{@link RestContext#REST_resourceResolver} 759 * </ul> 760 */ 761 Class<? extends RestResourceResolver> resourceResolver() default RestResourceResolver.Null.class; 762 763 /** 764 * Response handlers. 765 * 766 * <p> 767 * Specifies a list of {@link ResponseHandler} classes that know how to convert POJOs returned by REST methods or 768 * set via {@link RestResponse#setOutput(Object)} into appropriate HTTP responses. 769 * 770 * <ul class='seealso'> 771 * <li class='jf'>{@link RestContext#REST_responseHandlers} 772 * </ul> 773 */ 774 Class<? extends ResponseHandler>[] responseHandlers() default {}; 775 776 /** 777 * Declared roles. 778 * 779 * <p> 780 * A comma-delimited list of all possible user roles. 781 * 782 * <p> 783 * Used in conjunction with {@link #roleGuard()} is used with patterns. 784 * 785 * <h5 class='section'>Example:</h5> 786 * <p class='bcode w800'> 787 * <ja>@Rest</ja>( 788 * rolesDeclared=<js>"ROLE_ADMIN,ROLE_READ_WRITE,ROLE_READ_ONLY,ROLE_SPECIAL"</js>, 789 * roleGuard=<js>"ROLE_ADMIN || (ROLE_READ_WRITE && ROLE_SPECIAL)"</js> 790 * ) 791 * <jk>public class</jk> MyResource <jk>extends</jk> RestServlet { 792 * ... 793 * } 794 * </p> 795 * 796 * <ul class='seealso'> 797 * <li class='jf'>{@link RestContext#REST_rolesDeclared} 798 * </ul> 799 */ 800 String rolesDeclared() default ""; 801 802 /** 803 * Role guard. 804 * 805 * <p> 806 * An expression defining if a user with the specified roles are allowed to access methods on this class. 807 * 808 * <h5 class='section'>Example:</h5> 809 * <p class='bcode w800'> 810 * <ja>@Rest</ja>( 811 * path=<js>"/foo"</js>, 812 * roleGuard=<js>"ROLE_ADMIN || (ROLE_READ_WRITE && ROLE_SPECIAL)"</js> 813 * ) 814 * <jk>public class</jk> MyResource <jk>extends</jk> RestServlet { 815 * ... 816 * } 817 * </p> 818 * 819 * <ul class='notes'> 820 * <li> 821 * Supports any of the following expression constructs: 822 * <ul> 823 * <li><js>"foo"</js> - Single arguments. 824 * <li><js>"foo,bar,baz"</js> - Multiple OR'ed arguments. 825 * <li><js>"foo | bar | baz"</js> - Multiple OR'ed arguments, pipe syntax. 826 * <li><js>"foo || bar || baz"</js> - Multiple OR'ed arguments, Java-OR syntax. 827 * <li><js>"fo*"</js> - Patterns including <js>'*'</js> and <js>'?'</js>. 828 * <li><js>"fo* & *oo"</js> - Multiple AND'ed arguments, ampersand syntax. 829 * <li><js>"fo* && *oo"</js> - Multiple AND'ed arguments, Java-AND syntax. 830 * <li><js>"fo* || (*oo || bar)"</js> - Parenthesis. 831 * </ul> 832 * <li> 833 * AND operations take precedence over OR operations (as expected). 834 * <li> 835 * Whitespace is ignored. 836 * <li> 837 * <jk>null</jk> or empty expressions always match as <jk>false</jk>. 838 * <li> 839 * If patterns are used, you must specify the list of declared roles using {@link #rolesDeclared()} or {@link RestContext#REST_rolesDeclared}. 840 * <li> 841 * Supports {@doc DefaultRestSvlVariables} 842 * (e.g. <js>"$L{my.localized.variable}"</js>). 843 * </ul> 844 * 845 * <ul class='seealso'> 846 * <li class='jf'>{@link RestContext#REST_roleGuard} 847 * </ul> 848 */ 849 String roleGuard() default ""; 850 851 /** 852 * Serializers. 853 * 854 * <p> 855 * If no value is specified, the serializers are inherited from parent class. 856 * <br>Otherwise, this value overrides the serializers defined on the parent class. 857 * 858 * <p> 859 * Use {@link Inherit} to inherit serializers defined on the parent class. 860 * 861 * <p> 862 * Use {@link None} to suppress inheriting serializers defined on the parent class. 863 * 864 * <ul class='seealso'> 865 * <li class='jf'>{@link RestContext#REST_serializers} 866 * </ul> 867 */ 868 Class<?>[] serializers() default {}; 869 870 /** 871 * Optional site name. 872 * 873 * <p> 874 * The site name is intended to be a title that can be applied to the entire site. 875 * 876 * <p> 877 * This value can be retrieved programmatically through the {@link RestRequest#getSiteName()} method. 878 * 879 * <p> 880 * One possible use is if you want to add the same title to the top of all pages by defining a header on a 881 * common parent class like so: 882 * <p class='bcode w800'> 883 * <ja>@HtmlDocConfig</ja>( 884 * header={ 885 * <js>"<h1>$R{siteName}</h1>"</js>, 886 * <js>"<h2>$R{resourceTitle}</h2>"</js> 887 * } 888 * ) 889 * </p> 890 * 891 * <ul class='notes'> 892 * <li> 893 * Supports {@doc DefaultRestSvlVariables} 894 * (e.g. <js>"$L{my.localized.variable}"</js>). 895 * </ul> 896 * 897 * <ul class='seealso'> 898 * <li class='jm'>{@link RestInfoProvider#getSiteName(RestRequest)} 899 * </ul> 900 */ 901 String siteName() default ""; 902 903 /** 904 * Static file response headers. 905 * 906 * <p> 907 * Used to customize the headers on responses returned for statically-served files. 908 * 909 * <h5 class='section'>Example:</h5> 910 * <p class='bcode w800'> 911 * <jc>// Option #1 - Defined via annotation resolving to a config file setting with default value.</jc> 912 * <ja>@Rest</ja>( 913 * staticFileResponseHeaders={ 914 * <js>"Cache-Control: $C{REST/cacheControl,nocache}"</js>, 915 * <js>"My-Header: $C{REST/myHeaderValue}"</js> 916 * } 917 * ) 918 * <jk>public class</jk> MyResource { 919 * 920 * <jc>// Option #2 - Defined via builder passed in through resource constructor.</jc> 921 * <jk>public</jk> MyResource(RestContextBuilder builder) <jk>throws</jk> Exception { 922 * 923 * <jc>// Using method on builder.</jc> 924 * builder 925 * .staticFileResponseHeader(<js>"Cache-Control"</js>, <js>"nocache"</js>); 926 * .staticFileResponseHeaders(<js>"My-Header: foo"</js>); 927 * 928 * <jc>// Same, but using property.</jc> 929 * builder 930 * .addTo(<jsf>REST_staticFileResponseHeaders</jsf>, <js>"Cache-Control"</js>, <js>"nocache"</js>); 931 * .addTo(<jsf>REST_staticFileResponseHeaders</jsf>, <js>"My-Header"</js>, <js>"foo"</js>); 932 * } 933 * 934 * <jc>// Option #3 - Defined via builder passed in through init method.</jc> 935 * <ja>@RestHook</ja>(<jsf>INIT</jsf>) 936 * <jk>public void</jk> init(RestContextBuilder builder) <jk>throws</jk> Exception { 937 * builder.staticFileResponseHeader(<js>"Cache-Control"</js>, <js>"nocache"</js>); 938 * } 939 * } 940 * </p> 941 * 942 * <p> 943 * Note that headers can also be specified per path-mapping via the {@link Rest#staticFiles() Rest(staticFiles)} annotation. 944 * <p class='bcode w800'> 945 * <ja>@Rest</ja>( 946 * staticFiles={ 947 * <js>"htdocs:docs:{'Cache-Control':'max-age=86400, public'}"</js> 948 * } 949 * ) 950 * </p> 951 * 952 * <ul class='notes'> 953 * <li> 954 * Supports {@doc DefaultRestSvlVariables} 955 * (e.g. <js>"$L{my.localized.variable}"</js>). 956 * </ul> 957 * 958 * <ul class='seealso'> 959 * <li class='jf'>{@link RestContext#REST_staticFileResponseHeaders} 960 * </ul> 961 */ 962 String[] staticFileResponseHeaders() default {}; 963 964 /** 965 * Static file mappings. 966 * 967 * <p> 968 * Used to define paths and locations of statically-served files such as images or HTML documents 969 * from the classpath or file system. 970 * 971 * <p> 972 * The format of the value is one of the following: 973 * <ol class='spaced-list'> 974 * <li><js>"path:location"</js> 975 * <li><js>"path:location:headers"</js> 976 * </ol> 977 * 978 * <p> 979 * An example where this class is used is in the {@link Rest#staticFiles} annotation: 980 * <p class='bcode w800'> 981 * <jk>package</jk> com.foo.mypackage; 982 * 983 * <ja>@Rest</ja>( 984 * path=<js>"/myresource"</js>, 985 * staticFiles={ 986 * <js>"htdocs:docs"</js>, 987 * <js>"styles:styles"</js> 988 * } 989 * ) 990 * <jk>public class</jk> MyResource <jk>extends</jk> BasicRestServlet {...} 991 * </p> 992 * 993 * <p> 994 * In the example above, given a GET request to the following URL... 995 * <p class='bcode w800'> 996 * /myresource/htdocs/foobar.html 997 * </p> 998 * <br>...the servlet will attempt to find the <c>foobar.html</c> file in the following location: 999 * <ol class='spaced-list'> 1000 * <li><c>com.foo.mypackage.docs</c> package. 1001 * </ol> 1002 * 1003 * <p> 1004 * The location is interpreted as an absolute path if it starts with <js>'/'</js>. 1005 * <p class='bcode w800'> 1006 * <ja>@Rest</ja>( 1007 * staticFiles={ 1008 * <js>"htdocs:/docs"</js> 1009 * } 1010 * ) 1011 * </p> 1012 * <p> 1013 * In the example above, given a GET request to the following URL... 1014 * <p class='bcode w800'> 1015 * /myresource/htdocs/foobar.html 1016 * </p> 1017 * <br>...the servlet will attempt to find the <c>foobar.html</c> file in the following location: 1018 * <ol class='spaced-list'> 1019 * <li><c>docs</c> package (typically under <c>src/main/resources/docs</c> in your workspace). 1020 * <li><c>[working-dir]/docs</c> directory at runtime. 1021 * </ol> 1022 * 1023 * <p> 1024 * Response headers can be specified for served files by adding a 3rd section that consists of a {@doc SimpleJson} object. 1025 * <p class='bcode w800'> 1026 * <ja>@Rest</ja>( 1027 * staticFiles={ 1028 * <js>"htdocs:docs:{'Cache-Control':'max-age=86400, public'}"</js> 1029 * } 1030 * ) 1031 * </p> 1032 * 1033 * <p> 1034 * The same path can map to multiple locations. Files are searched in the order 1035 * <p class='bcode w800'> 1036 * <ja>@Rest</ja>( 1037 * staticFiles={ 1038 * <jc>// Search in absolute location '/htdocs/folder' before location 'htdocs.package' relative to servlet package.</jc> 1039 * <js>"htdocs:/htdocs/folder,htdocs:htdocs.package"</js> 1040 * } 1041 * ) 1042 * </p> 1043 * 1044 * <ul class='notes'> 1045 * <li> 1046 * Mappings are cumulative from super classes. 1047 * <li> 1048 * Child resources can override mappings made on parent class resources. 1049 * <br>When both parent and child resources map against the same path, files will be search in the child location 1050 * and then the parent location. 1051 * <li> 1052 * Supports {@doc DefaultRestSvlVariables} 1053 * (e.g. <js>"$L{my.localized.variable}"</js>). 1054 * </ul> 1055 * 1056 * <ul class='seealso'> 1057 * <li class='jf'>{@link RestContext#REST_staticFiles} 1058 * </ul> 1059 */ 1060 String[] staticFiles() default {}; 1061 1062 /** 1063 * Supported accept media types. 1064 * 1065 * <p> 1066 * Overrides the media types inferred from the serializers that identify what media types can be produced by the resource. 1067 * 1068 * <ul class='notes'> 1069 * <li> 1070 * Supports {@doc DefaultRestSvlVariables} 1071 * (e.g. <js>"$L{my.localized.variable}"</js>). 1072 * </ul> 1073 * 1074 * <ul class='seealso'> 1075 * <li class='jf'>{@link RestContext#REST_produces} 1076 * </ul> 1077 */ 1078 String[] produces() default {}; 1079 1080 /** 1081 * Supported content media types. 1082 * 1083 * <p> 1084 * Overrides the media types inferred from the parsers that identify what media types can be consumed by the resource. 1085 * 1086 * <ul class='notes'> 1087 * <li> 1088 * Supports {@doc DefaultRestSvlVariables} 1089 * (e.g. <js>"$L{my.localized.variable}"</js>). 1090 * </ul> 1091 * 1092 * <ul class='seealso'> 1093 * <li class='jf'>{@link RestContext#REST_consumes} 1094 * </ul> 1095 */ 1096 String[] consumes() default {}; 1097 1098 /** 1099 * Provides swagger-specific metadata on this resource. 1100 * 1101 * <p> 1102 * Used to populate the auto-generated OPTIONS swagger documentation. 1103 * 1104 * <h5 class='section'>Example:</h5> 1105 * <p class='bcode w800'> 1106 * <ja>@Rest</ja>( 1107 * path=<js>"/addressBook"</js>, 1108 * 1109 * <jc>// Swagger info.</jc> 1110 * swagger=@ResourceSwagger({ 1111 * <js>"contact:{name:'John Smith',email:'john@smith.com'},"</js>, 1112 * <js>"license:{name:'Apache 2.0',url:'http://www.apache.org/licenses/LICENSE-2.0.html'},"</js>, 1113 * <js>"version:'2.0',</js>, 1114 * <js>"termsOfService:'You are on your own.',"</js>, 1115 * <js>"tags:[{name:'Java',description:'Java utility',externalDocs:{description:'Home page',url:'http://juneau.apache.org'}}],"</js>, 1116 * <js>"externalDocs:{description:'Home page',url:'http://juneau.apache.org'}"</js> 1117 * }) 1118 * ) 1119 * </p> 1120 * 1121 * <ul class='seealso'> 1122 * <li class='ja'>{@link ResourceSwagger} 1123 * <li class='jm'>{@link RestInfoProvider#getSwagger(RestRequest)} 1124 * </ul> 1125 */ 1126 ResourceSwagger swagger() default @ResourceSwagger; 1127 1128 /** 1129 * Optional servlet title. 1130 * 1131 * <p> 1132 * It is used to populate the Swagger title field. 1133 * <br>This value can be retrieved programmatically through the {@link RestRequest#getResourceTitle()} method. 1134 * 1135 * <ul class='notes'> 1136 * <li> 1137 * Supports {@doc DefaultRestSvlVariables} 1138 * (e.g. <js>"$L{my.localized.variable}"</js>). 1139 * <li> 1140 * Corresponds to the swagger field <c>/info/title</c>. 1141 * </ul> 1142 * 1143 * <ul class='seealso'> 1144 * <li class='jm'>{@link RestInfoProvider#getTitle(RestRequest)} 1145 * </ul> 1146 */ 1147 String[] title() default {}; 1148 1149 /** 1150 * Resource authority path. 1151 * 1152 * <p> 1153 * Overrides the authority path value for this resource and any child resources. 1154 * 1155 * <ul class='notes'> 1156 * <li> 1157 * Supports {@doc DefaultRestSvlVariables} 1158 * (e.g. <js>"$L{my.localized.variable}"</js>). 1159 * </ul> 1160 * 1161 * <ul class='seealso'> 1162 * <li class='jf'>{@link RestContext#REST_uriAuthority} 1163 * </ul> 1164 */ 1165 String uriAuthority() default ""; 1166 1167 /** 1168 * Resource context path. 1169 * 1170 * <p> 1171 * Overrides the context path value for this resource and any child resources. 1172 * 1173 * <ul class='notes'> 1174 * <li> 1175 * Supports {@doc DefaultRestSvlVariables} 1176 * (e.g. <js>"$L{my.localized.variable}"</js>). 1177 * </ul> 1178 * 1179 * <ul class='seealso'> 1180 * <li class='jf'>{@link RestContext#REST_uriContext} 1181 * </ul> 1182 */ 1183 String uriContext() default ""; 1184 1185 /** 1186 * URI-resolution relativity. 1187 * 1188 * <p> 1189 * Specifies how relative URIs should be interpreted by serializers. 1190 * 1191 * <p> 1192 * See {@link UriResolution} for possible values. 1193 * 1194 * <ul class='notes'> 1195 * <li> 1196 * Supports {@doc DefaultRestSvlVariables} 1197 * (e.g. <js>"$L{my.localized.variable}"</js>). 1198 * </ul> 1199 * 1200 * <ul class='seealso'> 1201 * <li class='jf'>{@link RestContext#REST_uriRelativity} 1202 * </ul> 1203 */ 1204 String uriRelativity() default ""; 1205 1206 /** 1207 * URI-resolution. 1208 * 1209 * <p> 1210 * Specifies how relative URIs should be interpreted by serializers. 1211 * 1212 * <p> 1213 * See {@link UriResolution} for possible values. 1214 * 1215 * <ul class='notes'> 1216 * <li> 1217 * Supports {@doc DefaultRestSvlVariables} 1218 * (e.g. <js>"$L{my.localized.variable}"</js>). 1219 * </ul> 1220 * 1221 * <ul class='seealso'> 1222 * <li class='jf'>{@link RestContext#REST_uriResolution} 1223 * </ul> 1224 */ 1225 String uriResolution() default ""; 1226 1227 /** 1228 * Configuration property: Use classpath resource caching. 1229 * 1230 * <p> 1231 * When enabled, resources retrieved via {@link RestRequest#getClasspathReaderResource(String, boolean)} (and related 1232 * methods) will be cached in memory to speed subsequent lookups. 1233 * 1234 * <ul class='notes'> 1235 * <li> 1236 * Supports {@doc DefaultRestSvlVariables} 1237 * (e.g. <js>"$L{my.localized.variable}"</js>). 1238 * </ul> 1239 * 1240 * <ul class='seealso'> 1241 * <li class='jf'>{@link RestContext#REST_useClasspathResourceCaching} 1242 * </ul> 1243 */ 1244 String useClasspathResourceCaching() default ""; 1245 1246 /** 1247 * Enable debug mode. 1248 * 1249 * <p> 1250 * Enables the following: 1251 * <ul class='spaced-list'> 1252 * <li> 1253 * HTTP request/response bodies are cached in memory for logging purposes. 1254 * </ul> 1255 * 1256 * <p> 1257 * Possible values (case insensitive): 1258 * <ul> 1259 * <li><js>"true"</js> - Debug is enabled for all requests. 1260 * <li><js>"false"</js> - Debug is disabled for all requests. 1261 * <li><js>"per-request"</js> - Debug is enabled only for requests that have a <c class='snippet'>X-Debug: true</c> header. 1262 * </ul> 1263 * 1264 * <ul class='notes'> 1265 * <li> 1266 * Supports {@doc DefaultRestSvlVariables} 1267 * (e.g. <js>"$L{my.localized.variable}"</js>). 1268 * </ul> 1269 * 1270 * <ul class='seealso'> 1271 * <li class='jf'>{@link RestContext#REST_debug} 1272 * </ul> 1273 */ 1274 String debug() default ""; 1275}