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