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 * <h5 class='section'>Example:</h5> 1036 * <p class='bcode w800'> 1037 * <jc>// Option #1 - Defined via annotation resolving to a config file setting with default value.</jc> 1038 * <ja>@RestResource</ja>( 1039 * staticFileResponseHeaders={ 1040 * <js>"Cache-Control: $C{REST/cacheControl,nocache}"</js>, 1041 * <js>"My-Header: $C{REST/myHeaderValue}"</js> 1042 * } 1043 * ) 1044 * <jk>public class</jk> MyResource { 1045 * 1046 * <jc>// Option #2 - Defined via builder passed in through resource constructor.</jc> 1047 * <jk>public</jk> MyResource(RestContextBuilder builder) <jk>throws</jk> Exception { 1048 * 1049 * <jc>// Using method on builder.</jc> 1050 * builder 1051 * .staticFileResponseHeader(<js>"Cache-Control"</js>, <js>"nocache"</js>); 1052 * .staticFileResponseHeaders(<js>"My-Header: foo"</js>); 1053 * 1054 * <jc>// Same, but using property.</jc> 1055 * builder 1056 * .addTo(<jsf>REST_staticFileResponseHeaders</jsf>, <js>"Cache-Control"</js>, <js>"nocache"</js>); 1057 * .addTo(<jsf>REST_staticFileResponseHeaders</jsf>, <js>"My-Header"</js>, <js>"foo"</js>); 1058 * } 1059 * 1060 * <jc>// Option #3 - Defined via builder passed in through init method.</jc> 1061 * <ja>@RestHook</ja>(<jsf>INIT</jsf>) 1062 * <jk>public void</jk> init(RestContextBuilder builder) <jk>throws</jk> Exception { 1063 * builder.staticFileResponseHeader(<js>"Cache-Control"</js>, <js>"nocache"</js>); 1064 * } 1065 * } 1066 * </p> 1067 * 1068 * <p> 1069 * Note that headers can also be specified per path-mapping via the {@link RestResource#staticFiles() @RestResource(staticFiles)} annotation. 1070 * <p class='bcode w800'> 1071 * <ja>@RestResource</ja>( 1072 * staticFiles={ 1073 * <js>"htdocs:docs:{'Cache-Control':'max-age=86400, public'}"</js> 1074 * } 1075 * ) 1076 * </p> 1077 * 1078 * <ul class='notes'> 1079 * <li> 1080 * Supports {@doc DefaultRestSvlVariables} 1081 * (e.g. <js>"$L{my.localized.variable}"</js>). 1082 * </ul> 1083 * 1084 * <ul class='seealso'> 1085 * <li class='jf'>{@link RestContext#REST_staticFileResponseHeaders} 1086 * </ul> 1087 */ 1088 String[] staticFileResponseHeaders() default {}; 1089 1090 /** 1091 * Static file mappings. 1092 * 1093 * <p> 1094 * Used to define paths and locations of statically-served files such as images or HTML documents 1095 * from the classpath or file system. 1096 * 1097 * <p> 1098 * The format of the value is one of the following: 1099 * <ol class='spaced-list'> 1100 * <li><js>"path:location"</js> 1101 * <li><js>"path:location:headers"</js> 1102 * </ol> 1103 * 1104 * <p> 1105 * An example where this class is used is in the {@link RestResource#staticFiles} annotation: 1106 * <p class='bcode w800'> 1107 * <jk>package</jk> com.foo.mypackage; 1108 * 1109 * <ja>@RestResource</ja>( 1110 * path=<js>"/myresource"</js>, 1111 * staticFiles={ 1112 * <js>"htdocs:docs"</js>, 1113 * <js>"styles:styles"</js> 1114 * } 1115 * ) 1116 * <jk>public class</jk> MyResource <jk>extends</jk> BasicRestServlet {...} 1117 * </p> 1118 * 1119 * <p> 1120 * In the example above, given a GET request to the following URL... 1121 * <p class='bcode w800'> 1122 * /myresource/htdocs/foobar.html 1123 * </p> 1124 * <br>...the servlet will attempt to find the <c>foobar.html</c> file in the following location: 1125 * <ol class='spaced-list'> 1126 * <li><c>com.foo.mypackage.docs</c> package. 1127 * </ol> 1128 * 1129 * <p> 1130 * The location is interpreted as an absolute path if it starts with <js>'/'</js>. 1131 * <p class='bcode w800'> 1132 * <ja>@RestResource</ja>( 1133 * staticFiles={ 1134 * <js>"htdocs:/docs"</js> 1135 * } 1136 * ) 1137 * </p> 1138 * <p> 1139 * In the example above, given a GET request to the following URL... 1140 * <p class='bcode w800'> 1141 * /myresource/htdocs/foobar.html 1142 * </p> 1143 * <br>...the servlet will attempt to find the <c>foobar.html</c> file in the following location: 1144 * <ol class='spaced-list'> 1145 * <li><c>docs</c> package (typically under <c>src/main/resources/docs</c> in your workspace). 1146 * <li><c>[working-dir]/docs</c> directory at runtime. 1147 * </ol> 1148 * 1149 * <p> 1150 * Response headers can be specified for served files by adding a 3rd section that consists of a {@doc SimpleJson} object. 1151 * <p class='bcode w800'> 1152 * <ja>@RestResource</ja>( 1153 * staticFiles={ 1154 * <js>"htdocs:docs:{'Cache-Control':'max-age=86400, public'}"</js> 1155 * } 1156 * ) 1157 * </p> 1158 * 1159 * <p> 1160 * The same path can map to multiple locations. Files are searched in the order 1161 * <p class='bcode w800'> 1162 * <ja>@RestResource</ja>( 1163 * staticFiles={ 1164 * <jc>// Search in absolute location '/htdocs/folder' before location 'htdocs.package' relative to servlet package.</jc> 1165 * <js>"htdocs:/htdocs/folder,htdocs:htdocs.package"</js> 1166 * } 1167 * ) 1168 * </p> 1169 * 1170 * <ul class='notes'> 1171 * <li> 1172 * Mappings are cumulative from super classes. 1173 * <li> 1174 * Child resources can override mappings made on parent class resources. 1175 * <br>When both parent and child resources map against the same path, files will be search in the child location 1176 * and then the parent location. 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_staticFiles} 1184 * </ul> 1185 */ 1186 String[] staticFiles() default {}; 1187 1188 /** 1189 * Supported accept media types. 1190 * 1191 * <p> 1192 * Overrides the media types inferred from the serializers that identify what media types can be produced by the resource. 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_produces} 1202 * </ul> 1203 */ 1204 String[] produces() default {}; 1205 1206 /** 1207 * Supported content media types. 1208 * 1209 * <p> 1210 * Overrides the media types inferred from the parsers that identify what media types can be consumed by the resource. 1211 * 1212 * <ul class='notes'> 1213 * <li> 1214 * Supports {@doc DefaultRestSvlVariables} 1215 * (e.g. <js>"$L{my.localized.variable}"</js>). 1216 * </ul> 1217 * 1218 * <ul class='seealso'> 1219 * <li class='jf'>{@link RestContext#REST_consumes} 1220 * </ul> 1221 */ 1222 String[] consumes() default {}; 1223 1224 /** 1225 * Provides swagger-specific metadata on this resource. 1226 * 1227 * <p> 1228 * Used to populate the auto-generated OPTIONS swagger documentation. 1229 * 1230 * <h5 class='section'>Example:</h5> 1231 * <p class='bcode w800'> 1232 * <ja>@RestResource</ja>( 1233 * path=<js>"/addressBook"</js>, 1234 * 1235 * <jc>// Swagger info.</jc> 1236 * swagger=@ResourceSwagger({ 1237 * <js>"contact:{name:'John Smith',email:'john@smith.com'},"</js>, 1238 * <js>"license:{name:'Apache 2.0',url:'http://www.apache.org/licenses/LICENSE-2.0.html'},"</js>, 1239 * <js>"version:'2.0',</js>, 1240 * <js>"termsOfService:'You are on your own.',"</js>, 1241 * <js>"tags:[{name:'Java',description:'Java utility',externalDocs:{description:'Home page',url:'http://juneau.apache.org'}}],"</js>, 1242 * <js>"externalDocs:{description:'Home page',url:'http://juneau.apache.org'}"</js> 1243 * }) 1244 * ) 1245 * </p> 1246 * 1247 * <ul class='seealso'> 1248 * <li class='ja'>{@link ResourceSwagger} 1249 * <li class='jm'>{@link RestInfoProvider#getSwagger(RestRequest)} 1250 * </ul> 1251 */ 1252 ResourceSwagger swagger() default @ResourceSwagger; 1253 1254 /** 1255 * Optional servlet title. 1256 * 1257 * <p> 1258 * It is used to populate the Swagger title field. 1259 * <br>This value can be retrieved programmatically through the {@link RestRequest#getResourceTitle()} method. 1260 * 1261 * <ul class='notes'> 1262 * <li> 1263 * Supports {@doc DefaultRestSvlVariables} 1264 * (e.g. <js>"$L{my.localized.variable}"</js>). 1265 * <li> 1266 * Corresponds to the swagger field <c>/info/title</c>. 1267 * </ul> 1268 * 1269 * <ul class='seealso'> 1270 * <li class='jm'>{@link RestInfoProvider#getTitle(RestRequest)} 1271 * </ul> 1272 */ 1273 String[] title() default {}; 1274 1275 /** 1276 * Resource authority path. 1277 * 1278 * <p> 1279 * Overrides the authority path value for this resource and any child resources. 1280 * 1281 * <ul class='notes'> 1282 * <li> 1283 * Supports {@doc DefaultRestSvlVariables} 1284 * (e.g. <js>"$L{my.localized.variable}"</js>). 1285 * </ul> 1286 * 1287 * <ul class='seealso'> 1288 * <li class='jf'>{@link RestContext#REST_uriAuthority} 1289 * </ul> 1290 */ 1291 String uriAuthority() default ""; 1292 1293 /** 1294 * Resource context path. 1295 * 1296 * <p> 1297 * Overrides the context path value for this resource and any child resources. 1298 * 1299 * <ul class='notes'> 1300 * <li> 1301 * Supports {@doc DefaultRestSvlVariables} 1302 * (e.g. <js>"$L{my.localized.variable}"</js>). 1303 * </ul> 1304 * 1305 * <ul class='seealso'> 1306 * <li class='jf'>{@link RestContext#REST_uriContext} 1307 * </ul> 1308 */ 1309 String uriContext() default ""; 1310 1311 /** 1312 * URI-resolution relativity. 1313 * 1314 * <p> 1315 * Specifies how relative URIs should be interpreted by serializers. 1316 * 1317 * <p> 1318 * See {@link UriResolution} for possible values. 1319 * 1320 * <ul class='notes'> 1321 * <li> 1322 * Supports {@doc DefaultRestSvlVariables} 1323 * (e.g. <js>"$L{my.localized.variable}"</js>). 1324 * </ul> 1325 * 1326 * <ul class='seealso'> 1327 * <li class='jf'>{@link RestContext#REST_uriRelativity} 1328 * </ul> 1329 */ 1330 String uriRelativity() default ""; 1331 1332 /** 1333 * URI-resolution. 1334 * 1335 * <p> 1336 * Specifies how relative URIs should be interpreted by serializers. 1337 * 1338 * <p> 1339 * See {@link UriResolution} for possible values. 1340 * 1341 * <ul class='notes'> 1342 * <li> 1343 * Supports {@doc DefaultRestSvlVariables} 1344 * (e.g. <js>"$L{my.localized.variable}"</js>). 1345 * </ul> 1346 * 1347 * <ul class='seealso'> 1348 * <li class='jf'>{@link RestContext#REST_uriResolution} 1349 * </ul> 1350 */ 1351 String uriResolution() default ""; 1352 1353 /** 1354 * Configuration property: Use classpath resource caching. 1355 * 1356 * <p> 1357 * When enabled, resources retrieved via {@link RestRequest#getClasspathReaderResource(String, boolean)} (and related 1358 * methods) will be cached in memory to speed subsequent lookups. 1359 * 1360 * <ul class='notes'> 1361 * <li> 1362 * Supports {@doc DefaultRestSvlVariables} 1363 * (e.g. <js>"$L{my.localized.variable}"</js>). 1364 * </ul> 1365 * 1366 * <ul class='seealso'> 1367 * <li class='jf'>{@link RestContext#REST_useClasspathResourceCaching} 1368 * </ul> 1369 */ 1370 String useClasspathResourceCaching() default ""; 1371 1372 /** 1373 * Use stack trace hashes. 1374 * 1375 * <p> 1376 * When enabled, the number of times an exception has occurred will be determined based on stack trace hashsums, 1377 * made available through the {@link RestException#getOccurrence()} method. 1378 * 1379 * <ul class='notes'> 1380 * <li> 1381 * Supports {@doc DefaultRestSvlVariables} 1382 * (e.g. <js>"$L{my.localized.variable}"</js>). 1383 * </ul> 1384 * 1385 * <ul class='seealso'> 1386 * <li class='jf'>{@link RestContext#REST_useStackTraceHashes} 1387 * </ul> 1388 * 1389 * @deprecated Use {@link Logging#useStackTraceHashing()} 1390 */ 1391 @Deprecated 1392 String useStackTraceHashes() default ""; 1393 1394 /** 1395 * Enable debug mode. 1396 * 1397 * <p> 1398 * Enables the following: 1399 * <ul class='spaced-list'> 1400 * <li> 1401 * HTTP request/response bodies are cached in memory for logging purposes. 1402 * </ul> 1403 * 1404 * <p> 1405 * Possible values (case insensitive): 1406 * <ul> 1407 * <li><js>"true"</js> - Debug is enabled for all requests. 1408 * <li><js>"false"</js> - Debug is disabled for all requests. 1409 * <li><js>"per-request"</js> - Debug is enabled only for requests that have a <c class='snippet'>X-Debug: true</c> header. 1410 * </ul> 1411 * 1412 * <ul class='notes'> 1413 * <li> 1414 * Supports {@doc DefaultRestSvlVariables} 1415 * (e.g. <js>"$L{my.localized.variable}"</js>). 1416 * </ul> 1417 * 1418 * <ul class='seealso'> 1419 * <li class='jf'>{@link RestContext#REST_debug} 1420 * </ul> 1421 */ 1422 String debug() default ""; 1423}