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