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