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