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