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