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