001/* 002 * Licensed to the Apache Software Foundation (ASF) under one or more 003 * contributor license agreements. See the NOTICE file distributed with 004 * this work for additional information regarding copyright ownership. 005 * The ASF licenses this file to You under the Apache License, Version 2.0 006 * (the "License"); you may not use this file except in compliance with 007 * the License. You may obtain a copy of the License at 008 * 009 * http://www.apache.org/licenses/LICENSE-2.0 010 * 011 * Unless required by applicable law or agreed to in writing, software 012 * distributed under the License is distributed on an "AS IS" BASIS, 013 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 014 * See the License for the specific language governing permissions and 015 * limitations under the License. 016 */ 017package org.apache.juneau.rest.annotation; 018 019import static java.lang.annotation.ElementType.*; 020import static java.lang.annotation.RetentionPolicy.*; 021 022import java.lang.annotation.*; 023import java.nio.charset.*; 024import java.util.*; 025 026import org.apache.juneau.*; 027import org.apache.juneau.annotation.*; 028import org.apache.juneau.commons.annotation.*; 029import org.apache.juneau.config.*; 030import org.apache.juneau.cp.*; 031import org.apache.juneau.encoders.*; 032import org.apache.juneau.http.annotation.*; 033import org.apache.juneau.httppart.*; 034import org.apache.juneau.parser.*; 035import org.apache.juneau.rest.*; 036import org.apache.juneau.rest.arg.*; 037import org.apache.juneau.rest.converter.*; 038import org.apache.juneau.rest.debug.*; 039import org.apache.juneau.rest.guard.*; 040import org.apache.juneau.rest.httppart.*; 041import org.apache.juneau.rest.logger.*; 042import org.apache.juneau.rest.processor.*; 043import org.apache.juneau.rest.servlet.*; 044import org.apache.juneau.rest.staticfile.*; 045import org.apache.juneau.rest.swagger.*; 046import org.apache.juneau.serializer.*; 047 048/** 049 * Used to denote that a class is a REST resource and to associate metadata on it. 050 * 051 * <p> 052 * Usually used on a subclass of {@link RestServlet}, but can be used to annotate any class that you want to expose as 053 * a REST resource. 054 * 055 * <h5 class='section'>See Also:</h5><ul> 056 * <li class='link'><a class="doclink" href="https://juneau.apache.org/docs/topics/RestAnnotatedClassBasics">@Rest-Annotated Class Basics</a> 057 058 * </ul> 059 */ 060@Target(TYPE) 061@Retention(RUNTIME) 062@Inherited 063@ContextApply({ RestAnnotation.RestContextApply.class, RestAnnotation.RestOpContextApply.class }) 064@AnnotationGroup(Rest.class) 065public @interface Rest { 066 067 /** 068 * Allowed header URL parameters. 069 * 070 * <p> 071 * When specified, allows headers such as <js>"Accept"</js> and <js>"Content-Type"</js> to be passed in as URL query 072 * parameters. 073 * <br> 074 * For example: 075 * <p class='burlenc'> 076 * ?Accept=text/json&Content-Type=text/json 077 * </p> 078 * 079 * <h5 class='section'>Notes:</h5><ul> 080 * <li class='note'> 081 * Supports <a class="doclink" href="https://juneau.apache.org/docs/topics/RestServerSvlVariables">SVL Variables</a> 082 * (e.g. <js>"$L{my.localized.variable}"</js>). 083 * <li class='note'> 084 * Use <js>"*"</js> to represent all methods. 085 * <li class='note'> 086 * Use <js>"NONE"</js> (case insensitive) to suppress inheriting a value from a parent class. 087 * </ul> 088 * 089 * <h5 class='section'>See Also:</h5><ul> 090 * <li class='jm'>{@link org.apache.juneau.rest.RestContext.Builder#allowedHeaderParams(String)} 091 * </ul> 092 * 093 * @return The annotation value. 094 */ 095 String allowedHeaderParams() default ""; 096 097 /** 098 * Allowed method headers. 099 * 100 * <p> 101 * A comma-delimited list of HTTP method names that are allowed to be passed as values in an <c>X-Method</c> HTTP header 102 * to override the real HTTP method name. 103 * <p> 104 * Allows you to override the actual HTTP method with a simulated method. 105 * <br>For example, if an HTTP Client API doesn't support <c>PATCH</c> but does support <c>POST</c> (because 106 * <c>PATCH</c> is not part of the original HTTP spec), you can add a <c>X-Method: PATCH</c> header on a normal 107 * <c>HTTP POST /foo</c> request call which will make the HTTP call look like a <c>PATCH</c> request in any of the REST APIs. 108 * 109 * <h5 class='section'>Notes:</h5><ul> 110 * <li class='note'> 111 * Supports <a class="doclink" href="https://juneau.apache.org/docs/topics/RestServerSvlVariables">SVL Variables</a> 112 * (e.g. <js>"$L{my.localized.variable}"</js>). 113 * <li class='note'> 114 * Method names are case-insensitive. 115 * <li class='note'> 116 * Use <js>"*"</js> to represent all methods. 117 * <li class='note'> 118 * Use <js>"NONE"</js> (case insensitive) to suppress inheriting a value from a parent class. 119 * </ul> 120 * 121 * @return The annotation value. 122 */ 123 String allowedMethodHeaders() default ""; 124 125 /** 126 * Allowed method parameters. 127 * 128 * <p> 129 * When specified, the HTTP method can be overridden by passing in a <js>"method"</js> URL parameter on a regular 130 * GET request. 131 * <br> 132 * For example: 133 * <p class='burlenc'> 134 * ?method=OPTIONS 135 * </p> 136 * 137 * <h5 class='section'>Notes:</h5><ul> 138 * <li class='note'> 139 * Supports <a class="doclink" href="https://juneau.apache.org/docs/topics/RestServerSvlVariables">SVL Variables</a> 140 * (e.g. <js>"$L{my.localized.variable}"</js>). 141 * <li class='note'> 142 * Use <js>"*"</js> to represent all methods. 143 * <li class='note'> 144 * Use <js>"NONE"</js> (case insensitive) to suppress inheriting a value from a parent class. 145 * </ul> 146 * 147 * <h5 class='section'>See Also:</h5><ul> 148 * <li class='jm'>{@link org.apache.juneau.rest.RestContext.Builder#allowedMethodParams(String)} 149 * </ul> 150 * 151 * @return The annotation value. 152 */ 153 String allowedMethodParams() default ""; 154 155 /** 156 * The resolver used for resolving instances of child resources and various other beans including: 157 * <ul> 158 * <li>{@link CallLogger} 159 * <li>{@link SwaggerProvider} 160 * <li>{@link FileFinder} 161 * <li>{@link StaticFiles} 162 * </ul> 163 * 164 * <p> 165 * Note that the <c>SpringRestServlet</c> classes uses the <c>SpringBeanStore</c> class to allow for any 166 * Spring beans to be injected into your REST resources. 167 * 168 * @return The annotation value. 169 */ 170 Class<? extends BeanStore> beanStore() default BeanStore.Void.class; 171 172 /** 173 * Specifies the logger to use for logging of HTTP requests and responses. 174 * 175 * <h5 class='section'>Notes:</h5><ul> 176 * <li class='note'> 177 * The default call logger if not specified is {@link CallLogger}. 178 * <li class='note'> 179 * The resource class itself will be used if it implements the {@link CallLogger} interface and not 180 * explicitly overridden via this annotation. 181 * <li class='note'> 182 * The implementation must have one of the following constructors: 183 * <ul> 184 * <li><code><jk>public</jk> T(RestContext)</code> 185 * <li><code><jk>public</jk> T()</code> 186 * <li><code><jk>public static</jk> T <jsm>create</jsm>(RestContext)</code> 187 * <li><code><jk>public static</jk> T <jsm>create</jsm>()</code> 188 * </ul> 189 * <li class='note'> 190 * Inner classes of the REST resource class are allowed. 191 * </ul> 192 * 193 * <h5 class='section'>See Also:</h5><ul> 194 * <li class='jm'>{@link org.apache.juneau.rest.RestContext.Builder#callLogger()} 195 * <li class='link'><a class="doclink" href="https://juneau.apache.org/docs/topics/RestServerLoggingAndDebugging">Logging / Debugging</a> 196 * </ul> 197 * 198 * @return The annotation value. 199 */ 200 Class<? extends CallLogger> callLogger() default CallLogger.Void.class; 201 202 /** 203 * REST children. 204 * 205 * <p> 206 * Defines children of this resource. 207 * 208 * <h5 class='section'>Inheritance Rules</h5> 209 * <ul> 210 * <li>Children on child are combined with those on parent class. 211 * <li>Children are list parent-to-child in the order they appear in the annotation. 212 * </ul> 213 * 214 * <h5 class='section'>See Also:</h5><ul> 215 * <li class='jm'>{@link org.apache.juneau.rest.RestContext.Builder#children(Object...)} 216 * </ul> 217 * 218 * @return The annotation value. 219 */ 220 Class<?>[] children() default {}; 221 222 /** 223 * Client version header. 224 * 225 * <p> 226 * Specifies the name of the header used to denote the client version on HTTP requests. 227 * 228 * <h5 class='section'>Notes:</h5><ul> 229 * <li class='note'> 230 * Supports <a class="doclink" href="https://juneau.apache.org/docs/topics/RestServerSvlVariables">SVL Variables</a> 231 * (e.g. <js>"$L{my.localized.variable}"</js>). 232 * </ul> 233 * 234 * <h5 class='section'>See Also:</h5><ul> 235 * <li class='jm'>{@link org.apache.juneau.rest.RestContext.Builder#clientVersionHeader(String)} 236 * </ul> 237 * 238 * @return The annotation value. 239 */ 240 String clientVersionHeader() default ""; 241 242 /** 243 * Optional location of configuration file for this servlet. 244 * 245 * <p> 246 * The configuration file . 247 * 248 * <h5 class='section'>Inheritance Rules</h5> 249 * <ul> 250 * <li>Config file is searched for in child-to-parent order. 251 * </ul> 252 * 253 * <h5 class='section'>Notes:</h5><ul> 254 * <li class='note'> 255 * Supports <a class="doclink" href="https://juneau.apache.org/docs/topics/RestServerSvlVariables">SVL Variables</a> 256 * (e.g. <js>"$L{my.localized.variable}"</js>). 257 * <li class='note'> 258 * Use the keyword <c>SYSTEM_DEFAULT</c> to refer to the system default configuration 259 * returned by the {@link Config#getSystemDefault()}. 260 * </ul> 261 * 262 * <h5 class='section'>See Also:</h5><ul> 263 * <li class='jm'>{@link org.apache.juneau.rest.RestContext.Builder#config(Config)} 264 * </ul> 265 * 266 * @return The annotation value. 267 */ 268 String config() default ""; 269 270 /** 271 * Supported content media types. 272 * 273 * <p> 274 * Overrides the media types inferred from the parsers that identify what media types can be consumed by the resource. 275 * 276 * <h5 class='section'>Notes:</h5><ul> 277 * <li class='note'> 278 * Supports <a class="doclink" href="https://juneau.apache.org/docs/topics/RestServerSvlVariables">SVL Variables</a> 279 * (e.g. <js>"$L{my.localized.variable}"</js>). 280 * </ul> 281 * 282 * <h5 class='section'>See Also:</h5><ul> 283 * <li class='jm'>{@link org.apache.juneau.rest.RestContext.Builder#consumes(MediaType...)} 284 * </ul> 285 * 286 * @return The annotation value. 287 */ 288 String[] consumes() default {}; 289 290 /** 291 * Class-level response converters. 292 * 293 * <p> 294 * Associates one or more {@link RestConverter converters} with a resource class. 295 * 296 * <h5 class='section'>Inheritance Rules</h5> 297 * <ul> 298 * <li>Converters on child are combined with those on parent class. 299 * <li>Converters are executed child-to-parent in the order they appear in the annotation. 300 * <li>Converters on methods are executed before those on classes. 301 * </ul> 302 * 303 * <h5 class='section'>See Also:</h5><ul> 304 * <li class='jm'>{@link org.apache.juneau.rest.RestOpContext.Builder#converters()} - Registering converters with REST resources. 305 * </ul> 306 * 307 * @return The annotation value. 308 */ 309 Class<? extends RestConverter>[] converters() default {}; 310 311 /** 312 * Enable debug mode. 313 * 314 * <p> 315 * Enables the following: 316 * <ul class='spaced-list'> 317 * <li> 318 * HTTP request/response bodies are cached in memory for logging purposes. 319 * <li> 320 * HTTP requests/responses are logged to the registered {@link CallLogger}. 321 * </ul> 322 * 323 * <ul class='values'> 324 * <li><js>"true"</js> - Debug is enabled for all requests. 325 * <li><js>"false"</js> - Debug is disabled for all requests. 326 * <li><js>"conditional"</js> - Debug is enabled only for requests that have a <c class='snippet'>Debug: true</c> header. 327 * </ul> 328 * 329 * <h5 class='section'>Notes:</h5><ul> 330 * <li class='note'> 331 * Supports <a class="doclink" href="https://juneau.apache.org/docs/topics/RestServerSvlVariables">SVL Variables</a> 332 * (e.g. <js>"$L{my.localized.variable}"</js>). 333 * <li class='note'> 334 * These debug settings can be overridden by the {@link Rest#debugOn()} annotation or at runtime by directly 335 * calling {@link RestRequest#setDebug()}. 336 * </ul> 337 * 338 * <h5 class='section'>See Also:</h5><ul> 339 * <li class='jm'>{@link org.apache.juneau.rest.RestContext.Builder#debugEnablement()} 340 * </ul> 341 * 342 * @return The annotation value. 343 */ 344 String debug() default ""; 345 346 /** 347 * Debug enablement bean. 348 * 349 * <p> 350 * Specifies a custom {@link org.apache.juneau.rest.debug.DebugEnablement} implementation class to use for determining whether debug mode is enabled. 351 * This allows for more sophisticated control over when debug features are enabled beyond simple boolean flags. 352 * 353 * <h5 class='section'>See Also:</h5><ul> 354 * <li class='jm'>{@link org.apache.juneau.rest.RestContext.Builder#debugEnablement()} 355 * </ul> 356 * 357 * @return The annotation value. 358 */ 359 Class<? extends DebugEnablement> debugEnablement() default DebugEnablement.Void.class; 360 361 /** 362 * Enable debug mode on specified classes/methods. 363 * 364 * <p> 365 * Enables the following: 366 * <ul class='spaced-list'> 367 * <li> 368 * HTTP request/response bodies are cached in memory for logging purposes on matching classes and methods. 369 * <li> 370 * HTTP requests/responses are logged to the registered {@link CallLogger}. 371 * </ul> 372 * 373 * <p> 374 * Consists of a comma-delimited list of strings of the following forms: 375 * <ul> 376 * <li><js>"class-identifier"</js> - Enable debug on the specified class. 377 * <li><js>"class-identifier=[true|false|conditional]"</js> - Explicitly enable debug on the specified class. 378 * <li><js>"method-identifier"</js> - Enable debug on the specified class. 379 * <li><js>"method-identifier=[true|false|conditional]"</js> - Explicitly enable debug on the specified class. 380 * </ul> 381 * 382 * <p> 383 * Class identifiers can be any of the following forms: 384 * <ul> 385 * <li>Fully qualified: 386 * <ul> 387 * <li><js>"com.foo.MyClass"</js> 388 * </ul> 389 * <li>Fully qualified inner class: 390 * <ul> 391 * <li><js>"com.foo.MyClass$Inner1$Inner2"</js> 392 * </ul> 393 * <li>Simple: 394 * <ul> 395 * <li><js>"MyClass"</js> 396 * </ul> 397 * <li>Simple inner: 398 * <ul> 399 * <li><js>"MyClass$Inner1$Inner2"</js> 400 * <li><js>"Inner1$Inner2"</js> 401 * <li><js>"Inner2"</js> 402 * </ul> 403 * </ul> 404 * 405 * <p> 406 * Method identifiers can be any of the following forms: 407 * <ul> 408 * <li>Fully qualified with args: 409 * <ul> 410 * <li><js>"com.foo.MyClass.myMethod(String,int)"</js> 411 * <li><js>"com.foo.MyClass.myMethod(java.lang.String,int)"</js> 412 * <li><js>"com.foo.MyClass.myMethod()"</js> 413 * </ul> 414 * <li>Fully qualified: 415 * <ul> 416 * <li><js>"com.foo.MyClass.myMethod"</js> 417 * </ul> 418 * <li>Simple with args: 419 * <ul> 420 * <li><js>"MyClass.myMethod(String,int)"</js> 421 * <li><js>"MyClass.myMethod(java.lang.String,int)"</js> 422 * <li><js>"MyClass.myMethod()"</js> 423 * </ul> 424 * <li>Simple: 425 * <ul> 426 * <li><js>"MyClass.myMethod"</js> 427 * </ul> 428 * <li>Simple inner class: 429 * <ul> 430 * <li><js>"MyClass$Inner1$Inner2.myMethod"</js> 431 * <li><js>"Inner1$Inner2.myMethod"</js> 432 * <li><js>"Inner2.myMethod"</js> 433 * </ul> 434 * </ul> 435 * 436 * <h5 class='figure'>Example:</h5> 437 * <p class='bjava'> 438 * <jc>// Turn on debug per-request on the class and always on the doX() method</jc>. 439 * <ja>@Rest</ja>( 440 * debugOn=<js>"MyResource=conditional,MyResource.doX=true"</js> 441 * ) 442 * <jk>public class</jk> MyResource { 443 * 444 * <ja>@RestGet</ja> 445 * <jk>public void</jk> String getX() { 446 * ... 447 * } 448 * </p> 449 * 450 * <p> 451 * A more-typical scenario is to pull this setting from an external source such as system property or environment 452 * variable: 453 * 454 * <h5 class='figure'>Example:</h5> 455 * <p class='bjava'> 456 * <ja>@Rest</ja>( 457 * debugOn=<js>"$E{DEBUG_ON_SETTINGS}"</js> 458 * ) 459 * <jk>public class</jk> MyResource {...} 460 * </p> 461 * 462 * <h5 class='section'>Notes:</h5><ul> 463 * <li class='note'> 464 * Supports <a class="doclink" href="https://juneau.apache.org/docs/topics/RestServerSvlVariables">SVL Variables</a> 465 * (e.g. <js>"$L{my.localized.variable}"</js>). 466 * <li class='note'> 467 * These debug settings override the settings define via {@link Rest#debug()} and {@link RestOp#debug()}. 468 * <li class='note'> 469 * These debug settings can be overridden at runtime by directly calling {@link RestRequest#setDebug()}. 470 * </ul> 471 * 472 * @return The annotation value. 473 */ 474 String debugOn() default ""; 475 476 /** 477 * Default <c>Accept</c> header. 478 * 479 * <p> 480 * The default value for the <c>Accept</c> header if not specified on a request. 481 * 482 * <p> 483 * This is a shortcut for using {@link #defaultRequestHeaders()} for just this specific header. 484 * 485 * <h5 class='section'>Notes:</h5><ul> 486 * <li class='note'> 487 * Supports <a class="doclink" href="https://juneau.apache.org/docs/topics/RestServerSvlVariables">SVL Variables</a> 488 * (e.g. <js>"$L{my.localized.variable}"</js>). 489 * </ul> 490 * 491 * @return The annotation value. 492 */ 493 String defaultAccept() default ""; 494 495 /** 496 * Default character encoding. 497 * 498 * <p> 499 * The default character encoding for the request and response if not specified on the request. 500 * 501 * <h5 class='section'>Notes:</h5><ul> 502 * <li class='note'> 503 * Supports <a class="doclink" href="https://juneau.apache.org/docs/topics/RestServerSvlVariables">SVL Variables</a> 504 * (e.g. <js>"$L{my.localized.variable}"</js>). 505 * </ul> 506 * 507 * <h5 class='section'>See Also:</h5><ul> 508 * <li class='jm'>{@link org.apache.juneau.rest.RestContext.Builder#defaultCharset(Charset)} 509 * <li class='jm'>{@link org.apache.juneau.rest.RestOpContext.Builder#defaultCharset(Charset)} 510 * <li class='ja'>{@link RestOp#defaultCharset} 511 * <li class='ja'>{@link RestGet#defaultCharset} 512 * <li class='ja'>{@link RestPut#defaultCharset} 513 * <li class='ja'>{@link RestPost#defaultCharset} 514 * <li class='ja'>{@link RestDelete#defaultCharset} 515 * </ul> 516 * 517 * @return The annotation value. 518 */ 519 String defaultCharset() default ""; 520 521 /** 522 * Default <c>Content-Type</c> header. 523 * 524 * <p> 525 * The default value for the <c>Content-Type</c> header if not specified on a request. 526 * 527 * <p> 528 * This is a shortcut for using {@link #defaultRequestHeaders()} for just this specific header. 529 * 530 * <h5 class='section'>Notes:</h5><ul> 531 * <li class='note'> 532 * Supports <a class="doclink" href="https://juneau.apache.org/docs/topics/RestServerSvlVariables">SVL Variables</a> 533 * (e.g. <js>"$L{my.localized.variable}"</js>). 534 * </ul> 535 * 536 * @return The annotation value. 537 */ 538 String defaultContentType() default ""; 539 540 /** 541 * Default request attributes. 542 * 543 * <p> 544 * Specifies default values for request attributes if they're not already set on the request. 545 * 546 * <p> 547 * Affects values returned by the following methods: 548 * <ul> 549 * <li class='jm'>{@link RestRequest#getAttribute(String)}. 550 * <li class='jm'>{@link RestRequest#getAttributes()}. 551 * </ul> 552 * 553 * <h5 class='section'>Example:</h5> 554 * <p class='bjava'> 555 * <jc>// Defined via annotation resolving to a config file setting with default value.</jc> 556 * <ja>@Rest</ja>(defaultRequestAttributes={<js>"Foo=bar"</js>, <js>"Baz: $C{REST/myAttributeValue}"</js>}) 557 * <jk>public class</jk> MyResource { 558 * 559 * <jc>// Override at the method level.</jc> 560 * <ja>@RestGet</ja>(defaultRequestAttributes={<js>"Foo: bar"</js>}) 561 * <jk>public</jk> Object myMethod() {...} 562 * } 563 * </p> 564 * 565 * <h5 class='section'>Notes:</h5><ul> 566 * <li class='note'> 567 * Supports <a class="doclink" href="https://juneau.apache.org/docs/topics/RestServerSvlVariables">SVL Variables</a> 568 * (e.g. <js>"$L{my.localized.variable}"</js>). 569 * </ul> 570 * 571 * <h5 class='section'>See Also:</h5><ul> 572 * <li class='jm'>{@link org.apache.juneau.rest.RestContext.Builder#defaultRequestAttributes(NamedAttribute...)} 573 * <li class='ja'>{@link RestOp#defaultRequestAttributes()} 574 * <li class='ja'>{@link RestGet#defaultRequestAttributes()} 575 * <li class='ja'>{@link RestPut#defaultRequestAttributes()} 576 * <li class='ja'>{@link RestPost#defaultRequestAttributes()} 577 * <li class='ja'>{@link RestDelete#defaultRequestAttributes()} 578 * </ul> 579 * 580 * @return The annotation value. 581 */ 582 String[] defaultRequestAttributes() default {}; 583 584 /** 585 * Default request headers. 586 * 587 * <p> 588 * Specifies default values for request headers if they're not passed in through the request. 589 * 590 * <h5 class='section'>Notes:</h5><ul> 591 * <li class='note'> 592 * Supports <a class="doclink" href="https://juneau.apache.org/docs/topics/RestServerSvlVariables">SVL Variables</a> 593 * (e.g. <js>"$L{my.localized.variable}"</js>). 594 * </ul> 595 * 596 * <h5 class='section'>See Also:</h5><ul> 597 * <li class='jm'>{@link org.apache.juneau.rest.RestContext.Builder#defaultRequestHeaders(org.apache.http.Header...)} 598 * </ul> 599 * 600 * @return The annotation value. 601 */ 602 String[] defaultRequestHeaders() default {}; 603 604 /** 605 * Default response headers. 606 * 607 * <p> 608 * Specifies default values for response headers if they're not set after the Java REST method is called. 609 * 610 * <h5 class='section'>Notes:</h5><ul> 611 * <li class='note'> 612 * Supports <a class="doclink" href="https://juneau.apache.org/docs/topics/RestServerSvlVariables">SVL Variables</a> 613 * (e.g. <js>"$L{my.localized.variable}"</js>). 614 * </ul> 615 * 616 * <h5 class='section'>See Also:</h5><ul> 617 * <li class='jm'>{@link org.apache.juneau.rest.RestContext.Builder#defaultResponseHeaders(org.apache.http.Header...)} 618 * </ul> 619 * 620 * @return The annotation value. 621 */ 622 String[] defaultResponseHeaders() default {}; 623 624 /** 625 * Optional servlet description. 626 * 627 * <p> 628 * It is used to populate the Swagger description field. 629 * 630 * <h5 class='section'>Inheritance Rules</h5> 631 * <ul> 632 * <li>Description is searched for in child-to-parent order. 633 * </ul> 634 * 635 * <h5 class='section'>Notes:</h5><ul> 636 * <li class='note'> 637 * Supports <a class="doclink" href="https://juneau.apache.org/docs/topics/RestServerSvlVariables">SVL Variables</a> 638 * (e.g. <js>"$L{my.localized.variable}"</js>). 639 * <li class='note'> 640 * The format is plain-text. 641 * <br>Multiple lines are concatenated with newlines. 642 * </ul> 643 * 644 * @return The annotation value. 645 */ 646 String[] description() default {}; 647 648 /** 649 * Disable content URL parameter. 650 * 651 * <p> 652 * When enabled, the HTTP content content on PUT and POST requests can be passed in as text using the <js>"content"</js> 653 * URL parameter. 654 * <br> 655 * For example: 656 * <p class='burlenc'> 657 * ?content=(name='John%20Smith',age=45) 658 * </p> 659 * 660 * <h5 class='section'>Notes:</h5><ul> 661 * <li class='note'> 662 * Supports <a class="doclink" href="https://juneau.apache.org/docs/topics/RestServerSvlVariables">SVL Variables</a> 663 * (e.g. <js>"$L{my.localized.variable}"</js>). 664 * </ul> 665 * 666 * <h5 class='section'>See Also:</h5><ul> 667 * <li class='jm'>{@link org.apache.juneau.rest.RestContext.Builder#disableContentParam()} 668 * </ul> 669 * 670 * @return The annotation value. 671 */ 672 String disableContentParam() default ""; 673 674 /** 675 * Specifies the compression encoders for this resource. 676 * 677 * <p> 678 * Encoders are used to enable various kinds of compression (e.g. <js>"gzip"</js>) on requests and responses. 679 * 680 * <p> 681 * Encoders are automatically inherited from {@link Rest#encoders()} annotations on parent classes with the encoders on child classes 682 * prepended to the encoder group. 683 * The {@link org.apache.juneau.encoders.EncoderSet.NoInherit} class can be used to prevent inheriting from the parent class. 684 * 685 * <h5 class='section'>Example:</h5> 686 * <p class='bjava'> 687 * <jc>// Define a REST resource that handles GZIP compression.</jc> 688 * <ja>@Rest</ja>( 689 * encoders={ 690 * GzipEncoder.<jk>class</jk> 691 * } 692 * ) 693 * <jk>public class</jk> MyResource { 694 * ... 695 * } 696 * </p> 697 * 698 * <p> 699 * The encoders can also be tailored at the method level using {@link RestOp#encoders()} (and related annotations). 700 * 701 * <p> 702 * The programmatic equivalent to this annotation is: 703 * <p class='bjava'> 704 * RestContext.Builder <jv>builder</jv> = RestContext.<jsm>create</jsm>(<jv>resource</jv>); 705 * <jv>builder</jv>.getEncoders().add(<jv>classes</jv>); 706 * </p> 707 * 708 * <h5 class='section'>Inheritance Rules</h5> 709 * <ul> 710 * <li>Encoders on child are combined with those on parent class. 711 * </ul> 712 * 713 * <h5 class='section'>See Also:</h5><ul> 714 * <li class='link'><a class="doclink" href="https://juneau.apache.org/docs/topics/RestServerEncoders">Encoders</a> 715 * </ul> 716 * 717 * @return The annotation value. 718 */ 719 Class<? extends Encoder>[] encoders() default {}; 720 721 /** 722 * Default form data parameter definitions. 723 * 724 * <p> 725 * Provides default values for {@link FormData @FormData} annotations on method parameters across all methods in this class. 726 * 727 * <h5 class='section'>Example:</h5> 728 * <p class='bjava'> 729 * <ja>@Rest</ja>( 730 * formDataParams={ 731 * <ja>@FormData</ja>(name=<js>"action"</js>, def=<js>"submit"</js>) 732 * } 733 * ) 734 * <jk>public class</jk> MyResource {...} 735 * </p> 736 * 737 * @return The annotation value. 738 * @since 9.2.0 739 */ 740 FormData[] formDataParams() default {}; 741 742 /** 743 * Class-level guards. 744 * 745 * <p> 746 * Associates one or more {@link RestGuard RestGuards} with all REST methods defined in this class. 747 * 748 * <h5 class='section'>Inheritance Rules</h5> 749 * <ul> 750 * <li>Guards on child are combined with those on parent class. 751 * <li>Guards are executed child-to-parent in the order they appear in the annotation. 752 * <li>Guards on methods are executed before those on classes. 753 * </ul> 754 * 755 * <h5 class='section'>See Also:</h5><ul> 756 * <li class='jm'>{@link org.apache.juneau.rest.RestOpContext.Builder#guards()} 757 * </ul> 758 * 759 * @return The annotation value. 760 */ 761 Class<? extends RestGuard>[] guards() default {}; 762 763 /** 764 * Default header parameter definitions. 765 * 766 * <p> 767 * Provides default values for {@link Header @Header} annotations on method parameters across all methods in this class. 768 * 769 * <h5 class='section'>Example:</h5> 770 * <p class='bjava'> 771 * <ja>@Rest</ja>( 772 * headerParams={ 773 * <ja>@Header</ja>(name=<js>"Accept-Language"</js>, def=<js>"en-US"</js>), 774 * <ja>@Header</ja>(name=<js>"X-API-Version"</js>, def=<js>"1.0"</js>) 775 * } 776 * ) 777 * <jk>public class</jk> MyResource {...} 778 * </p> 779 * 780 * @return The annotation value. 781 * @since 9.2.0 782 */ 783 Header[] headerParams() default {}; 784 785 /** 786 * The maximum allowed input size (in bytes) on HTTP requests. 787 * 788 * <p> 789 * Useful for alleviating DoS attacks by throwing an exception when too much input is received instead of resulting 790 * in out-of-memory errors which could affect system stability. 791 * 792 * <h5 class='section'>Notes:</h5><ul> 793 * <li class='note'> 794 * Supports <a class="doclink" href="https://juneau.apache.org/docs/topics/RestServerSvlVariables">SVL Variables</a> 795 * (e.g. <js>"$L{my.localized.variable}"</js>). 796 * </ul> 797 * 798 * <h5 class='section'>See Also:</h5><ul> 799 * <li class='jm'>{@link org.apache.juneau.rest.RestContext.Builder#maxInput(String)} 800 * <li class='jm'>{@link org.apache.juneau.rest.RestOpContext.Builder#maxInput(String)} 801 * <li class='ja'>{@link RestOp#maxInput} 802 * <li class='ja'>{@link RestPost#maxInput} 803 * <li class='ja'>{@link RestPut#maxInput} 804 * </ul> 805 * 806 * @return The annotation value. 807 */ 808 String maxInput() default ""; 809 810 /** 811 * Messages. 812 * 813 * Identifies the location of the resource bundle for this class. 814 * 815 * <p> 816 * There are two possible formats: 817 * <ul> 818 * <li>A simple string - Represents the {@link org.apache.juneau.cp.Messages.Builder#name(String) name} of the resource bundle. 819 * <br><br><i>Example:</i> 820 * <p class='bjava'> 821 * <jc>// Bundle name is Messages.properties.</jc> 822 * <ja>@Rest</ja>(messages=<js>"Messages"</js>) 823 * </p> 824 * <li>Simplified JSON - Represents parameters for the {@link org.apache.juneau.cp.Messages.Builder} class. 825 * <br><br><i>Example:</i> 826 * <p class='bjava'> 827 * <jc>// Bundles can be found in two packages.</jc> 828 * <ja>@Rest</ja>(messages=<js>"{name:'Messages',baseNames:['{package}.{name}','{package}.i18n.{name}']"</js>) 829 * </p> 830 * </ul> 831 * 832 * <p> 833 * If the bundle name is not specified, the class name of the resource object is used. 834 * 835 * <h5 class='section'>Notes:</h5><ul> 836 * <li class='note'> 837 * Supports <a class="doclink" href="https://juneau.apache.org/docs/topics/RestServerSvlVariables">SVL Variables</a> 838 * (e.g. <js>"$L{my.localized.variable}"</js>). 839 * </ul> 840 * 841 * @return The annotation value. 842 */ 843 String messages() default ""; 844 845 /** 846 * Dynamically apply this annotation to the specified classes. 847 * 848 * <h5 class='section'>See Also:</h5><ul> 849 * <li class='link'><a class="doclink" href="https://juneau.apache.org/docs/topics/DynamicallyAppliedAnnotations">Dynamically Applied Annotations</a> 850 * </ul> 851 * 852 * @return The annotation value. 853 */ 854 String[] on() default {}; 855 856 /** 857 * Dynamically apply this annotation to the specified classes. 858 * 859 * <p> 860 * Identical to {@link #on()} except allows you to specify class objects instead of a strings. 861 * 862 * <h5 class='section'>See Also:</h5><ul> 863 * <li class='link'><a class="doclink" href="https://juneau.apache.org/docs/topics/DynamicallyAppliedAnnotations">Dynamically Applied Annotations</a> 864 * </ul> 865 * 866 * @return The annotation value. 867 */ 868 Class<?>[] onClass() default {}; 869 870 /** 871 * Specifies the parsers for converting HTTP request bodies into POJOs. 872 * 873 * <p> 874 * Parsers are used to convert the content of HTTP requests into POJOs. 875 * <br>Any of the Juneau framework parsers can be used in this setting. 876 * <br>The parser selected is based on the request <c>Content-Type</c> header matched against the values returned by the following method 877 * using a best-match algorithm: 878 * <ul class='javatree'> 879 * <li class='jm'>{@link Parser#getMediaTypes()} 880 * </ul> 881 * 882 * <p> 883 * Parsers are automatically inherited from {@link Rest#parsers()} annotations on parent classes with the parsers on child classes 884 * prepended to the parser group. 885 * The {@link org.apache.juneau.parser.ParserSet.NoInherit} class can be used to prevent inheriting from the parent class. 886 * 887 * <h5 class='section'>Example:</h5> 888 * <p class='bjava'> 889 * <jc>// Define a REST resource that can consume JSON and XML.</jc> 890 * <ja>@Rest</ja>( 891 * parsers={ 892 * JsonParser.<jk>class</jk>, 893 * XmlParser.<jk>class</jk> 894 * } 895 * ) 896 * <jk>public class</jk> MyResource { 897 * ... 898 * } 899 * </p> 900 * 901 * <p> 902 * The parsers can also be tailored at the method level using {@link RestOp#parsers()} (and related annotations). 903 * 904 * <p> 905 * The programmatic equivalent to this annotation is: 906 * <p class='bjava'> 907 * RestContext.Builder <jv>builder</jv> = RestContext.<jsm>create</jsm>(<jv>resource</jv>); 908 * <jv>builder</jv>.getParsers().add(<jv>classes</jv>); 909 * </p> 910 * 911 * <h5 class='section'>Inheritance Rules</h5> 912 * <ul> 913 * <li>Parsers on child override those on parent class. 914 * <li>{@link org.apache.juneau.parser.ParserSet.Inherit} class can be used to inherit and augment values from parent. 915 * <li>{@link org.apache.juneau.parser.ParserSet.NoInherit} class can be used to suppress inheriting from parent. 916 * <li>Parsers on methods take precedence over those on classes. 917 * </ul> 918 * 919 * <h5 class='section'>See Also:</h5><ul> 920 * <li class='link'><a class="doclink" href="https://juneau.apache.org/docs/topics/Marshalling">Marshalling</a> 921 * </ul> 922 * 923 * @return The annotation value. 924 */ 925 Class<?>[] parsers() default {}; 926 927 /** 928 * HTTP part parser. 929 * 930 * <p> 931 * Specifies the {@link HttpPartParser} to use for parsing headers, query/form parameters, and URI parts. 932 * 933 * @return The annotation value. 934 */ 935 Class<? extends HttpPartParser> partParser() default HttpPartParser.Void.class; 936 937 /** 938 * HTTP part serializer. 939 * 940 * <p> 941 * Specifies the {@link HttpPartSerializer} to use for serializing headers, query/form parameters, and URI parts. 942 * 943 * @return The annotation value. 944 */ 945 Class<? extends HttpPartSerializer> partSerializer() default HttpPartSerializer.Void.class; 946 947 /** 948 * Resource path. 949 * 950 * <p> 951 * Used in the following situations: 952 * <ul class='spaced-list'> 953 * <li> 954 * On child resources (resource classes attached to parents via the {@link #children()} annotation) to identify 955 * the subpath used to access the child resource relative to the parent. 956 * <li> 957 * On top-level {@link RestServlet} classes deployed as Spring beans when <c>JuneauRestInitializer</c> is being used. 958 * </ul> 959 * 960 * <h5 class='topic'>On child resources</h5> 961 * <p> 962 * The typical usage is to define a path to a child resource relative to the parent resource. 963 * 964 * <h5 class='figure'>Example:</h5> 965 * <p class='bjava'> 966 * <ja>@Rest</ja>( 967 * children={ChildResource.<jk>class</jk>} 968 * ) 969 * <jk>public class</jk> TopLevelResource <jk>extends</jk> BasicRestServlet {...} 970 * 971 * <ja>@Rest</ja>( 972 * path=<js>"/child"</js>, 973 * children={GrandchildResource.<jk>class</jk>} 974 * ) 975 * <jk>public class</jk> ChildResource {...} 976 * 977 * <ja>@Rest</ja>( 978 * path=<js>"/grandchild"</js> 979 * ) 980 * <jk>public class</jk> GrandchildResource { 981 * <ja>@RestGet</ja>(<js>"/"</js>) 982 * <jk>public</jk> String sayHello() { 983 * <jk>return</jk> <js>"Hello!"</js>; 984 * } 985 * } 986 * </p> 987 * <p> 988 * In the example above, assuming the <c>TopLevelResource</c> servlet is deployed to path <c>/myContext/myServlet</c>, 989 * then the <c>sayHello</c> method is accessible through the URI <c>/myContext/myServlet/child/grandchild</c>. 990 * 991 * <p> 992 * Note that in this scenario, the <c>path</c> attribute is not defined on the top-level resource. 993 * Specifying the path on the top-level resource has no effect, but can be used for readability purposes. 994 * 995 * <h5 class='topic'>Path variables</h5> 996 * <p> 997 * The path can contain variables that get resolved to {@link org.apache.juneau.http.annotation.Path @Path} parameters 998 * or access through the {@link RestRequest#getPathParams()} method. 999 * 1000 * <h5 class='figure'>Example:</h5> 1001 * <p class='bjava'> 1002 * <ja>@Rest</ja>( 1003 * path=<js>"/myResource/{foo}/{bar}"</js> 1004 * ) 1005 * <jk>public class</jk> MyResource <jk>extends</jk> BasicRestServlet { 1006 * 1007 * <ja>@RestGet</ja>(<js>"/{baz}"</js>) 1008 * <jk>public void</jk> String doX(<ja>@Path</ja> String <jv>foo</jv>, <ja>@Path</ja> <jk>int</jk> <jv>bar</jv>, <ja>@Path</ja> MyPojo <jv>baz</jv>) { 1009 * ... 1010 * } 1011 * } 1012 * </p> 1013 * 1014 * <p> 1015 * Variables can be used on either top-level or child resources and can be defined on multiple levels. 1016 * 1017 * <p> 1018 * All variables in the path must be specified or else the target will not resolve and a <c>404</c> will result. 1019 * 1020 * <p> 1021 * When variables are used on a path of a top-level resource deployed as a Spring bean in a Spring Boot application, 1022 * the first part of the URL must be a literal which will be used as the servlet path of the registered servlet. 1023 * 1024 * <h5 class='section'>Notes:</h5><ul> 1025 * <li class='note'> 1026 * The leading slash is optional. <js>"/myResource"</js> and <js>"myResource"</js> is equivalent. 1027 * <li class='note'> 1028 * The paths <js>"/myResource"</js> and <js>"/myResource/*"</js> are equivalent. 1029 * <li class='note'> 1030 * Paths must not end with <js>"/"</js> (per the servlet spec). 1031 * </ul> 1032 * 1033 * <h5 class='section'>Inheritance Rules</h5> 1034 * <ul> 1035 * <li>Path is searched for in child-to-parent order. 1036 * </ul> 1037 * 1038 * <h5 class='section'>See Also:</h5><ul> 1039 * <li class='jm'>{@link org.apache.juneau.rest.RestContext.Builder#path(String)} 1040 * </ul> 1041 * 1042 * @return The annotation value. 1043 */ 1044 String path() default ""; 1045 1046 /** 1047 * Default path parameter definitions. 1048 * 1049 * <p> 1050 * Provides default values for {@link Path @Path} annotations on method parameters across all methods in this class. 1051 * 1052 * <h5 class='section'>Example:</h5> 1053 * <p class='bjava'> 1054 * <ja>@Rest</ja>( 1055 * pathParams={ 1056 * <ja>@Path</ja>(name=<js>"version"</js>, def=<js>"v1"</js>) 1057 * } 1058 * ) 1059 * <jk>public class</jk> MyResource {...} 1060 * </p> 1061 * 1062 * @return The annotation value. 1063 * @since 9.2.0 1064 */ 1065 Path[] pathParams() default {}; 1066 1067 /** 1068 * Supported accept media types. 1069 * 1070 * <p> 1071 * Overrides the media types inferred from the serializers that identify what media types can be produced by the resource. 1072 * 1073 * <h5 class='section'>Notes:</h5><ul> 1074 * <li class='note'> 1075 * Supports <a class="doclink" href="https://juneau.apache.org/docs/topics/RestServerSvlVariables">SVL Variables</a> 1076 * (e.g. <js>"$L{my.localized.variable}"</js>). 1077 * </ul> 1078 * 1079 * <h5 class='section'>See Also:</h5><ul> 1080 * <li class='jm'>{@link org.apache.juneau.rest.RestContext.Builder#produces(MediaType...)} 1081 * </ul> 1082 * 1083 * @return The annotation value. 1084 */ 1085 String[] produces() default {}; 1086 1087 /** 1088 * Default query parameter definitions. 1089 * 1090 * <p> 1091 * Provides default values for {@link Query @Query} annotations on method parameters across all methods in this class. 1092 * Values specified here are used as defaults when the same property is not explicitly defined on a method parameter's 1093 * {@link Query @Query} annotation. 1094 * 1095 * <h5 class='section'>Example:</h5> 1096 * <p class='bjava'> 1097 * <jc>// Define common query parameters at class level</jc> 1098 * <ja>@Rest</ja>( 1099 * queryParams={ 1100 * <ja>@Query</ja>(name=<js>"format"</js>, def=<js>"json"</js>, description=<js>"Output format"</js>), 1101 * <ja>@Query</ja>(name=<js>"verbose"</js>, def=<js>"false"</js>, schema=<ja>@Schema</ja>(type=<js>"boolean"</js>)) 1102 * } 1103 * ) 1104 * <jk>public class</jk> MyResource { 1105 * 1106 * <jc>// Method will inherit the default query parameter definitions</jc> 1107 * <ja>@RestGet</ja> 1108 * <jk>public</jk> String doGet(<ja>@Query</ja>(<js>"format"</js>) String format, <ja>@Query</ja>(<js>"verbose"</js>) <jk>boolean</jk> verbose) {...} 1109 * 1110 * <jc>// Can override defaults on a per-method basis</jc> 1111 * <ja>@RestGet</ja> 1112 * <jk>public</jk> String doGet2(<ja>@Query</ja>(name=<js>"format"</js>, def=<js>"xml"</js>) String format) {...} 1113 * } 1114 * </p> 1115 * 1116 * <h5 class='section'>Notes:</h5><ul> 1117 * <li class='note'> 1118 * These defaults apply to validation, parsing, and OpenAPI/Swagger documentation generation. 1119 * <li class='note'> 1120 * Method-level {@link Query @Query} annotations take precedence over class-level definitions. 1121 * <li class='note'> 1122 * The {@link Query#name() name} attribute must be specified for each query definition. 1123 * </ul> 1124 * 1125 * @return The annotation value. 1126 * @since 9.2.0 1127 */ 1128 Query[] queryParams() default {}; 1129 1130 /** 1131 * Render response stack traces in responses. 1132 * 1133 * <p> 1134 * Render stack traces in HTTP response bodies when errors occur. 1135 * 1136 * <h5 class='section'>Notes:</h5><ul> 1137 * <li class='note'> 1138 * Supports <a class="doclink" href="https://juneau.apache.org/docs/topics/RestServerSvlVariables">SVL Variables</a> 1139 * (e.g. <js>"$L{my.localized.variable}"</js>). 1140 * </ul> 1141 * 1142 * @return The annotation value. 1143 */ 1144 String renderResponseStackTraces() default ""; 1145 1146 /** 1147 * Response processors. 1148 * 1149 * <p> 1150 * Specifies a list of {@link ResponseProcessor} classes that know how to convert POJOs returned by REST methods or 1151 * set via {@link RestResponse#setContent(Object)} into appropriate HTTP responses. 1152 * 1153 * <h5 class='section'>See Also:</h5><ul> 1154 * <li class='jm'>{@link org.apache.juneau.rest.RestContext.Builder#responseProcessors()} 1155 * </ul> 1156 * 1157 * @return The annotation value. 1158 */ 1159 Class<? extends ResponseProcessor>[] responseProcessors() default {}; 1160 1161 /** 1162 * REST children class. 1163 * 1164 * <p> 1165 * Allows you to extend the {@link RestChildren} class to modify how any of the methods are implemented. 1166 * 1167 * <h5 class='section'>See Also:</h5><ul> 1168 * <li class='jm'>{@link org.apache.juneau.rest.RestContext.Builder#restChildrenClass(Class)} 1169 * </ul> 1170 * 1171 * @return The annotation value. 1172 */ 1173 Class<? extends RestChildren> restChildrenClass() default RestChildren.Void.class; 1174 1175 /** 1176 * Java REST operation method parameter resolvers. 1177 * 1178 * <p> 1179 * By default, the Juneau framework will automatically Java method parameters of various types (e.g. 1180 * <c>RestRequest</c>, <c>Accept</c>, <c>Reader</c>). 1181 * <br>This setting allows you to provide your own resolvers for your own class types that you want resolved. 1182 * 1183 * <h5 class='section'>See Also:</h5><ul> 1184 * <li class='jm'>{@link org.apache.juneau.rest.RestContext.Builder#restOpArgs(Class...)} 1185 * </ul> 1186 * 1187 * @return The annotation value. 1188 */ 1189 Class<? extends RestOpArg>[] restOpArgs() default {}; 1190 1191 /** 1192 * Role guard. 1193 * 1194 * <p> 1195 * An expression defining if a user with the specified roles are allowed to access methods on this class. 1196 * 1197 * <p> 1198 * This is a shortcut for specifying {@link RestOp#roleGuard()} on all the REST operations on a class. 1199 * 1200 * <h5 class='section'>Example:</h5> 1201 * <p class='bjava'> 1202 * <ja>@Rest</ja>( 1203 * path=<js>"/foo"</js>, 1204 * roleGuard=<js>"ROLE_ADMIN || (ROLE_READ_WRITE && ROLE_SPECIAL)"</js> 1205 * ) 1206 * <jk>public class</jk> MyResource <jk>extends</jk> BasicRestServlet { 1207 * ... 1208 * } 1209 * </p> 1210 * 1211 * <h5 class='section'>Notes:</h5><ul> 1212 * <li class='note'> 1213 * Supports any of the following expression constructs: 1214 * <ul> 1215 * <li><js>"foo"</js> - Single arguments. 1216 * <li><js>"foo,bar,baz"</js> - Multiple OR'ed arguments. 1217 * <li><js>"foo | bar | baz"</js> - Multiple OR'ed arguments, pipe syntax. 1218 * <li><js>"foo || bar || baz"</js> - Multiple OR'ed arguments, Java-OR syntax. 1219 * <li><js>"fo*"</js> - Patterns including <js>'*'</js> and <js>'?'</js>. 1220 * <li><js>"fo* & *oo"</js> - Multiple AND'ed arguments, ampersand syntax. 1221 * <li><js>"fo* && *oo"</js> - Multiple AND'ed arguments, Java-AND syntax. 1222 * <li><js>"fo* || (*oo || bar)"</js> - Parenthesis. 1223 * </ul> 1224 * <li> 1225 * AND operations take precedence over OR operations (as expected). 1226 * <li> 1227 * Whitespace is ignored. 1228 * <li> 1229 * <jk>null</jk> or empty expressions always match as <jk>false</jk>. 1230 * <li> 1231 * If patterns are used, you must specify the list of declared roles using {@link #rolesDeclared()} or {@link org.apache.juneau.rest.RestOpContext.Builder#rolesDeclared(String...)}. 1232 * <li> 1233 * Supports <a class="doclink" href="https://juneau.apache.org/docs/topics/RestServerSvlVariables">SVL Variables</a> 1234 * (e.g. <js>"$L{my.localized.variable}"</js>). 1235 * </ul> 1236 * 1237 * <h5 class='section'>See Also:</h5><ul> 1238 * <li class='jm'>{@link org.apache.juneau.rest.RestOpContext.Builder#roleGuard(String)} 1239 * </ul> 1240 * 1241 * @return The annotation value. 1242 */ 1243 String roleGuard() default ""; 1244 1245 /** 1246 * Declared roles. 1247 * 1248 * <p> 1249 * A comma-delimited list of all possible user roles. 1250 * 1251 * <p> 1252 * Used in conjunction with {@link #roleGuard()} is used with patterns. 1253 * 1254 * <p> 1255 * This is a shortcut for specifying {@link RestOp#rolesDeclared()} on all the REST operations on a class. 1256 * 1257 * <h5 class='section'>Example:</h5> 1258 * <p class='bjava'> 1259 * <ja>@Rest</ja>( 1260 * rolesDeclared=<js>"ROLE_ADMIN,ROLE_READ_WRITE,ROLE_READ_ONLY,ROLE_SPECIAL"</js>, 1261 * roleGuard=<js>"ROLE_ADMIN || (ROLE_READ_WRITE && ROLE_SPECIAL)"</js> 1262 * ) 1263 * <jk>public class</jk> MyResource <jk>extends</jk> BasicRestServlet { 1264 * ... 1265 * } 1266 * </p> 1267 * 1268 * <h5 class='section'>See Also:</h5><ul> 1269 * <li class='jm'>{@link org.apache.juneau.rest.RestOpContext.Builder#rolesDeclared(String...)} 1270 * </ul> 1271 * 1272 * @return The annotation value. 1273 */ 1274 String rolesDeclared() default ""; 1275 1276 /** 1277 * Specifies the serializers for POJOs into HTTP response bodies. 1278 * 1279 * <p> 1280 * Serializer are used to convert POJOs to HTTP response bodies. 1281 * <br>Any of the Juneau framework serializers can be used in this setting. 1282 * <br>The serializer selected is based on the request <c>Accept</c> header matched against the values returned by the following method 1283 * using a best-match algorithm: 1284 * <ul class='javatree'> 1285 * <li class='jm'>{@link Serializer#getMediaTypeRanges()} 1286 * </ul> 1287 * 1288 * <p> 1289 * Serializers are automatically inherited from {@link Rest#serializers()} annotations on parent classes with the serializers on child classes 1290 * prepended to the serializer group. 1291 * The {@link org.apache.juneau.serializer.SerializerSet.NoInherit} class can be used to prevent inheriting from the parent class. 1292 * 1293 * <h5 class='section'>Example:</h5> 1294 * <p class='bjava'> 1295 * <jc>// Define a REST resource that can produce JSON and XML.</jc> 1296 * <ja>@Rest</ja>( 1297 * serializers={ 1298 * JsonParser.<jk>class</jk>, 1299 * XmlParser.<jk>class</jk> 1300 * } 1301 * ) 1302 * <jk>public class</jk> MyResource { 1303 * ... 1304 * } 1305 * </p> 1306 * 1307 * <p> 1308 * The serializers can also be tailored at the method level using {@link RestOp#serializers()} (and related annotations). 1309 * 1310 * <p> 1311 * The programmatic equivalent to this annotation is: 1312 * <p class='bjava'> 1313 * RestContext.Builder <jv>builder</jv> = RestContext.<jsm>create</jsm>(<jv>resource</jv>); 1314 * <jv>builder</jv>.getSerializers().add(<jv>classes</jv>); 1315 * </p> 1316 * 1317 * <h5 class='section'>Inheritance Rules</h5> 1318 * <ul> 1319 * <li>Serializers on child override those on parent class. 1320 * <li>{@link org.apache.juneau.serializer.SerializerSet.Inherit} class can be used to inherit and augment values from parent. 1321 * <li>{@link org.apache.juneau.serializer.SerializerSet.NoInherit} class can be used to suppress inheriting from parent. 1322 * <li>Serializers on methods take precedence over those on classes. 1323 * </ul> 1324 * 1325 * <h5 class='section'>See Also:</h5><ul> 1326 * <li class='link'><a class="doclink" href="https://juneau.apache.org/docs/topics/Marshalling">Marshalling</a> 1327 * </ul> 1328 * 1329 * @return The annotation value. 1330 */ 1331 Class<? extends Serializer>[] serializers() default {}; 1332 1333 /** 1334 * Optional site name. 1335 * 1336 * <p> 1337 * The site name is intended to be a title that can be applied to the entire site. 1338 * 1339 * <p> 1340 * One possible use is if you want to add the same title to the top of all pages by defining a header on a 1341 * common parent class like so: 1342 * <p class='bjava'> 1343 * <ja>@HtmlDocConfig</ja>( 1344 * header={ 1345 * <js>"<h1>$RS{siteName}</h1>"</js>, 1346 * <js>"<h2>$RS{title}</h2>"</js> 1347 * } 1348 * ) 1349 * </p> 1350 * 1351 * <h5 class='section'>Notes:</h5><ul> 1352 * <li class='note'> 1353 * Supports <a class="doclink" href="https://juneau.apache.org/docs/topics/RestServerSvlVariables">SVL Variables</a> 1354 * (e.g. <js>"$L{my.localized.variable}"</js>). 1355 * </ul> 1356 * 1357 * @return The annotation value. 1358 */ 1359 String siteName() default ""; 1360 1361 /** 1362 * Static files. 1363 * 1364 * <p> 1365 * Used to retrieve localized files to be served up as static files through the REST API via the following 1366 * predefined methods: 1367 * <ul class='javatree'> 1368 * <li class='jm'>{@link BasicRestObject#getHtdoc(String, Locale)}. 1369 * <li class='jm'>{@link BasicRestServlet#getHtdoc(String, Locale)}. 1370 * </ul> 1371 * 1372 * <p> 1373 * The static file finder can be accessed through the following methods: 1374 * <ul class='javatree'> 1375 * <li class='jm'>{@link RestContext#getStaticFiles()} 1376 * <li class='jm'>{@link RestRequest#getStaticFiles()} 1377 * </ul> 1378 * 1379 * <h5 class='section'>Inheritance Rules</h5> 1380 * <ul> 1381 * <li>Static files on child are combined with those on parent class. 1382 * <li>Static files are are executed child-to-parent in the order they appear in the annotation. 1383 * </ul> 1384 * 1385 * @return The annotation value. 1386 */ 1387 Class<? extends StaticFiles> staticFiles() default StaticFiles.Void.class; 1388 1389 /** 1390 * Provides swagger-specific metadata on this resource. 1391 * 1392 * <p> 1393 * Used to populate the auto-generated OPTIONS swagger documentation. 1394 * 1395 * <h5 class='section'>Example:</h5> 1396 * <p class='bjava'> 1397 * <ja>@Rest</ja>( 1398 * path=<js>"/addressBook"</js>, 1399 * 1400 * <jc>// Swagger info.</jc> 1401 * swagger=@Swagger({ 1402 * <js>"contact:{name:'John Smith',email:'john@smith.com'},"</js>, 1403 * <js>"license:{name:'Apache 2.0',url:'http://www.apache.org/licenses/LICENSE-2.0.html'},"</js>, 1404 * <js>"version:'2.0',</js>, 1405 * <js>"termsOfService:'You are on your own.',"</js>, 1406 * <js>"tags:[{name:'Java',description:'Java utility',externalDocs:{description:'Home page',url:'http://juneau.apache.org'}}],"</js>, 1407 * <js>"externalDocs:{description:'Home page',url:'http://juneau.apache.org'}"</js> 1408 * }) 1409 * ) 1410 * </p> 1411 * 1412 * <h5 class='section'>See Also:</h5><ul> 1413 * <li class='ja'>{@link Swagger} 1414 * </ul> 1415 * 1416 * @return The annotation value. 1417 */ 1418 Swagger swagger() default @Swagger; 1419 1420 /** 1421 * Swagger provider. 1422 * 1423 * <h5 class='section'>See Also:</h5><ul> 1424 * <li class='jm'>{@link org.apache.juneau.rest.RestContext.Builder#swaggerProvider(Class)} 1425 * </ul> 1426 * 1427 * @return The annotation value. 1428 */ 1429 Class<? extends SwaggerProvider> swaggerProvider() default SwaggerProvider.Void.class; 1430 1431 /** 1432 * Optional servlet title. 1433 * 1434 * <p> 1435 * It is used to populate the Swagger title field. 1436 * 1437 * <h5 class='section'>Inheritance Rules</h5> 1438 * <ul> 1439 * <li>Label is searched for in child-to-parent order. 1440 * </ul> 1441 * 1442 * <h5 class='section'>Notes:</h5><ul> 1443 * <li class='note'> 1444 * Supports <a class="doclink" href="https://juneau.apache.org/docs/topics/RestServerSvlVariables">SVL Variables</a> 1445 * (e.g. <js>"$L{my.localized.variable}"</js>). 1446 * <li class='note'> 1447 * Corresponds to the swagger field <c>/info/title</c>. 1448 * </ul> 1449 * 1450 * @return The annotation value. 1451 */ 1452 String[] title() default {}; 1453 1454 /** 1455 * Resource authority path. 1456 * 1457 * <p> 1458 * Overrides the authority path value for this resource and any child resources. 1459 * 1460 * <h5 class='section'>Notes:</h5><ul> 1461 * <li class='note'> 1462 * Supports <a class="doclink" href="https://juneau.apache.org/docs/topics/RestServerSvlVariables">SVL Variables</a> 1463 * (e.g. <js>"$L{my.localized.variable}"</js>). 1464 * </ul> 1465 * 1466 * <h5 class='section'>See Also:</h5><ul> 1467 * <li class='jm'>{@link org.apache.juneau.rest.RestContext.Builder#uriAuthority(String)} 1468 * </ul> 1469 * 1470 * @return The annotation value. 1471 */ 1472 String uriAuthority() default ""; 1473 1474 /** 1475 * Resource context path. 1476 * 1477 * <p> 1478 * Overrides the context path value for this resource and any child resources. 1479 * 1480 * <h5 class='section'>Notes:</h5><ul> 1481 * <li class='note'> 1482 * Supports <a class="doclink" href="https://juneau.apache.org/docs/topics/RestServerSvlVariables">SVL Variables</a> 1483 * (e.g. <js>"$L{my.localized.variable}"</js>). 1484 * </ul> 1485 * 1486 * <h5 class='section'>See Also:</h5><ul> 1487 * <li class='jm'>{@link org.apache.juneau.rest.RestContext.Builder#uriContext(String)} 1488 * </ul> 1489 * 1490 * @return The annotation value. 1491 */ 1492 String uriContext() default ""; 1493 1494 /** 1495 * URI-resolution relativity. 1496 * 1497 * <p> 1498 * Specifies how relative URIs should be interpreted by serializers. 1499 * 1500 * <p> 1501 * See {@link UriResolution} for possible values. 1502 * 1503 * <h5 class='section'>Notes:</h5><ul> 1504 * <li class='note'> 1505 * Supports <a class="doclink" href="https://juneau.apache.org/docs/topics/RestServerSvlVariables">SVL Variables</a> 1506 * (e.g. <js>"$L{my.localized.variable}"</js>). 1507 * </ul> 1508 * 1509 * <h5 class='section'>See Also:</h5><ul> 1510 * <li class='jm'>{@link org.apache.juneau.rest.RestContext.Builder#uriRelativity(UriRelativity)} 1511 * </ul> 1512 * 1513 * @return The annotation value. 1514 */ 1515 String uriRelativity() default ""; 1516 1517 /** 1518 * URI-resolution. 1519 * 1520 * <p> 1521 * Specifies how relative URIs should be interpreted by serializers. 1522 * 1523 * <p> 1524 * See {@link UriResolution} for possible values. 1525 * 1526 * <h5 class='section'>Notes:</h5><ul> 1527 * <li class='note'> 1528 * Supports <a class="doclink" href="https://juneau.apache.org/docs/topics/RestServerSvlVariables">SVL Variables</a> 1529 * (e.g. <js>"$L{my.localized.variable}"</js>). 1530 * </ul> 1531 * 1532 * <h5 class='section'>See Also:</h5><ul> 1533 * <li class='jm'>{@link org.apache.juneau.rest.RestContext.Builder#uriResolution(UriResolution)} 1534 * </ul> 1535 * 1536 * @return The annotation value. 1537 */ 1538 String uriResolution() default ""; 1539}