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