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 javax.servlet.http.*; 021 022import org.apache.juneau.*; 023import org.apache.juneau.config.*; 024import org.apache.juneau.encoders.*; 025import org.apache.juneau.httppart.*; 026import org.apache.juneau.parser.*; 027import org.apache.juneau.rest.*; 028import org.apache.juneau.serializer.*; 029import org.apache.juneau.utils.*; 030 031/** 032 * Used to denote that a class is a REST resource and to associate metadata on it. 033 * 034 * <p> 035 * Usually used on a subclass of {@link RestServlet}, but can be used to annotate any class that you want to expose as 036 * a REST resource. 037 * 038 * <h5 class='section'>See Also:</h5> 039 * <ul> 040 * <li class='link'>{@doc juneau-rest-server.RestResource} 041 * </ul> 042 */ 043@Documented 044@Target(TYPE) 045@Retention(RUNTIME) 046@Inherited 047public @interface RestResource { 048 049 /** 050 * Allow body URL parameter. 051 * 052 * <p> 053 * When enabled, the HTTP body content on PUT and POST requests can be passed in as text using the <js>"body"</js> 054 * URL parameter. 055 * <br> 056 * For example: 057 * <p class='bcode w800'> 058 * ?body=(name='John%20Smith',age=45) 059 * </p> 060 * 061 * <h5 class='section'>Notes:</h5> 062 * <ul class='spaced-list'> 063 * <li> 064 * Supports {@doc DefaultRestSvlVariables} 065 * (e.g. <js>"$L{my.localized.variable}"</js>). 066 * </ul> 067 * 068 * <h5 class='section'>See Also:</h5> 069 * <ul> 070 * <li class='jf'>{@link RestContext#REST_allowBodyParam} 071 * </ul> 072 */ 073 String allowBodyParam() default ""; 074 075 /** 076 * Allowed method parameters. 077 * 078 * <p> 079 * When specified, the HTTP method can be overridden by passing in a <js>"method"</js> URL parameter on a regular 080 * GET request. 081 * <br> 082 * For example: 083 * <p class='bcode w800'> 084 * ?method=OPTIONS 085 * </p> 086 * 087 * <h5 class='section'>Notes:</h5> 088 * <ul class='spaced-list'> 089 * <li> 090 * Supports {@doc DefaultRestSvlVariables} 091 * (e.g. <js>"$L{my.localized.variable}"</js>). 092 * </ul> 093 * 094 * <h5 class='section'>See Also:</h5> 095 * <ul> 096 * <li class='jf'>{@link RestContext#REST_allowedMethodParams} 097 * </ul> 098 */ 099 String allowedMethodParams() default ""; 100 101 /** 102 * Allow header URL parameters. 103 * 104 * <p> 105 * When enabled, headers such as <js>"Accept"</js> and <js>"Content-Type"</js> to be passed in as URL query 106 * parameters. 107 * <br> 108 * For example: 109 * <p class='bcode w800'> 110 * ?Accept=text/json&Content-Type=text/json 111 * </p> 112 * 113 * <h5 class='section'>Notes:</h5> 114 * <ul class='spaced-list'> 115 * <li> 116 * Supports {@doc DefaultRestSvlVariables} 117 * (e.g. <js>"$L{my.localized.variable}"</js>). 118 * </ul> 119 * 120 * <h5 class='section'>See Also:</h5> 121 * <ul> 122 * <li class='jf'>{@link RestContext#REST_allowHeaderParams} 123 * </ul> 124 */ 125 String allowHeaderParams() default ""; 126 127 /** 128 * Class-level bean filters. 129 * 130 * <p> 131 * Shortcut to add bean filters to the bean contexts of the objects returned by the following methods: 132 * <ul> 133 * <li>{@link RestContext#getBeanContext()} 134 * <li>{@link RestContext#getSerializers()} 135 * <li>{@link RestContext#getParsers()} 136 * </ul> 137 * 138 * <h5 class='section'>See Also:</h5> 139 * <ul> 140 * <li class='jf'>{@link BeanContext#BEAN_beanFilters} 141 * </ul> 142 */ 143 Class<?>[] beanFilters() default {}; 144 145 /** 146 * REST call handler. 147 * 148 * <p> 149 * This class handles the basic lifecycle of an HTTP REST call. 150 * 151 * <h5 class='section'>See Also:</h5> 152 * <ul> 153 * <li class='jf'>{@link RestContext#REST_callHandler} 154 * </ul> 155 */ 156 Class<? extends RestCallHandler> callHandler() default RestCallHandler.Null.class; 157 158 /** 159 * REST children. 160 * 161 * <p> 162 * Defines children of this resource. 163 * 164 * <h5 class='section'>See Also:</h5> 165 * <ul> 166 * <li class='jf'>{@link RestContext#REST_children} 167 * </ul> 168 */ 169 Class<?>[] children() default {}; 170 171 /** 172 * Classpath resource finder. 173 * 174 * <p> 175 * Used to retrieve localized files from the classpath. 176 * 177 * <h5 class='section'>See Also:</h5> 178 * <ul> 179 * <li class='jf'>{@link RestContext#REST_classpathResourceFinder} 180 * </ul> 181 */ 182 Class<? extends ClasspathResourceFinder> classpathResourceFinder() default ClasspathResourceFinder.Null.class; 183 184 /** 185 * Client version header. 186 * 187 * <p> 188 * Specifies the name of the header used to denote the client version on HTTP requests. 189 * 190 * <h5 class='section'>Notes:</h5> 191 * <ul class='spaced-list'> 192 * <li> 193 * Supports {@doc DefaultRestSvlVariables} 194 * (e.g. <js>"$L{my.localized.variable}"</js>). 195 * </ul> 196 * 197 * <h5 class='section'>See Also:</h5> 198 * <ul> 199 * <li class='jf'>{@link RestContext#REST_clientVersionHeader} 200 * </ul> 201 */ 202 String clientVersionHeader() default ""; 203 204 /** 205 * Optional location of configuration file for this servlet. 206 * 207 * <p> 208 * The configuration file . 209 * 210 * <h5 class='section'>Notes:</h5> 211 * <ul class='spaced-list'> 212 * <li> 213 * Supports {@doc DefaultRestSvlVariables} 214 * (e.g. <js>"$L{my.localized.variable}"</js>). 215 * <li> 216 * Use the keyword <code>SYSTEM_DEFAULT</code> to refer to the system default configuration 217 * returned by the {@link Config#getSystemDefault()}. 218 * </ul> 219 * 220 * <h5 class='section'>See Also:</h5> 221 * <ul> 222 * <li class='jm'>{@link RestContextBuilder#config(Config)} 223 * </ul> 224 */ 225 String config() default ""; 226 227 /** 228 * Class-level response converters. 229 * 230 * <p> 231 * Associates one or more {@link RestConverter converters} with a resource class. 232 * 233 * <h5 class='section'>See Also:</h5> 234 * <ul> 235 * <li class='jf'>{@link RestContext#REST_converters} 236 * </ul> 237 */ 238 Class<? extends RestConverter>[] converters() default {}; 239 240 /** 241 * Default <code>Accept</code> header. 242 * 243 * <p> 244 * The default value for the <code>Accept</code> header if not specified on a request. 245 * 246 * <p> 247 * This is a shortcut for using {@link #defaultRequestHeaders()} for just this specific header. 248 * 249 * <h5 class='section'>Notes:</h5> 250 * <ul class='spaced-list'> 251 * <li> 252 * Supports {@doc DefaultRestSvlVariables} 253 * (e.g. <js>"$L{my.localized.variable}"</js>). 254 * </ul> 255 */ 256 String defaultAccept() default ""; 257 258 /** 259 * Default character encoding. 260 * 261 * <p> 262 * The default character encoding for the request and response if not specified on the request. 263 * 264 * <h5 class='section'>Notes:</h5> 265 * <ul class='spaced-list'> 266 * <li> 267 * Supports {@doc DefaultRestSvlVariables} 268 * (e.g. <js>"$L{my.localized.variable}"</js>). 269 * </ul> 270 * 271 * <h5 class='section'>See Also:</h5> 272 * <ul> 273 * <li class='jf'>{@link RestContext#REST_defaultCharset} 274 * </ul> 275 */ 276 String defaultCharset() default ""; 277 278 /** 279 * Default <code>Content-Type</code> header. 280 * 281 * <p> 282 * The default value for the <code>Content-Type</code> header if not specified on a request. 283 * 284 * <p> 285 * This is a shortcut for using {@link #defaultRequestHeaders()} for just this specific header. 286 * 287 * <h5 class='section'>Notes:</h5> 288 * <ul class='spaced-list'> 289 * <li> 290 * Supports {@doc DefaultRestSvlVariables} 291 * (e.g. <js>"$L{my.localized.variable}"</js>). 292 * </ul> 293 */ 294 String defaultContentType() default ""; 295 296 /** 297 * Default request headers. 298 * 299 * <p> 300 * Specifies default values for request headers if they're not passed in through the request. 301 * 302 * <h5 class='section'>Notes:</h5> 303 * <ul class='spaced-list'> 304 * <li> 305 * Supports {@doc DefaultRestSvlVariables} 306 * (e.g. <js>"$L{my.localized.variable}"</js>). 307 * </ul> 308 * 309 * <h5 class='section'>See Also:</h5> 310 * <ul> 311 * <li class='jf'>{@link RestContext#REST_defaultRequestHeaders} 312 * </ul> 313 */ 314 String[] defaultRequestHeaders() default {}; 315 316 /** 317 * Default response headers. 318 * 319 * <p> 320 * Specifies default values for response headers if they're not set after the Java REST method is called. 321 * 322 * <h5 class='section'>Notes:</h5> 323 * <ul class='spaced-list'> 324 * <li> 325 * Supports {@doc DefaultRestSvlVariables} 326 * (e.g. <js>"$L{my.localized.variable}"</js>). 327 * </ul> 328 * 329 * <h5 class='section'>See Also:</h5> 330 * <ul> 331 * <li class='jf'>{@link RestContext#REST_defaultResponseHeaders} 332 * </ul> 333 */ 334 String[] defaultResponseHeaders() default {}; 335 336 /** 337 * Optional servlet description. 338 * 339 * <p> 340 * It is used to populate the Swagger description field. 341 * <br>This value can be retrieved programmatically through the {@link RestRequest#getResourceDescription()} method. 342 * 343 * <h5 class='section'>Notes:</h5> 344 * <ul class='spaced-list'> 345 * <li> 346 * Supports {@doc DefaultRestSvlVariables} 347 * (e.g. <js>"$L{my.localized.variable}"</js>). 348 * <li> 349 * The format is plain-text. 350 * <br>Multiple lines are concatenated with newlines. 351 * </ul> 352 * 353 * <h5 class='section'>See Also:</h5> 354 * <ul> 355 * <li class='jm'>{@link RestInfoProvider#getDescription(RestRequest)} 356 * </ul> 357 */ 358 String[] description() default {}; 359 360 /** 361 * Compression encoders. 362 * 363 * <p> 364 * These can be used to enable various kinds of compression (e.g. <js>"gzip"</js>) on requests and responses. 365 * 366 * <h5 class='section'>See Also:</h5> 367 * <ul> 368 * <li class='jf'>{@link RestContext#REST_encoders} 369 * </ul> 370 */ 371 Class<? extends Encoder>[] encoders() default {}; 372 373 /** 374 * Shortcut for setting {@link #properties()} of simple boolean types. 375 * 376 * <h5 class='section'>Notes:</h5> 377 * <ul class='spaced-list'> 378 * <li> 379 * Supports {@doc DefaultRestSvlVariables} 380 * (e.g. <js>"$L{my.localized.variable}"</js>). 381 * <li> 382 * Setting a flag is equivalent to setting the same property to <js>"true"</js>. 383 * </ul> 384 */ 385 String[] flags() default {}; 386 387 /** 388 * Class-level guards. 389 * 390 * <p> 391 * Associates one or more {@link RestGuard RestGuards} with all REST methods defined in this class. 392 * 393 * <h5 class='section'>See Also:</h5> 394 * <ul> 395 * <li class='jf'>{@link RestContext#REST_guards} 396 * </ul> 397 */ 398 Class<? extends RestGuard>[] guards() default {}; 399 400 /** 401 * Provides HTML-doc-specific metadata on this method. 402 * 403 * <p> 404 * Used to customize the output from the HTML Doc serializer. 405 * <p class='bcode w800'> 406 * <ja>@RestResource</ja>( 407 * path=<js>"/addressBook"</js>, 408 * 409 * <jc>// Links on the HTML rendition page. 410 * // "request:/..." URIs are relative to the request URI. 411 * // "servlet:/..." URIs are relative to the servlet URI. 412 * // "$C{...}" variables are pulled from the config file.</jc> 413 * htmldoc=<ja>@HtmlDoc</ja>( 414 * <jc>// Widgets for $W variables.</jc> 415 * widgets={ 416 * PoweredByJuneau.<jk>class</jk>, 417 * ContentTypeLinks.<jk>class</jk> 418 * } 419 * navlinks={ 420 * <js>"up: request:/.."</js>, 421 * <js>"options: servlet:/?method=OPTIONS"</js>, 422 * <js>"source: $C{Source/gitHub}/org/apache/juneau/examples/rest/addressbook/AddressBookResource.java"</js>, 423 * }, 424 * aside={ 425 * <js>"<div style='max-width:400px;min-width:200px'>"</js>, 426 * <js>" <p>Proof-of-concept resource that shows off the capabilities of working with POJO resources.</p>"</js>, 427 * <js>" <p>Provides examples of: </p>"</js>, 428 * <js>" <ul>"</js>, 429 * <js>" <li>XML and RDF namespaces"</js>, 430 * <js>" <li>Swagger documentation"</js>, 431 * <js>" <li>Widgets"</js>, 432 * <js>" </ul>"</js>, 433 * <js>" <p style='text-weight:bold;text-decoration:underline;'>Available Content Types</p>"</js>, 434 * <js>" $W{ContentTypeLinks}"</js>, 435 * <js>"</div>"</js> 436 * }, 437 * footer=<js>"$W{PoweredByJuneau}"</js> 438 * ) 439 * ) 440 * </p> 441 * 442 * <h5 class='section'>See Also:</h5> 443 * <ul> 444 * <li class='link'>{@doc juneau-rest-server.HtmlDocAnnotation} 445 * </ul> 446 */ 447 HtmlDoc htmldoc() default @HtmlDoc; 448 449 /** 450 * Configuration property: REST info provider. 451 * 452 * <p> 453 * Class used to retrieve title/description/swagger information about a resource. 454 * 455 * <h5 class='section'>See Also:</h5> 456 * <ul> 457 * <li class='jf'>{@link RestContext#REST_infoProvider} 458 * </ul> 459 */ 460 Class<? extends RestInfoProvider> infoProvider() default RestInfoProvider.Null.class; 461 462 /** 463 * REST logger. 464 * 465 * <p> 466 * Specifies the logger to use for logging. 467 * 468 * <h5 class='section'>See Also:</h5> 469 * <ul> 470 * <li class='jf'>{@link RestContext#REST_logger} 471 * </ul> 472 */ 473 Class<? extends RestLogger> logger() default RestLogger.Null.class; 474 475 /** 476 * The maximum allowed input size (in bytes) on HTTP requests. 477 * 478 * <p> 479 * Useful for alleviating DoS attacks by throwing an exception when too much input is received instead of resulting 480 * in out-of-memory errors which could affect system stability. 481 * 482 * <h5 class='section'>Notes:</h5> 483 * <ul class='spaced-list'> 484 * <li> 485 * Supports {@doc DefaultRestSvlVariables} 486 * (e.g. <js>"$L{my.localized.variable}"</js>). 487 * </ul> 488 * 489 * <h5 class='section'>See Also:</h5> 490 * <ul> 491 * <li class='jf'>{@link RestContext#REST_maxInput} 492 * </ul> 493 */ 494 String maxInput() default ""; 495 496 /** 497 * Messages. 498 * 499 * Identifies the location of the resource bundle for this class. 500 * 501 * <h5 class='section'>Notes:</h5> 502 * <ul class='spaced-list'> 503 * <li> 504 * Supports {@doc DefaultRestSvlVariables} 505 * (e.g. <js>"$L{my.localized.variable}"</js>). 506 * </ul> 507 * 508 * <h5 class='section'>See Also:</h5> 509 * <ul> 510 * <li class='jf'>{@link RestContext#REST_messages} 511 * </ul> 512 */ 513 String messages() default ""; 514 515 /** 516 * Configuration property: MIME types. 517 * 518 * <p> 519 * Defines MIME-type file type mappings. 520 * 521 * <h5 class='section'>Notes:</h5> 522 * <ul class='spaced-list'> 523 * <li> 524 * Supports {@doc DefaultRestSvlVariables} 525 * (e.g. <js>"$L{my.localized.variable}"</js>). 526 * </ul> 527 * 528 * <h5 class='section'>See Also:</h5> 529 * <ul> 530 * <li class='jf'>{@link RestContext#REST_mimeTypes} 531 * </ul> 532 */ 533 String[] mimeTypes() default {}; 534 535 /** 536 * Java method parameter resolvers. 537 * 538 * <p> 539 * By default, the Juneau framework will automatically Java method parameters of various types (e.g. 540 * <code>RestRequest</code>, <code>Accept</code>, <code>Reader</code>). 541 * <br>This setting allows you to provide your own resolvers for your own class types that you want resolved. 542 * 543 * <h5 class='section'>See Also:</h5> 544 * <ul> 545 * <li class='jf'>{@link RestContext#REST_paramResolvers} 546 * </ul> 547 */ 548 Class<? extends RestMethodParam>[] paramResolvers() default {}; 549 550 /** 551 * Parser listener. 552 * 553 * <p> 554 * Specifies the parser listener class to use for listening to non-fatal parsing errors. 555 * 556 * <h5 class='section'>See Also:</h5> 557 * <ul> 558 * <li class='jf'>{@link Parser#PARSER_listener} 559 * </ul> 560 */ 561 Class<? extends ParserListener> parserListener() default ParserListener.Null.class; 562 563 /** 564 * Parsers. 565 * 566 * <p> 567 * If no value is specified, the parsers are inherited from parent class. 568 * <br>Otherwise, this value overrides the parsers defined on the parent class. 569 * 570 * <p> 571 * Use {@link Inherit} to inherit parsers defined on the parent class. 572 * 573 * <p> 574 * Use {@link None} to suppress inheriting parsers defined on the parent class. 575 * 576 * <h5 class='section'>See Also:</h5> 577 * <ul> 578 * <li class='jf'>{@link RestContext#REST_parsers} 579 * </ul> 580 */ 581 Class<?>[] parsers() default {}; 582 583 /** 584 * HTTP part parser. 585 * 586 * <p> 587 * Specifies the {@link HttpPartParser} to use for parsing headers, query/form parameters, and URI parts. 588 * 589 * <h5 class='section'>See Also:</h5> 590 * <ul> 591 * <li class='jf'>{@link RestContext#REST_partParser} 592 * </ul> 593 */ 594 Class<? extends HttpPartParser> partParser() default HttpPartParser.Null.class; 595 596 /** 597 * HTTP part serializer. 598 * 599 * <p> 600 * Specifies the {@link HttpPartSerializer} to use for serializing headers, query/form parameters, and URI parts. 601 * 602 * <h5 class='section'>See Also:</h5> 603 * <ul> 604 * <li class='jf'>{@link RestContext#REST_partSerializer} 605 * </ul> 606 */ 607 Class<? extends HttpPartSerializer> partSerializer() default HttpPartSerializer.Null.class; 608 609 /** 610 * Resource path. 611 * 612 * <p> 613 * Identifies the URL subpath relative to the parent resource. 614 * 615 * <h5 class='section'>See Also:</h5> 616 * <ul> 617 * <li class='jf'>{@link RestContext#REST_path} 618 * </ul> 619 */ 620 String path() default ""; 621 622 /** 623 * Class-level POJO swaps. 624 * 625 * <p> 626 * Shortcut to add POJO swaps to the bean contexts of the objects returned by the following methods: 627 * <ul> 628 * <li>{@link RestContext#getBeanContext()} 629 * <li>{@link RestContext#getSerializers()} 630 * <li>{@link RestContext#getParsers()} 631 * </ul> 632 * 633 * <h5 class='section'>See Also:</h5> 634 * <ul> 635 * <li class='jf'>{@link BeanContext#BEAN_pojoSwaps} 636 * </ul> 637 */ 638 Class<?>[] pojoSwaps() default {}; 639 640 /** 641 * Class-level properties. 642 * 643 * <p> 644 * Shortcut for specifying class-level properties on this servlet to the objects returned by the following methods: 645 * <ul> 646 * <li>{@link RestContext#getBeanContext()} 647 * <li>{@link RestContext#getSerializers()} 648 * <li>{@link RestContext#getParsers()} 649 * </ul> 650 * 651 * <p> 652 * Any of the properties defined on {@link RestContext} or any of the serializers and parsers can be specified. 653 * 654 * <p> 655 * Property values will be converted to the appropriate type. 656 * 657 * <p> 658 * In some cases, properties can be overridden at runtime through the 659 * {@link RestResponse#prop(String, Object)} method or through an {@link RequestProperties} 660 * method parameter. 661 * 662 * <h5 class='section'>Notes:</h5> 663 * <ul class='spaced-list'> 664 * <li> 665 * Supports {@doc DefaultRestSvlVariables} 666 * (e.g. <js>"$L{my.localized.variable}"</js>). 667 * </ul> 668 * 669 * <h5 class='section'>See Also:</h5> 670 * <ul> 671 * <li class='jm'>{@link RestContextBuilder#set(String,Object)} 672 * <li class='jm'>{@link RestContextBuilder#set(java.util.Map)} 673 * </ul> 674 */ 675 Property[] properties() default {}; 676 677 /** 678 * Render response stack traces in responses. 679 * 680 * <p> 681 * Render stack traces in HTTP response bodies when errors occur. 682 * 683 * <h5 class='section'>Notes:</h5> 684 * <ul class='spaced-list'> 685 * <li> 686 * Supports {@doc DefaultRestSvlVariables} 687 * (e.g. <js>"$L{my.localized.variable}"</js>). 688 * </ul> 689 * 690 * <h5 class='section'>See Also:</h5> 691 * <ul> 692 * <li class='jf'>{@link RestContext#REST_renderResponseStackTraces} 693 * </ul> 694 */ 695 String renderResponseStackTraces() default ""; 696 697 /** 698 * REST resource resolver. 699 * 700 * <p> 701 * The resolver used for resolving child resources. 702 * 703 * <h5 class='section'>See Also:</h5> 704 * <ul> 705 * <li class='jf'>{@link RestContext#REST_resourceResolver} 706 * </ul> 707 */ 708 Class<? extends RestResourceResolver> resourceResolver() default RestResourceResolver.Null.class; 709 710 /** 711 * Response handlers. 712 * 713 * <p> 714 * Specifies a list of {@link ResponseHandler} classes that know how to convert POJOs returned by REST methods or 715 * set via {@link RestResponse#setOutput(Object)} into appropriate HTTP responses. 716 * 717 * <h5 class='section'>See Also:</h5> 718 * <ul> 719 * <li class='jf'>{@link RestContext#REST_responseHandlers} 720 * </ul> 721 */ 722 Class<? extends ResponseHandler>[] responseHandlers() default {}; 723 724 /** 725 * Serializer listener. 726 * 727 * <p> 728 * Specifies the serializer listener class to use for listening to non-fatal serialization errors. 729 * 730 * <h5 class='section'>See Also:</h5> 731 * <ul> 732 * <li class='jf'>{@link Serializer#SERIALIZER_listener} 733 * </ul> 734 */ 735 Class<? extends SerializerListener> serializerListener() default SerializerListener.Null.class; 736 737 /** 738 * Serializers. 739 * 740 * <p> 741 * If no value is specified, the serializers are inherited from parent class. 742 * <br>Otherwise, this value overrides the serializers defined on the parent class. 743 * 744 * <p> 745 * Use {@link Inherit} to inherit serializers defined on the parent class. 746 * 747 * <p> 748 * Use {@link None} to suppress inheriting serializers defined on the parent class. 749 * 750 * <h5 class='section'>See Also:</h5> 751 * <ul> 752 * <li class='jf'>{@link RestContext#REST_serializers} 753 * </ul> 754 */ 755 Class<?>[] serializers() default {}; 756 757 /** 758 * Optional site name. 759 * 760 * <p> 761 * The site name is intended to be a title that can be applied to the entire site. 762 * 763 * <p> 764 * This value can be retrieved programmatically through the {@link RestRequest#getSiteName()} method. 765 * 766 * <p> 767 * One possible use is if you want to add the same title to the top of all pages by defining a header on a 768 * common parent class like so: 769 * <p class='bcode w800'> 770 * htmldoc=<ja>@HtmlDoc</ja>( 771 * header={ 772 * <js>"<h1>$R{siteName}</h1>"</js>, 773 * <js>"<h2>$R{resourceTitle}</h2>"</js> 774 * } 775 * ) 776 * </p> 777 * 778 * <h5 class='section'>Notes:</h5> 779 * <ul class='spaced-list'> 780 * <li> 781 * Supports {@doc DefaultRestSvlVariables} 782 * (e.g. <js>"$L{my.localized.variable}"</js>). 783 * </ul> 784 * 785 * <h5 class='section'>See Also:</h5> 786 * <ul> 787 * <li class='jm'>{@link RestInfoProvider#getSiteName(RestRequest)} 788 * </ul> 789 */ 790 String siteName() default ""; 791 792 /** 793 * Static file response headers. 794 * 795 * <p> 796 * Used to customize the headers on responses returned for statically-served files. 797 * 798 * <h5 class='section'>Notes:</h5> 799 * <ul class='spaced-list'> 800 * <li> 801 * Supports {@doc DefaultRestSvlVariables} 802 * (e.g. <js>"$L{my.localized.variable}"</js>). 803 * </ul> 804 * 805 * <h5 class='section'>See Also:</h5> 806 * <ul> 807 * <li class='jf'>{@link RestContext#REST_staticFileResponseHeaders} 808 * </ul> 809 */ 810 String[] staticFileResponseHeaders() default {}; 811 812 /** 813 * Static file mappings. 814 * 815 * <p> 816 * Used to define paths and locations of statically-served files such as images or HTML documents. 817 * 818 * <h5 class='section'>Notes:</h5> 819 * <ul class='spaced-list'> 820 * <li> 821 * Supports {@doc DefaultRestSvlVariables} 822 * (e.g. <js>"$L{my.localized.variable}"</js>). 823 * </ul> 824 * 825 * <h5 class='section'>See Also:</h5> 826 * <ul> 827 * <li class='jf'>{@link RestContext#REST_staticFiles} 828 * </ul> 829 */ 830 String[] staticFiles() default {}; 831 832 /** 833 * Supported accept media types. 834 * 835 * <p> 836 * Overrides the media types inferred from the serializers that identify what media types can be produced by the resource. 837 * 838 * <h5 class='section'>Notes:</h5> 839 * <ul class='spaced-list'> 840 * <li> 841 * Supports {@doc DefaultRestSvlVariables} 842 * (e.g. <js>"$L{my.localized.variable}"</js>). 843 * </ul> 844 * 845 * <h5 class='section'>See Also:</h5> 846 * <ul> 847 * <li class='jf'>{@link RestContext#REST_produces} 848 * </ul> 849 */ 850 String[] produces() default {}; 851 852 /** 853 * Supported content media types. 854 * 855 * <p> 856 * Overrides the media types inferred from the parsers that identify what media types can be consumed by the resource. 857 * 858 * <h5 class='section'>Notes:</h5> 859 * <ul class='spaced-list'> 860 * <li> 861 * Supports {@doc DefaultRestSvlVariables} 862 * (e.g. <js>"$L{my.localized.variable}"</js>). 863 * </ul> 864 * 865 * <h5 class='section'>See Also:</h5> 866 * <ul> 867 * <li class='jf'>{@link RestContext#REST_consumes} 868 * </ul> 869 */ 870 String[] consumes() default {}; 871 872 /** 873 * Provides swagger-specific metadata on this resource. 874 * 875 * <p> 876 * Used to populate the auto-generated OPTIONS swagger documentation. 877 * 878 * <h5 class='section'>Example:</h5> 879 * <p class='bcode w800'> 880 * <ja>@RestResource</ja>( 881 * path=<js>"/addressBook"</js>, 882 * 883 * <jc>// Swagger info.</jc> 884 * swagger=@ResourceSwagger({ 885 * <js>"contact:{name:'John Smith',email:'john@smith.com'},"</js>, 886 * <js>"license:{name:'Apache 2.0',url:'http://www.apache.org/licenses/LICENSE-2.0.html'},"</js>, 887 * <js>"version:'2.0',</js>, 888 * <js>"termsOfService:'You are on your own.',"</js>, 889 * <js>"tags:[{name:'Java',description:'Java utility',externalDocs:{description:'Home page',url:'http://juneau.apache.org'}}],"</js>, 890 * <js>"externalDocs:{description:'Home page',url:'http://juneau.apache.org'}"</js> 891 * }) 892 * ) 893 * </p> 894 * 895 * <h5 class='section'>See Also:</h5> 896 * <ul> 897 * <li class='ja'>{@link ResourceSwagger} 898 * <li class='jm'>{@link RestInfoProvider#getSwagger(RestRequest)} 899 * </ul> 900 */ 901 ResourceSwagger swagger() default @ResourceSwagger; 902 903 /** 904 * Optional servlet title. 905 * 906 * <p> 907 * It is used to populate the Swagger title field. 908 * <br>This value can be retrieved programmatically through the {@link RestRequest#getResourceTitle()} method. 909 * 910 * <h5 class='section'>Notes:</h5> 911 * <ul class='spaced-list'> 912 * <li> 913 * Supports {@doc DefaultRestSvlVariables} 914 * (e.g. <js>"$L{my.localized.variable}"</js>). 915 * <li> 916 * Corresponds to the swagger field <code>/info/title</code>. 917 * </ul> 918 * 919 * <h5 class='section'>See Also:</h5> 920 * <ul> 921 * <li class='jm'>{@link RestInfoProvider#getTitle(RestRequest)} 922 * </ul> 923 */ 924 String[] title() default {}; 925 926 /** 927 * Resource authority path. 928 * 929 * <p> 930 * Overrides the authority path value for this resource and any child resources. 931 * 932 * <h5 class='section'>Notes:</h5> 933 * <ul class='spaced-list'> 934 * <li> 935 * Supports {@doc DefaultRestSvlVariables} 936 * (e.g. <js>"$L{my.localized.variable}"</js>). 937 * </ul> 938 * 939 * <h5 class='section'>See Also:</h5> 940 * <ul> 941 * <li class='jf'>{@link RestContext#REST_uriAuthority} 942 * </ul> 943 */ 944 String uriAuthority() default ""; 945 946 /** 947 * Resource context path. 948 * 949 * <p> 950 * Overrides the context path value for this resource and any child resources. 951 * 952 * <h5 class='section'>Notes:</h5> 953 * <ul class='spaced-list'> 954 * <li> 955 * Supports {@doc DefaultRestSvlVariables} 956 * (e.g. <js>"$L{my.localized.variable}"</js>). 957 * </ul> 958 * 959 * <h5 class='section'>See Also:</h5> 960 * <ul> 961 * <li class='jf'>{@link RestContext#REST_uriContext} 962 * </ul> 963 */ 964 String uriContext() default ""; 965 966 /** 967 * URI-resolution relativity. 968 * 969 * <p> 970 * Specifies how relative URIs should be interpreted by serializers. 971 * 972 * <p> 973 * See {@link UriResolution} for possible values. 974 * 975 * <h5 class='section'>Notes:</h5> 976 * <ul class='spaced-list'> 977 * <li> 978 * Supports {@doc DefaultRestSvlVariables} 979 * (e.g. <js>"$L{my.localized.variable}"</js>). 980 * </ul> 981 * 982 * <h5 class='section'>See Also:</h5> 983 * <ul> 984 * <li class='jf'>{@link RestContext#REST_uriRelativity} 985 * </ul> 986 */ 987 String uriRelativity() default ""; 988 989 /** 990 * URI-resolution. 991 * 992 * <p> 993 * Specifies how relative URIs should be interpreted by serializers. 994 * 995 * <p> 996 * See {@link UriResolution} for possible values. 997 * 998 * <h5 class='section'>Notes:</h5> 999 * <ul class='spaced-list'> 1000 * <li> 1001 * Supports {@doc DefaultRestSvlVariables} 1002 * (e.g. <js>"$L{my.localized.variable}"</js>). 1003 * </ul> 1004 * 1005 * <h5 class='section'>See Also:</h5> 1006 * <ul> 1007 * <li class='jf'>{@link RestContext#REST_uriResolution} 1008 * </ul> 1009 */ 1010 String uriResolution() default ""; 1011 1012 /** 1013 * Configuration property: Use classpath resource caching. 1014 * 1015 * <p> 1016 * When enabled, resources retrieved via {@link RestRequest#getClasspathReaderResource(String, boolean)} (and related 1017 * methods) will be cached in memory to speed subsequent lookups. 1018 * 1019 * <h5 class='section'>Notes:</h5> 1020 * <ul class='spaced-list'> 1021 * <li> 1022 * Supports {@doc DefaultRestSvlVariables} 1023 * (e.g. <js>"$L{my.localized.variable}"</js>). 1024 * </ul> 1025 * 1026 * <h5 class='section'>See Also:</h5> 1027 * <ul> 1028 * <li class='jf'>{@link RestContext#REST_useClasspathResourceCaching} 1029 * </ul> 1030 */ 1031 String useClasspathResourceCaching() default ""; 1032 1033 /** 1034 * Use stack trace hashes. 1035 * 1036 * <p> 1037 * When enabled, the number of times an exception has occurred will be determined based on stack trace hashsums, 1038 * made available through the {@link RestException#getOccurrence()} method. 1039 * 1040 * <h5 class='section'>Notes:</h5> 1041 * <ul class='spaced-list'> 1042 * <li> 1043 * Supports {@doc DefaultRestSvlVariables} 1044 * (e.g. <js>"$L{my.localized.variable}"</js>). 1045 * </ul> 1046 * 1047 * <h5 class='section'>See Also:</h5> 1048 * <ul> 1049 * <li class='jf'>{@link RestContext#REST_useStackTraceHashes} 1050 * </ul> 1051 */ 1052 String useStackTraceHashes() default ""; 1053 1054 /** 1055 * Enable debug mode. 1056 * 1057 * <p> 1058 * Enables the following: 1059 * <ul> 1060 * <li>A message and stack trace is printed to STDERR when {@link BasicRestCallHandler#handleError(HttpServletRequest, HttpServletResponse, Throwable)} is called. 1061 * </ul> 1062 * 1063 * <h5 class='section'>Notes:</h5> 1064 * <ul class='spaced-list'> 1065 * <li> 1066 * Supports {@doc DefaultRestSvlVariables} 1067 * (e.g. <js>"$L{my.localized.variable}"</js>). 1068 * </ul> 1069 * 1070 * <h5 class='section'>See Also:</h5> 1071 * <ul> 1072 * <li class='jf'>{@link RestContext#REST_debug} 1073 * </ul> 1074 */ 1075 String debug() default ""; 1076}