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.http.annotation; 014 015import static java.lang.annotation.ElementType.*; 016import static java.lang.annotation.RetentionPolicy.*; 017 018import java.lang.annotation.*; 019 020import org.apache.juneau.jsonschema.annotation.Items; 021import org.apache.juneau.*; 022import org.apache.juneau.httppart.*; 023import org.apache.juneau.oapi.*; 024 025/** 026 * REST response header annotation. 027 * 028 * <p> 029 * Annotation used to denote an HTTP response header. 030 * 031 * <p> 032 * Can be used in the following locations: 033 * <ul> 034 * <li>Arguments of server-side <ja>@RestMethod</ja>-annotated methods. 035 * <li>Methods and return types of server-side and client-side <ja>@Response</ja>-annotated interfaces. 036 * </ul> 037 * 038 * <h5 class='topic'>Arguments of server-side <ja>@RestMethod</ja>-annotated methods</h5> 039 * 040 * <p> 041 * On server-side REST, this annotation can be applied to method parameters to identify them as an HTTP response header. 042 * <br>In this case, the annotation can only be applied to subclasses of type {@link Value}. 043 * 044 * <p> 045 * The following examples show 3 different ways of accomplishing the same task of setting an HTTP header 046 * on a response: 047 * 048 * <p class='bcode w800'> 049 * <jc>// Example #1 - Setting header directly on RestResponse object.</jc> 050 * <ja>@RestMethod</ja>(...) 051 * <jk>public void</jk> login(RestResponse res) { 052 * res.setHeader(<js>"X-Rate-Limit"</js>, 1000); 053 * ... 054 * } 055 * 056 * <jc>// Example #2 - Use on parameter.</jc> 057 * <ja>@RestMethod</ja>(...) 058 * <jk>public void</jk> login( 059 * <ja>@ResponseHeader</ja>( 060 * name=<js>"X-Rate-Limit"</js>, 061 * type=<js>"integer"</js>, 062 * format=<js>"int32"</js>, 063 * description=<js>"Calls per hour allowed by the user."</js>, 064 * example=<js>"123"</js> 065 * ) 066 * Value<Integer> rateLimit 067 * ) { 068 * rateLimit.set(1000); 069 * ... 070 * } 071 * 072 * <jc>// Example #3 - Use on type.</jc> 073 * <ja>@RestMethod</ja>(...) 074 * <jk>public void</jk> login(Value<RateLimit> rateLimit) { 075 * rateLimit.set(new RateLimit(1000)); 076 * ... 077 * } 078 * 079 * <ja>@ResponseHeader</ja>( 080 * name=<js>"X-Rate-Limit"</js>, 081 * type=<js>"integer"</js>, 082 * format=<js>"int32"</js>, 083 * description=<js>"Calls per hour allowed by the user."</js>, 084 * example=<js>"123"</js> 085 * ) 086 * <jk>public class</jk> RateLimit { 087 * <jc>// OpenApiPartSerializer knows to look for this method based on format/type.</jc> 088 * <jk>public</jk> Integer toInteger() { 089 * <jk>return</jk> 1000; 090 * } 091 * } 092 * </p> 093 * 094 * <h5 class='topic'>Public methods of @Response-annotated types</h5> 095 * 096 * <p> 097 * On server-side REST, this annotation can also be applied to public methods of {@link Response}-annotated methods. 098 * 099 * <p class='bcode w800'> 100 * <ja>@Response</ja> 101 * <jk>public class</jk> AddPetSuccess { 102 * 103 * <ja>@ResponseHeader</ja>( 104 * name=<js>"X-PetId"</js>, 105 * type=<js>"integer"</js>, 106 * format=<js>"int32"</js>, 107 * description=<js>"ID of added pet."</js>, 108 * example=<js>"123"</js> 109 * ) 110 * <jk>public int</jk> getPetId() {...} 111 * } 112 * </p> 113 * 114 * 115 * <ul class='seealso'> 116 * <li class='link'>{@doc RestResponseHeaderAnnotation} 117 * <li class='link'>{@doc RestSwagger} 118 * <li class='extlink'>{@doc ExtSwaggerHeaderObject} 119 * </ul> 120 * 121 * <h5 class='topic'>Methods and return types of server-side and client-side @Response-annotated interfaces</h5> 122 * 123 * <ul class='seealso'> 124 * <li class='link'>{@doc RestResponseAnnotation} 125 * <li class='link'>{@doc RestcResponse} 126 * </ul> 127*/ 128@Documented 129@Target({PARAMETER,METHOD,TYPE}) 130@Retention(RUNTIME) 131@Inherited 132public @interface ResponseHeader { 133 134 /** 135 * The HTTP status (or statuses) of the response. 136 * 137 * <ul class='notes'> 138 * <li> 139 * The is a comma-delimited list of HTTP status codes that this header applies to. 140 * <li> 141 * The default value is <js>"200"</js>. 142 * </ul> 143 */ 144 int[] code() default {}; 145 146 /** 147 * The HTTP header name. 148 * 149 * <ul class='notes'> 150 * <li> 151 * The format is plain-text. 152 * </ul> 153 */ 154 String name() default ""; 155 156 /** 157 * Synonym for {@link #name()}. 158 */ 159 String n() default ""; 160 161 /** 162 * A synonym for {@link #name()}. 163 * 164 * <p> 165 * Allows you to use shortened notation if you're only specifying the name. 166 * 167 * <p> 168 * The following are completely equivalent ways of defining a response header: 169 * <p class='bcode w800'> 170 * <ja>@ResponseHeader</ja>(name=<js>"X-Rate-Limit"</js>) Value<Integer> rateLimit) 171 * </p> 172 * <p class='bcode w800'> 173 * <ja>@ResponseHeader</ja>(<js>"X-Rate-Limit"</js>) Value<Integer> rateLimit) 174 * </p> 175 */ 176 String value() default ""; 177 178 /** 179 * Specifies the {@link HttpPartSerializer} class used for serializing values to strings. 180 * 181 * <p> 182 * Overrides for this part the part serializer defined on the REST resource which by default is {@link OpenApiSerializer}. 183 */ 184 Class<? extends HttpPartSerializer> serializer() default HttpPartSerializer.Null.class; 185 186 /** 187 * <mk>description</mk> field of the {@doc ExtSwaggerHeaderObject}. 188 * 189 * <h5 class='section'>Used for:</h5> 190 * <ul class='spaced-list'> 191 * <li> 192 * Server-side generated Swagger documentation. 193 * </ul> 194 * 195 * <ul class='notes'> 196 * <li> 197 * The format is plain text. 198 * <br>Multiple lines are concatenated with newlines. 199 * <li> 200 * Supports {@doc RestSvlVariables} 201 * (e.g. <js>"$L{my.localized.variable}"</js>). 202 * </ul> 203 */ 204 String[] description() default {}; 205 206 /** 207 * Synonym for {@link #description()}. 208 */ 209 String[] d() default {}; 210 211 /** 212 * <mk>type</mk> field of the {@doc ExtSwaggerHeaderObject}. 213 * 214 * <p> 215 * The type of the parameter. 216 * 217 * <p> 218 * The possible values are: 219 * <ul class='spaced-list'> 220 * <li> 221 * <js>"string"</js> 222 * <li> 223 * <js>"number"</js> 224 * <li> 225 * <js>"integer"</js> 226 * <li> 227 * <js>"boolean"</js> 228 * <li> 229 * <js>"array"</js> 230 * <li> 231 * <js>"object"</js> 232 * <li> 233 * <js>"file"</js> 234 * </ul> 235 * 236 * <p> 237 * Static strings are defined in {@link ParameterType}. 238 * 239 * <h5 class='section'>Used for:</h5> 240 * <ul class='spaced-list'> 241 * <li> 242 * Server-side generated Swagger documentation. 243 * </ul> 244 * 245 * <ul class='seealso'> 246 * <li class='extlink'>{@doc ExtSwaggerDataTypes} 247 * </ul> 248 */ 249 String type() default ""; 250 251 /** 252 * Synonym for {@link #type()}. 253 */ 254 String t() default ""; 255 256 /** 257 * <mk>format</mk> field of the {@doc ExtSwaggerHeaderObject}. 258 * 259 * <p> 260 * The possible values are: 261 * <ul class='spaced-list'> 262 * <li> 263 * <js>"int32"</js> - Signed 32 bits. 264 * <br>Only valid with type <js>"integer"</js>. 265 * <li> 266 * <js>"int64"</js> - Signed 64 bits. 267 * <br>Only valid with type <js>"integer"</js>. 268 * <li> 269 * <js>"float"</js> - 32-bit floating point number. 270 * <br>Only valid with type <js>"number"</js>. 271 * <li> 272 * <js>"double"</js> - 64-bit floating point number. 273 * <br>Only valid with type <js>"number"</js>. 274 * <li> 275 * <js>"byte"</js> - BASE-64 encoded characters. 276 * <br>Only valid with type <js>"string"</js>. 277 * <li> 278 * <js>"binary"</js> - Hexadecimal encoded octets (e.g. <js>"00FF"</js>). 279 * <br>Only valid with type <js>"string"</js>. 280 * <li> 281 * <js>"date"</js> - An <a href='http://xml2rfc.ietf.org/public/rfc/html/rfc3339.html#anchor14'>RFC3339 full-date</a>. 282 * <br>Only valid with type <js>"string"</js>. 283 * <li> 284 * <js>"date-time"</js> - An <a href='http://xml2rfc.ietf.org/public/rfc/html/rfc3339.html#anchor14'>RFC3339 date-time</a>. 285 * <br>Only valid with type <js>"string"</js>. 286 * <li> 287 * <js>"password"</js> - Used to hint UIs the input needs to be obscured. 288 * <li> 289 * <js>"uon"</js> - UON notation (e.g. <js>"(foo=bar,baz=@(qux,123))"</js>). 290 * <br>Only valid with type <js>"object"</js>. 291 * </ul> 292 * 293 * <p> 294 * Static strings are defined in {@link FormatType}. 295 * 296 * <h5 class='section'>Used for:</h5> 297 * <ul class='spaced-list'> 298 * <li> 299 * Server-side generated Swagger documentation. 300 * </ul> 301 * 302 * <ul class='seealso'> 303 * <li class='extlink'>{@doc ExtSwaggerDataTypeFormats} 304 * </ul> 305 */ 306 String format() default ""; 307 308 /** 309 * Synonym for {@link #format()}. 310 */ 311 String f() default ""; 312 313 /** 314 * <mk>collectionFormat</mk> field of the {@doc ExtSwaggerHeaderObject}. 315 * 316 * <p> 317 * Determines the format of the array if <c>type</c> <js>"array"</js> is used. 318 * <br>Can only be used if <c>type</c> is <js>"array"</js>. 319 * 320 * <br>Possible values are: 321 * <ul class='spaced-list'> 322 * <li> 323 * <js>"csv"</js> (default) - Comma-separated values (e.g. <js>"foo,bar"</js>). 324 * <li> 325 * <js>"ssv"</js> - Space-separated values (e.g. <js>"foo bar"</js>). 326 * <li> 327 * <js>"tsv"</js> - Tab-separated values (e.g. <js>"foo\tbar"</js>). 328 * <li> 329 * <js>"pipes</js> - Pipe-separated values (e.g. <js>"foo|bar"</js>). 330 * <li> 331 * <js>"multi"</js> - Corresponds to multiple parameter instances instead of multiple values for a single instance (e.g. <js>"foo=bar&foo=baz"</js>). 332 * <li> 333 * <js>"uon"</js> - UON notation (e.g. <js>"@(foo,bar)"</js>). 334 * </ul> 335 * 336 * <p> 337 * Static strings are defined in {@link CollectionFormatType}. 338 * 339 * <h5 class='section'>Used for:</h5> 340 * <ul class='spaced-list'> 341 * <li> 342 * Server-side generated Swagger documentation. 343 * </ul> 344 * 345 * <p> 346 * Note that for collections/arrays parameters with POJO element types, the input is broken into a string array before being converted into POJO elements. 347 */ 348 String collectionFormat() default ""; 349 350 /** 351 * Synonym for {@link #collectionFormat()}. 352 */ 353 String cf() default ""; 354 355 /** 356 * <mk>$ref</mk> field of the {@doc ExtSwaggerHeaderObject}. 357 * 358 * <p> 359 * Denotes a reference to a definition object. 360 * 361 * <h5 class='section'>Used for:</h5> 362 * <ul class='spaced-list'> 363 * <li> 364 * Server-side generated Swagger documentation. 365 * </ul> 366 */ 367 String $ref() default ""; 368 369 /** 370 * <mk>maximum</mk> field of the {@doc ExtSwaggerHeaderObject}. 371 * 372 * <h5 class='section'>Used for:</h5> 373 * <ul class='spaced-list'> 374 * <li> 375 * Server-side generated Swagger documentation. 376 * </ul> 377 */ 378 String maximum() default ""; 379 380 /** 381 * Synonym for {@link #maximum()}. 382 */ 383 String max() default ""; 384 385 /** 386 * <mk>minimum</mk> field of the {@doc ExtSwaggerHeaderObject}. 387 * 388 * <h5 class='section'>Used for:</h5> 389 * <ul class='spaced-list'> 390 * <li> 391 * Server-side generated Swagger documentation. 392 * </ul> 393 */ 394 String minimum() default ""; 395 396 /** 397 * Synonym for {@link #minimum()}. 398 */ 399 String min() default ""; 400 401 /** 402 * <mk>multipleOf</mk> field of the {@doc ExtSwaggerHeaderObject}. 403 * 404 * <h5 class='section'>Used for:</h5> 405 * <ul class='spaced-list'> 406 * <li> 407 * Server-side generated Swagger documentation. 408 * </ul> 409 */ 410 String multipleOf() default ""; 411 412 /** 413 * Synonym for {@link #multipleOf()}. 414 */ 415 String mo() default ""; 416 417 /** 418 * <mk>maxLength</mk> field of the {@doc ExtSwaggerHeaderObject}. 419 * 420 * <h5 class='section'>Used for:</h5> 421 * <ul class='spaced-list'> 422 * <li> 423 * Server-side generated Swagger documentation. 424 * </ul> 425 */ 426 long maxLength() default -1; 427 428 /** 429 * Synonym for {@link #maxLength()}. 430 */ 431 long maxl() default -1; 432 433 /** 434 * <mk>minLength</mk> field of the {@doc ExtSwaggerHeaderObject}. 435 * 436 * <h5 class='section'>Used for:</h5> 437 * <ul class='spaced-list'> 438 * <li> 439 * Server-side generated Swagger documentation. 440 * </ul> 441 */ 442 long minLength() default -1; 443 444 /** 445 * Synonym for {@link #minLength()}. 446 */ 447 long minl() default -1; 448 449 /** 450 * <mk>pattern</mk> field of the {@doc ExtSwaggerHeaderObject}. 451 * 452 * <p> 453 * A string value is valid if it matches the specified regular expression pattern. 454 * 455 * <p> 456 * If validation fails during serialization or parsing, the part serializer/parser will throw a {@link SchemaValidationException}. 457 * 458 * <p> 459 * Only allowed for the following types: <js>"string"</js>. 460 * 461 * <h5 class='section'>Used for:</h5> 462 * <ul class='spaced-list'> 463 * <li> 464 * Server-side generated Swagger documentation. 465 * </ul> 466 */ 467 String pattern() default ""; 468 469 /** 470 * Synonym for {@link #pattern()}. 471 */ 472 String p() default ""; 473 474 /** 475 * <mk>maxItems</mk> field of the {@doc ExtSwaggerHeaderObject}. 476 * 477 * <h5 class='section'>Used for:</h5> 478 * <ul class='spaced-list'> 479 * <li> 480 * Server-side generated Swagger documentation. 481 * </ul> 482 */ 483 long maxItems() default -1; 484 485 /** 486 * Synonym for {@link #maxItems()}. 487 */ 488 long maxi() default -1; 489 490 /** 491 * <mk>minItems</mk> field of the {@doc ExtSwaggerHeaderObject}. 492 * 493 * <h5 class='section'>Used for:</h5> 494 * <ul class='spaced-list'> 495 * <li> 496 * Server-side generated Swagger documentation. 497 * </ul> 498 */ 499 long minItems() default -1; 500 501 /** 502 * Synonym for {@link #minItems()}. 503 */ 504 long mini() default -1; 505 506 /** 507 * <mk>exclusiveMaximum</mk> field of the {@doc ExtSwaggerHeaderObject}. 508 * 509 * <h5 class='section'>Used for:</h5> 510 * <ul class='spaced-list'> 511 * <li> 512 * Server-side generated Swagger documentation. 513 * </ul> 514 */ 515 boolean exclusiveMaximum() default false; 516 517 /** 518 * Synonym for {@link #exclusiveMaximum()}. 519 */ 520 boolean emax() default false; 521 522 /** 523 * <mk>exclusiveMinimum</mk> field of the {@doc ExtSwaggerHeaderObject}. 524 * 525 * <h5 class='section'>Used for:</h5> 526 * <ul class='spaced-list'> 527 * <li> 528 * Server-side generated Swagger documentation. 529 * </ul> 530 */ 531 boolean exclusiveMinimum() default false; 532 533 /** 534 * Synonym for {@link #exclusiveMinimum()}. 535 */ 536 boolean emin() default false; 537 538 /** 539 * <mk>uniqueItems</mk> field of the {@doc ExtSwaggerHeaderObject}. 540 * 541 * <h5 class='section'>Used for:</h5> 542 * <ul class='spaced-list'> 543 * <li> 544 * Server-side generated Swagger documentation. 545 * </ul> 546 */ 547 boolean uniqueItems() default false; 548 549 /** 550 * Synonym for {@link #uniqueItems()}. 551 */ 552 boolean ui() default false; 553 554 /** 555 * <mk>items</mk> field of the {@doc ExtSwaggerHeaderObject}. 556 * 557 * <h5 class='section'>Used for:</h5> 558 * <ul class='spaced-list'> 559 * <li> 560 * Server-side generated Swagger documentation. 561 * </ul> 562 */ 563 Items items() default @Items; 564 565 /** 566 * <mk>default</mk> field of the {@doc ExtSwaggerHeaderObject}. 567 * 568 * <h5 class='section'>Used for:</h5> 569 * <ul class='spaced-list'> 570 * <li> 571 * Server-side generated Swagger documentation. 572 * </ul> 573 */ 574 String[] _default() default {}; 575 576 /** 577 * Synonym for {@link #_default()}. 578 */ 579 String[] df() default {}; 580 581 /** 582 * <mk>enum</mk> field of the {@doc ExtSwaggerHeaderObject}. 583 * 584 * <h5 class='section'>Used for:</h5> 585 * <ul class='spaced-list'> 586 * <li> 587 * Server-side generated Swagger documentation. 588 * </ul> 589 */ 590 String[] _enum() default {}; 591 592 /** 593 * Synonym for {@link #_enum()}. 594 */ 595 String[] e() default {}; 596 597 /** 598 * A serialized example of the parameter. 599 * 600 * <p> 601 * This attribute defines a representation of the value that is used by <c>BasicRestInfoProvider</c> to construct 602 * an example of parameter. 603 * 604 * <h5 class='section'>Example:</h5> 605 * <p class='bcode w800'> 606 * <ja>@ResponseHeader</ja>( 607 * name=<js>"Status"</js>, 608 * type=<js>"array"</js>, 609 * collectionFormat=<js>"csv"</js>, 610 * example=<js>"AVALIABLE,PENDING"</js> 611 * ) 612 * </p> 613 * 614 * <h5 class='section'>Used for:</h5> 615 * <ul class='spaced-list'> 616 * <li> 617 * Server-side generated Swagger documentation. 618 * </ul> 619 */ 620 String[] example() default {}; 621 622 /** 623 * Synonym for {@link #example()}. 624 */ 625 String[] ex() default {}; 626 627 /** 628 * Free-form value for the {@doc ExtSwaggerHeaderObject}. 629 * 630 * <p> 631 * This is a {@doc SimplifiedJson} object that makes up the swagger information for this field. 632 * 633 * <p> 634 * The following are completely equivalent ways of defining the swagger description of the Header object: 635 * <p class='bcode w800'> 636 * <jc>// Normal</jc> 637 * <ja>@ResponseHeader</ja>( 638 * name=<js>"Location"</js>, 639 * description=<js>"The new location of this resource"</js>, 640 * type=<js>"string"</js>, 641 * format=<js>"uri"</js> 642 * ) 643 * </p> 644 * <p class='bcode w800'> 645 * <jc>// Free-form</jc> 646 * <ja>@ResponseHeader</ja>( 647 * name=<js>"Location"</js>, 648 * api={ 649 * <js>"description: 'The new location of this resource',"</js>, 650 * <js>"type: 'string',"</js>, 651 * <js>"format: 'uri'"</js> 652 * } 653 * ) 654 * </p> 655 * <p class='bcode w800'> 656 * <jc>// Free-form using variables</jc> 657 * <ja>@ResponseHeader</ja>( 658 * name=<js>"Location"</js>, 659 * api=<js>"$L{locationSwagger}"</js> 660 * ) 661 * </p> 662 * <p class='bcode w800'> 663 * <mc>// Contents of MyResource.properties</mc> 664 * <mk>locationSwagger</mk> = <mv>{ description: "The new location of this resource", type: "string", format: "uri" }</mv> 665 * </p> 666 * 667 * <p> 668 * The reasons why you may want to use this field include: 669 * <ul> 670 * <li>You want to pull in the entire Swagger JSON definition for this body from an external source such as a properties file. 671 * <li>You want to add extra fields to the Swagger documentation that are not officially part of the Swagger specification. 672 * </ul> 673 * 674 * <h5 class='section'>Used for:</h5> 675 * <ul class='spaced-list'> 676 * <li> 677 * Server-side generated Swagger documentation. 678 * </ul> 679 * 680 * <ul class='notes'> 681 * <li> 682 * Note that the only swagger field you can't specify using this value is <js>"name"</js> whose value needs to be known during servlet initialization. 683 * <li> 684 * The format is a {@doc SimplifiedJson} object. 685 * <li> 686 * The leading/trailing <c>{ }</c> characters are optional. 687 * <br>The following two example are considered equivalent: 688 * <p class='bcode w800'> 689 * <ja>@ResponseHeader</ja>(<js>"{description:'The new location of this resource'}"</js>) 690 * </p> 691 * <p class='bcode w800'> 692 * <ja>@ResponseHeader</ja>(<js>"description:'The new location of this resource'"</js>) 693 * </p> 694 * <li> 695 * Supports {@doc RestSvlVariables} 696 * (e.g. <js>"$L{my.localized.variable}"</js>). 697 * <li> 698 * Values defined in this field supersede values pulled from the Swagger JSON file and are superseded by individual values defined on this annotation. 699 * </ul> 700 */ 701 String[] api() default {}; 702}