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.*; 019import java.util.*; 020 021import org.apache.juneau.jsonschema.annotation.Items; 022import org.apache.juneau.*; 023import org.apache.juneau.annotation.*; 024import org.apache.juneau.httppart.*; 025import org.apache.juneau.json.*; 026import org.apache.juneau.jsonschema.*; 027import org.apache.juneau.oapi.*; 028 029/** 030 * REST request header annotation. 031 * 032 * <p> 033 * Identifies a POJO to be used as the header of an HTTP request. 034 * 035 * <p> 036 * Can be used in the following locations: 037 * <ul> 038 * <li>Arguments and argument-types of server-side <ja>@RestMethod</ja>-annotated methods. 039 * <li>Arguments and argument-types of client-side <ja>@RemoteResource</ja>-annotated interfaces. 040 * <li>Methods and return types of server-side and client-side <ja>@Request</ja>-annotated interfaces. 041 * </ul> 042 * 043 * <h5 class='topic'>Arguments and argument-types of server-side @RestMethod-annotated methods</h5> 044 * 045 * Annotation that can be applied to a parameter of a <ja>@RestMethod</ja>-annotated method to identify it as a HTTP 046 * request header. 047 * 048 * <h5 class='section'>Example:</h5> 049 * <p class='bcode w800'> 050 * <ja>@RestMethod</ja>(name=<jsf>GET</jsf>) 051 * <jk>public void</jk> doGet(<ja>@Header</ja>(<js>"ETag"</js>) UUID etag) {...} 052 * </p> 053 * 054 * <p> 055 * This is functionally equivalent to the following code... 056 * <p class='bcode w800'> 057 * <ja>@RestMethod</ja>(name=<jsf>GET</jsf>) 058 * <jk>public void</jk> doPostPerson(RestRequest req, RestResponse res) { 059 * UUID etag = req.getHeader(UUID.<jk>class</jk>, <js>"ETag"</js>); 060 * ... 061 * } 062 * </p> 063 * 064 * <ul class='seealso'> 065 * <li class='link'>{@doc juneau-rest-server.HttpPartAnnotations.Header} 066 * <li class='link'>{@doc juneau-rest-server.Swagger} 067 * <li class='extlink'>{@doc SwaggerParameterObject} 068 * </ul> 069 * 070 * <h5 class='topic'>Arguments and argument-types of client-side @RemoteResource-annotated interfaces</h5> 071 * 072 * Annotation applied to Java method arguments of interface proxies to denote that they are serialized as an HTTP 073 * header value. 074 * 075 * <ul class='seealso'> 076 * <li class='link'>{@doc juneau-rest-client.RestProxies.Header} 077 * </ul> 078 * 079 * <h5 class='topic'>Methods and return types of server-side and client-side @Request-annotated interfaces</h5> 080 * 081 * <ul class='seealso'> 082 * <li class='link'>{@doc juneau-rest-server.HttpPartAnnotations.Request} 083 * <li class='link'>{@doc juneau-rest-client.RestProxies.Request} 084 * </ul> 085 */ 086@Documented 087@Target({PARAMETER,FIELD,METHOD,TYPE}) 088@Retention(RUNTIME) 089@Inherited 090public @interface Header { 091 092 /** 093 * Skips this value during serialization if it's an empty string or empty collection/array. 094 * 095 * <p> 096 * Note that <jk>null</jk> values are already ignored. 097 * 098 * <h5 class='section'>Used for:</h5> 099 * <ul class='spaced-list'> 100 * <li> 101 * Client-side schema-based serializing. 102 * </ul> 103 */ 104 boolean skipIfEmpty() default false; 105 106 /** 107 * Specifies the {@link HttpPartSerializer} class used for serializing values to strings. 108 * 109 * <p> 110 * Overrides for this part the part serializer defined on the REST client which by default is {@link OpenApiSerializer}. 111 */ 112 Class<? extends HttpPartSerializer> serializer() default HttpPartSerializer.Null.class; 113 114 /** 115 * Specifies the {@link HttpPartParser} class used for parsing strings to values. 116 * 117 * <p> 118 * Overrides for this part the part parser defined on the REST resource which by default is {@link OpenApiParser}. 119 */ 120 Class<? extends HttpPartParser> parser() default HttpPartParser.Null.class; 121 122 //================================================================================================================= 123 // Attributes common to all Swagger Parameter objects 124 //================================================================================================================= 125 126 /** 127 * HTTP header name. 128 * <p> 129 * A blank value (the default) indicates to reuse the bean property name when used on a request bean property. 130 * 131 * <p> 132 * The value should be either a valid HTTP header name, or <js>"*"</js> to represent multiple name/value pairs 133 * 134 * <p> 135 * A blank value (the default) has the following behavior: 136 * <ul class='spaced-list'> 137 * <li> 138 * If the data type is <c>NameValuePairs</c>, <c>Map</c>, or a bean, 139 * then it's the equivalent to <js>"*"</js> which will cause the value to be serialized as name/value pairs. 140 * 141 * <h5 class='figure'>Examples:</h5> 142 * <p class='bcode w800'> 143 * <jc>// When used on a REST method</jc> 144 * <ja>@RestMethod</ja>(path=<js>"/addPet"</js>) 145 * <jk>public void</jk> addPet(<ja>@Header</ja> ObjectMap allHeaderParameters) {...} 146 * </p> 147 * <p class='bcode w800'> 148 * <jc>// When used on a remote method parameter</jc> 149 * <ja>@RemoteResource</ja>(path=<js>"/myproxy"</js>) 150 * <jk>public interface</jk> MyProxy { 151 * 152 * <jc>// Equivalent to @Header("*")</jc> 153 * <ja>@RemoteMethod</ja>(path=<js>"/mymethod"</js>) 154 * String myProxyMethod1(<ja>@Header</ja> Map<String,Object> allHeaderParameters); 155 * } 156 * </p> 157 * <p class='bcode w800'> 158 * <jc>// When used on a request bean method</jc> 159 * <jk>public interface</jk> MyRequest { 160 * 161 * <jc>// Equivalent to @Header("*")</jc> 162 * <ja>@Header</ja> 163 * Map<String,Object> getFoo(); 164 * } 165 * </p> 166 * </li> 167 * <li> 168 * If used on a request bean method, uses the bean property name. 169 * 170 * <h5 class='figure'>Example:</h5> 171 * <p class='bcode w800'> 172 * <jk>public interface</jk> MyRequest { 173 * 174 * <jc>// Equivalent to @Header("Foo")</jc> 175 * <ja>@Header</ja> 176 * <ja>@BeanProperty</ja>(<js>"Foo"</js>) 177 * String getFoo(); 178 * } 179 * </p> 180 * </li> 181 * </ul> 182 */ 183 String name() default ""; 184 185 /** 186 * A synonym for {@link #name()}. 187 * 188 * <p> 189 * Allows you to use shortened notation if you're only specifying the name. 190 * 191 * <p> 192 * The following are completely equivalent ways of defining a header entry: 193 * <p class='bcode w800'> 194 * <jk>public</jk> Order placeOrder(<ja>@Header</ja>(name=<js>"api_key"</js>) String apiKey) {...} 195 * </p> 196 * <p class='bcode w800'> 197 * <jk>public</jk> Order placeOrder(<ja>@Header</ja>(<js>"api_key"</js>) String apiKey) {...} 198 * </p> 199 */ 200 String value() default ""; 201 202 /** 203 * <mk>description</mk> field of the {@doc SwaggerParameterObject}. 204 * 205 * <p> 206 * A brief description of the parameter. This could contain examples of use. 207 * 208 * <h5 class='section'>Used for:</h5> 209 * <ul class='spaced-list'> 210 * <li> 211 * Server-side generated Swagger documentation. 212 * </ul> 213 * 214 * <ul class='notes'> 215 * <li> 216 * The format is plain text. 217 * <br>Multiple lines are concatenated with newlines. 218 * <li> 219 * Supports {@doc DefaultRestSvlVariables} 220 * (e.g. <js>"$L{my.localized.variable}"</js>). 221 * </ul> 222 */ 223 String[] description() default {}; 224 225 /** 226 * <mk>required</mk> field of the {@doc SwaggerParameterObject}. 227 * 228 * <p> 229 * Determines whether the parameter is mandatory. 230 * 231 * <p> 232 * If validation fails during serialization or parsing, the part serializer/parser will throw a {@link SchemaValidationException}. 233 * <br>On the client-side, this gets converted to a <c>RestCallException</c> which is thrown before the connection is made. 234 * <br>On the server-side, this gets converted to a <c>BadRequest</c> (400). 235 * 236 * <h5 class='section'>Used for:</h5> 237 * <ul class='spaced-list'> 238 * <li> 239 * Server-side schema-based parsing validation. 240 * <li> 241 * Server-side generated Swagger documentation. 242 * <li> 243 * Client-side schema-based serializing validation. 244 * </ul> 245 */ 246 boolean required() default false; 247 248 //================================================================================================================= 249 // Attributes specific to parameters other than body 250 //================================================================================================================= 251 252 /** 253 * <mk>type</mk> field of the {@doc SwaggerParameterObject}. 254 * 255 * <p> 256 * The type of the parameter. 257 * 258 * <p> 259 * The possible values are: 260 * <ul class='spaced-list'> 261 * <li> 262 * <js>"string"</js> 263 * <br>Parameter must be a string or a POJO convertible from a string. 264 * <li> 265 * <js>"number"</js> 266 * <br>Parameter must be a number primitive or number object. 267 * <br>If parameter is <c>Object</c>, creates either a <c>Float</c> or <c>Double</c> depending on the size of the number. 268 * <li> 269 * <js>"integer"</js> 270 * <br>Parameter must be a integer/long primitive or integer/long object. 271 * <br>If parameter is <c>Object</c>, creates either a <c>Short</c>, <c>Integer</c>, or <c>Long</c> depending on the size of the number. 272 * <li> 273 * <js>"boolean"</js> 274 * <br>Parameter must be a boolean primitive or object. 275 * <li> 276 * <js>"array"</js> 277 * <br>Parameter must be an array or collection. 278 * <br>Elements must be strings or POJOs convertible from strings. 279 * <br>If parameter is <c>Object</c>, creates an {@link ObjectList}. 280 * <li> 281 * <js>"object"</js> 282 * <br>Parameter must be a map or bean. 283 * <br>If parameter is <c>Object</c>, creates an {@link ObjectMap}. 284 * <br>Note that this is an extension of the OpenAPI schema as Juneau allows for arbitrarily-complex POJOs to be serialized as HTTP parts. 285 * <li> 286 * <js>"file"</js> 287 * <br>This type is currently not supported. 288 * </ul> 289 * 290 * <p> 291 * Static strings are defined in {@link ParameterType}. 292 * 293 * <h5 class='section'>Used for:</h5> 294 * <ul class='spaced-list'> 295 * <li> 296 * Server-side schema-based parsing. 297 * <li> 298 * Server-side generated Swagger documentation. 299 * <li> 300 * Client-side schema-based serializing. 301 * </ul> 302 * 303 * <ul class='seealso'> 304 * <li class='extlink'>{@doc SwaggerDataTypes} 305 * </ul> 306 */ 307 String type() default ""; 308 309 /** 310 * <mk>format</mk> field of the {@doc SwaggerParameterObject}. 311 * 312 * <p> 313 * The extending format for the previously mentioned {@doc SwaggerParameterTypes parameter type}. 314 * 315 * <p> 316 * The possible values are: 317 * <ul class='spaced-list'> 318 * <li> 319 * <js>"int32"</js> - Signed 32 bits. 320 * <br>Only valid with type <js>"integer"</js>. 321 * <li> 322 * <js>"int64"</js> - Signed 64 bits. 323 * <br>Only valid with type <js>"integer"</js>. 324 * <li> 325 * <js>"float"</js> - 32-bit floating point number. 326 * <br>Only valid with type <js>"number"</js>. 327 * <li> 328 * <js>"double"</js> - 64-bit floating point number. 329 * <br>Only valid with type <js>"number"</js>. 330 * <li> 331 * <js>"byte"</js> - BASE-64 encoded characters. 332 * <br>Only valid with type <js>"string"</js>. 333 * <br>Parameters of type POJO convertible from string are converted after the string has been decoded. 334 * <li> 335 * <js>"binary"</js> - Hexadecimal encoded octets (e.g. <js>"00FF"</js>). 336 * <br>Only valid with type <js>"string"</js>. 337 * <br>Parameters of type POJO convertible from string are converted after the string has been decoded. 338 * <li> 339 * <js>"date"</js> - An <a href='http://xml2rfc.ietf.org/public/rfc/html/rfc3339.html#anchor14'>RFC3339 full-date</a>. 340 * <br>Only valid with type <js>"string"</js>. 341 * <li> 342 * <js>"date-time"</js> - An <a href='http://xml2rfc.ietf.org/public/rfc/html/rfc3339.html#anchor14'>RFC3339 date-time</a>. 343 * <br>Only valid with type <js>"string"</js>. 344 * <li> 345 * <js>"password"</js> - Used to hint UIs the input needs to be obscured. 346 * <br>This format does not affect the serialization or parsing of the parameter. 347 * <li> 348 * <js>"uon"</js> - UON notation (e.g. <js>"(foo=bar,baz=@(qux,123))"</js>). 349 * <br>Only valid with type <js>"object"</js>. 350 * <br>If not specified, then the input is interpreted as plain-text and is converted to a POJO directly. 351 * </ul> 352 * 353 * <p> 354 * Static strings are defined in {@link FormatType}. 355 * 356 * <h5 class='section'>Used for:</h5> 357 * <ul class='spaced-list'> 358 * <li> 359 * Server-side schema-based parsing. 360 * <li> 361 * Server-side generated Swagger documentation. 362 * <li> 363 * Client-side schema-based serializing. 364 * </ul> 365 * 366 * <ul class='seealso'> 367 * <li class='extlink'>{@doc SwaggerDataTypeFormats} 368 * </ul> 369 */ 370 String format() default ""; 371 372 373 /** 374 * <mk>allowEmptyValue</mk> field of the {@doc SwaggerParameterObject}. 375 * 376 * <p> 377 * Sets the ability to pass empty-valued heaver values. 378 * 379 * <h5 class='section'>Used for:</h5> 380 * <ul class='spaced-list'> 381 * <li> 382 * Server-side schema-based parsing validation. 383 * <li> 384 * Server-side generated Swagger documentation. 385 * <li> 386 * Client-side schema-based serializing validation. 387 * </ul> 388 * 389 * <p> 390 * <b>Note:</b> This is technically only valid for either query or formData parameters, but support is provided anyway for backwards compatability. 391 */ 392 boolean allowEmptyValue() default false; 393 394 /** 395 * <mk>items</mk> field of the {@doc SwaggerParameterObject}. 396 * 397 * <p> 398 * Describes the type of items in the array. 399 * 400 * <p> 401 * Required if <c>type</c> is <js>"array"</js>. 402 * <br>Can only be used if <c>type</c> is <js>"array"</js>. 403 * 404 * <h5 class='section'>Used for:</h5> 405 * <ul class='spaced-list'> 406 * <li> 407 * Server-side schema-based parsing and parsing validation. 408 * <li> 409 * Server-side generated Swagger documentation. 410 * <li> 411 * Client-side schema-based serializing and serializing validation. 412 * </ul> 413 */ 414 Items items() default @Items; 415 416 /** 417 * <mk>collectionFormat</mk> field of the {@doc SwaggerParameterObject}. 418 * 419 * <p> 420 * Determines the format of the array if <c>type</c> <js>"array"</js> is used. 421 * <br>Can only be used if <c>type</c> is <js>"array"</js>. 422 * 423 * <br>Possible values are: 424 * <ul class='spaced-list'> 425 * <li> 426 * <js>"csv"</js> (default) - Comma-separated values (e.g. <js>"foo,bar"</js>). 427 * <li> 428 * <js>"ssv"</js> - Space-separated values (e.g. <js>"foo bar"</js>). 429 * <li> 430 * <js>"tsv"</js> - Tab-separated values (e.g. <js>"foo\tbar"</js>). 431 * <li> 432 * <js>"pipes</js> - Pipe-separated values (e.g. <js>"foo|bar"</js>). 433 * <li> 434 * <js>"uon"</js> - UON notation (e.g. <js>"@(foo,bar)"</js>). 435 * <li> 436 * </ul> 437 * 438 * <p> 439 * Static strings are defined in {@link CollectionFormatType}. 440 * 441 * <h5 class='section'>Used for:</h5> 442 * <ul class='spaced-list'> 443 * <li> 444 * Server-side schema-based parsing. 445 * <li> 446 * Server-side generated Swagger documentation. 447 * <li> 448 * Client-side schema-based serializing. 449 * </ul> 450 * 451 * <p> 452 * Note that for collections/arrays parameters with POJO element types, the input is broken into a string array before being converted into POJO elements. 453 */ 454 String collectionFormat() default ""; 455 456 /** 457 * <mk>default</mk> field of the {@doc SwaggerParameterObject}. 458 * 459 * <p> 460 * Declares the value of the parameter that the server will use if none is provided, for example a "count" to control the number of results per page might default to 100 if not supplied by the client in the request. 461 * <br>(Note: "default" has no meaning for required parameters.) 462 * 463 * <p> 464 * Additionally, this value is used to create instances of POJOs that are then serialized as language-specific examples in the generated Swagger documentation 465 * if the examples are not defined in some other way. 466 * 467 * <p> 468 * The format of this value is a string. 469 * <br>Multiple lines are concatenated with newlines. 470 * 471 * <h5 class='section'>Examples:</h5> 472 * <p class='bcode w800'> 473 * <jk>public</jk> Order placeOrder( 474 * <ja>@Header</ja>(name=<js>"X-PetId"</js>, _default=<js>"100"</js>) <jk>long</jk> petId, 475 * <ja>@Header</ja>(name=<js>"X-AdditionalInfo"</js>, format=<js>"uon"</js>, _default=<js>"(rushOrder=false)"</js>) AdditionalInfo additionalInfo, 476 * <ja>@Header</ja>(name=<js>"X-Flags"</js>, collectionFormat=<js>"uon"</js>, _default=<js>"@(new-customer)"</js>) String[] flags 477 * ) {...} 478 * </p> 479 * 480 * <h5 class='section'>Used for:</h5> 481 * <ul class='spaced-list'> 482 * <li> 483 * Server-side schema-based parsing. 484 * <li> 485 * Server-side generated Swagger documentation. 486 * <li> 487 * Client-side schema-based serializing. 488 * </ul> 489 */ 490 String[] _default() default {}; 491 492 /** 493 * <mk>maximum</mk> field of the {@doc SwaggerParameterObject}. 494 * 495 * <p> 496 * Defines the maximum value for a parameter of numeric types. 497 * <br>The value must be a valid JSON number. 498 * 499 * <p> 500 * If validation fails during serialization or parsing, the part serializer/parser will throw a {@link SchemaValidationException}. 501 * <br>On the client-side, this gets converted to a <c>RestCallException</c> which is thrown before the connection is made. 502 * <br>On the server-side, this gets converted to a <c>BadRequest</c> (400). 503 * 504 * <p> 505 * Only allowed for the following types: <js>"integer"</js>, <js>"number"</js>. 506 * 507 * <h5 class='section'>Used for:</h5> 508 * <ul class='spaced-list'> 509 * <li> 510 * Server-side schema-based parsing validation. 511 * <li> 512 * Server-side generated Swagger documentation. 513 * <li> 514 * Client-side schema-based serializing validation. 515 * </ul> 516 */ 517 String maximum() default ""; 518 519 /** 520 * <mk>exclusiveMaximum</mk> field of the {@doc SwaggerParameterObject}. 521 * 522 * <p> 523 * Defines whether the maximum is matched exclusively. 524 * 525 * <p> 526 * If validation fails during serialization or parsing, the part serializer/parser will throw a {@link SchemaValidationException}. 527 * <br>On the client-side, this gets converted to a <c>RestCallException</c> which is thrown before the connection is made. 528 * <br>On the server-side, this gets converted to a <c>BadRequest</c> (400). 529 * 530 * <p> 531 * Only allowed for the following types: <js>"integer"</js>, <js>"number"</js>. 532 * <br>If <jk>true</jk>, must be accompanied with <c>maximum</c>. 533 * 534 * <h5 class='section'>Used for:</h5> 535 * <ul class='spaced-list'> 536 * <li> 537 * Server-side schema-based parsing validation. 538 * <li> 539 * Server-side generated Swagger documentation. 540 * <li> 541 * Client-side schema-based serializing validation. 542 * </ul> 543 */ 544 boolean exclusiveMaximum() default false; 545 546 /** 547 * <mk>minimum</mk> field of the {@doc SwaggerParameterObject}. 548 * 549 * <p> 550 * Defines the minimum value for a parameter of numeric types. 551 * <br>The value must be a valid JSON number. 552 * 553 * <p> 554 * If validation fails during serialization or parsing, the part serializer/parser will throw a {@link SchemaValidationException}. 555 * <br>On the client-side, this gets converted to a <c>RestCallException</c> which is thrown before the connection is made. 556 * <br>On the server-side, this gets converted to a <c>BadRequest</c> (400). 557 * 558 * <p> 559 * Only allowed for the following types: <js>"integer"</js>, <js>"number"</js>. 560 * 561 * <h5 class='section'>Used for:</h5> 562 * <ul class='spaced-list'> 563 * <li> 564 * Server-side schema-based parsing validation. 565 * <li> 566 * Server-side generated Swagger documentation. 567 * <li> 568 * Client-side schema-based serializing validation. 569 * </ul> 570 */ 571 String minimum() default ""; 572 573 /** 574 * <mk>exclusiveMinimum</mk> field of the {@doc SwaggerParameterObject}. 575 * 576 * <p> 577 * Defines whether the minimum is matched exclusively. 578 * 579 * <p> 580 * If validation fails during serialization or parsing, the part serializer/parser will throw a {@link SchemaValidationException}. 581 * <br>On the client-side, this gets converted to a <c>RestCallException</c> which is thrown before the connection is made. 582 * <br>On the server-side, this gets converted to a <c>BadRequest</c> (400). 583 * 584 * <p> 585 * Only allowed for the following types: <js>"integer"</js>, <js>"number"</js>. 586 * <br>If <jk>true</jk>, must be accompanied with <c>minimum</c>. 587 * 588 * <h5 class='section'>Used for:</h5> 589 * <ul class='spaced-list'> 590 * <li> 591 * Server-side schema-based parsing validation. 592 * <li> 593 * Server-side generated Swagger documentation. 594 * <li> 595 * Client-side schema-based serializing validation. 596 * </ul> 597 */ 598 boolean exclusiveMinimum() default false; 599 600 /** 601 * <mk>maxLength</mk> field of the {@doc SwaggerParameterObject}. 602 * 603 * <p> 604 * A string instance is valid against this keyword if its length is less than, or equal to, the value of this keyword. 605 * <br>The length of a string instance is defined as the number of its characters as defined by <a href='https://tools.ietf.org/html/rfc4627'>RFC 4627</a>. 606 * <br>The value <c>-1</c> is always ignored. 607 * 608 * <p> 609 * If validation fails during serialization or parsing, the part serializer/parser will throw a {@link SchemaValidationException}. 610 * <br>On the client-side, this gets converted to a <c>RestCallException</c> which is thrown before the connection is made. 611 * <br>On the server-side, this gets converted to a <c>BadRequest</c> (400). 612 * 613 * <p> 614 * Only allowed for the following types: <js>"string"</js>. 615 * 616 * <h5 class='section'>Used for:</h5> 617 * <ul class='spaced-list'> 618 * <li> 619 * Server-side schema-based parsing validation. 620 * <li> 621 * Server-side generated Swagger documentation. 622 * <li> 623 * Client-side schema-based serializing validation. 624 * </ul> 625 */ 626 long maxLength() default -1; 627 628 /** 629 * <mk>minLength</mk> field of the {@doc SwaggerParameterObject}. 630 * 631 * <p> 632 * A string instance is valid against this keyword if its length is greater than, or equal to, the value of this keyword. 633 * <br>The length of a string instance is defined as the number of its characters as defined by <a href='https://tools.ietf.org/html/rfc4627'>RFC 4627</a>. 634 * <br>The value <c>-1</c> is always ignored. 635 * 636 * <p> 637 * If validation fails during serialization or parsing, the part serializer/parser will throw a {@link SchemaValidationException}. 638 * <br>On the client-side, this gets converted to a <c>RestCallException</c> which is thrown before the connection is made. 639 * <br>On the server-side, this gets converted to a <c>BadRequest</c> (400). 640 * 641 * <p> 642 * Only allowed for the following types: <js>"string"</js>. 643 * 644 * <h5 class='section'>Used for:</h5> 645 * <ul class='spaced-list'> 646 * <li> 647 * Server-side schema-based parsing validation. 648 * <li> 649 * Server-side generated Swagger documentation. 650 * <li> 651 * Client-side schema-based serializing validation. 652 * </ul> 653 */ 654 long minLength() default -1; 655 656 /** 657 * <mk>pattern</mk> field of the {@doc SwaggerParameterObject}. 658 * 659 * <p> 660 * A string input is valid if it matches the specified regular expression pattern. 661 * 662 * <p> 663 * If validation fails during serialization or parsing, the part serializer/parser will throw a {@link SchemaValidationException}. 664 * <br>On the client-side, this gets converted to a <c>RestCallException</c> which is thrown before the connection is made. 665 * <br>On the server-side, this gets converted to a <c>BadRequest</c> (400). 666 * 667 * <p> 668 * Only allowed for the following types: <js>"string"</js>. 669 * 670 * <h5 class='section'>Used for:</h5> 671 * <ul class='spaced-list'> 672 * <li> 673 * Server-side schema-based parsing validation. 674 * <li> 675 * Server-side generated Swagger documentation. 676 * <li> 677 * Client-side schema-based serializing validation. 678 * </ul> 679 */ 680 String pattern() default ""; 681 682 /** 683 * <mk>maxItems</mk> field of the {@doc SwaggerParameterObject}. 684 * 685 * <p> 686 * An array or collection is valid if its size is less than, or equal to, the value of this keyword. 687 * 688 * <p> 689 * If validation fails during serialization or parsing, the part serializer/parser will throw a {@link SchemaValidationException}. 690 * <br>On the client-side, this gets converted to a <c>RestCallException</c> which is thrown before the connection is made. 691 * <br>On the server-side, this gets converted to a <c>BadRequest</c> (400). 692 * 693 * <p> 694 * Only allowed for the following types: <js>"array"</js>. 695 * 696 * <h5 class='section'>Used for:</h5> 697 * <ul class='spaced-list'> 698 * <li> 699 * Server-side schema-based parsing validation. 700 * <li> 701 * Server-side generated Swagger documentation. 702 * <li> 703 * Client-side schema-based serializing validation. 704 * </ul> 705 */ 706 long maxItems() default -1; 707 708 /** 709 * <mk>minItems</mk> field of the {@doc SwaggerParameterObject}. 710 * 711 * <p> 712 * An array or collection is valid if its size is greater than, or equal to, the value of this keyword. 713 * 714 * <p> 715 * If validation fails during serialization or parsing, the part serializer/parser will throw a {@link SchemaValidationException}. 716 * <br>On the client-side, this gets converted to a <c>RestCallException</c> which is thrown before the connection is made. 717 * <br>On the server-side, this gets converted to a <c>BadRequest</c> (400). 718 * 719 * <p> 720 * Only allowed for the following types: <js>"array"</js>. 721 * 722 * <h5 class='section'>Used for:</h5> 723 * <ul class='spaced-list'> 724 * <li> 725 * Server-side schema-based parsing validation. 726 * <li> 727 * Server-side generated Swagger documentation. 728 * <li> 729 * Client-side schema-based serializing validation. 730 * </ul> 731 */ 732 long minItems() default -1; 733 734 /** 735 * <mk>uniqueItems</mk> field of the {@doc SwaggerParameterObject}. 736 * 737 * <p> 738 * If <jk>true</jk> the input validates successfully if all of its elements are unique. 739 * 740 * <p> 741 * If validation fails during serialization or parsing, the part serializer/parser will throw a {@link SchemaValidationException}. 742 * <br>On the client-side, this gets converted to a <c>RestCallException</c> which is thrown before the connection is made. 743 * <br>On the server-side, this gets converted to a <c>BadRequest</c> (400). 744 * 745 * <p> 746 * If the parameter type is a subclass of {@link Set}, this validation is skipped (since a set can only contain unique items anyway). 747 * <br>Otherwise, the collection or array is checked for duplicate items. 748 * 749 * <p> 750 * Only allowed for the following types: <js>"array"</js>. 751 * 752 * <h5 class='section'>Used for:</h5> 753 * <ul class='spaced-list'> 754 * <li> 755 * Server-side schema-based parsing validation. 756 * <li> 757 * Server-side generated Swagger documentation. 758 * <li> 759 * Client-side schema-based serializing validation. 760 * </ul> 761 */ 762 boolean uniqueItems() default false; 763 764 /** 765 * <mk>enum</mk> field of the {@doc SwaggerParameterObject}. 766 * 767 * <p> 768 * If specified, the input validates successfully if it is equal to one of the elements in this array. 769 * 770 * <p> 771 * If validation fails during serialization or parsing, the part serializer/parser will throw a {@link SchemaValidationException}. 772 * <br>On the client-side, this gets converted to a <c>RestCallException</c> which is thrown before the connection is made. 773 * <br>On the server-side, this gets converted to a <c>BadRequest</c> (400). 774 * 775 * <p> 776 * The format is a {@doc SimpleJson} array or comma-delimited list. 777 * <br>Multiple lines are concatenated with newlines. 778 * 779 * <h5 class='section'>Examples:</h5> 780 * <p class='bcode w800'> 781 * <jc>// Comma-delimited list</jc> 782 * <jk>public</jk> Collection<Pet> findPetsByStatus( 783 * <ja>@Header</ja>( 784 * name=<js>"X-Status"</js>, 785 * _enum=<js>"AVAILABLE,PENDING,SOLD"</js>, 786 * ) PetStatus status 787 * ) {...} 788 * </p> 789 * <p class='bcode w800'> 790 * <jc>// JSON array</jc> 791 * <jk>public</jk> Collection<Pet> findPetsByStatus( 792 * <ja>@Header</ja>( 793 * name=<js>"X-Status"</js>, 794 * _enum=<js>"['AVAILABLE','PENDING','SOLD']"</js>, 795 * ) PetStatus status 796 * ) {...} 797 * </p> 798 * 799 * <h5 class='section'>Used for:</h5> 800 * <ul class='spaced-list'> 801 * <li> 802 * Server-side schema-based parsing validation. 803 * <li> 804 * Server-side generated Swagger documentation. 805 * <li> 806 * Client-side schema-based serializing validation. 807 * </ul> 808 */ 809 String[] _enum() default {}; 810 811 /** 812 * <mk>multipleOf</mk> field of the {@doc SwaggerParameterObject}. 813 * 814 * <p> 815 * A numeric instance is valid if the result of the division of the instance by this keyword's value is an integer. 816 * <br>The value must be a valid JSON number. 817 * 818 * <p> 819 * If validation fails during serialization or parsing, the part serializer/parser will throw a {@link SchemaValidationException}. 820 * <br>On the client-side, this gets converted to a <c>RestCallException</c> which is thrown before the connection is made. 821 * <br>On the server-side, this gets converted to a <c>BadRequest</c> (400). 822 * 823 * <p> 824 * Only allowed for the following types: <js>"integer"</js>, <js>"number"</js>. 825 * 826 * <h5 class='section'>Used for:</h5> 827 * <ul class='spaced-list'> 828 * <li> 829 * Server-side schema-based parsing validation. 830 * <li> 831 * Server-side generated Swagger documentation. 832 * <li> 833 * Client-side schema-based serializing validation. 834 * </ul> 835 */ 836 String multipleOf() default ""; 837 838 //================================================================================================================= 839 // Other 840 //================================================================================================================= 841 842 /** 843 * A serialized example of the parameter. 844 * 845 * <p> 846 * This attribute defines a representation of the value that is used by <c>BasicRestInfoProvider</c> to construct 847 * an example of parameter. 848 * 849 * <h5 class='section'>Example:</h5> 850 * <p class='bcode w800'> 851 * <ja>@Header</ja>( 852 * name=<js>"Status"</js>, 853 * type=<js>"array"</js>, 854 * collectionFormat=<js>"csv"</js>, 855 * example=<js>"AVALIABLE,PENDING"</js> 856 * ) 857 * PetStatus[] status 858 * </p> 859 * 860 * <p> 861 * If not specified, Juneau will automatically create examples from sample POJOs serialized using the registered {@link HttpPartSerializer}. 862 * <br> 863 * 864 * </p> 865 * <h5 class='section'>Used for:</h5> 866 * <ul class='spaced-list'> 867 * <li> 868 * Server-side generated Swagger documentation. 869 * </ul> 870 * 871 * <ul class='seealso'> 872 * <li class='ja'>{@link Example} 873 * <li class='jc'>{@link BeanContext} 874 * <ul> 875 * <li class='jf'>{@link BeanContext#BEAN_examples BEAN_examples} 876 * </ul> 877 * <li class='jc'>{@link JsonSchemaSerializer} 878 * <ul> 879 * <li class='jf'>{@link JsonSchemaGenerator#JSONSCHEMA_addExamplesTo JSONSCHEMA_addExamplesTo} 880 * <li class='jf'>{@link JsonSchemaGenerator#JSONSCHEMA_allowNestedExamples JSONSCHEMA_allowNestedExamples} 881 * </ul> 882 * </ul> 883 * 884 * <ul class='notes'> 885 * <li> 886 * The format is a {@doc SimpleJson} object or plain text string. 887 * <br>Multiple lines are concatenated with newlines. 888 * <li> 889 * Supports {@doc DefaultRestSvlVariables} 890 * (e.g. <js>"$L{my.localized.variable}"</js>). 891 * </ul> 892 */ 893 String[] example() default {}; 894 895 /** 896 * Free-form value for the {@doc SwaggerParameterObject}. 897 * 898 * <p> 899 * This is a JSON object that makes up the swagger information for this field. 900 * 901 * <p> 902 * The following are completely equivalent ways of defining the swagger description of the request header: 903 * <p class='bcode w800'> 904 * <jc>// Normal</jc> 905 * <ja>@Header</ja>( 906 * name=<js>"api_key"</js>, 907 * description=<js>"Security API key"</js>, 908 * required=<jk>true</jk>, 909 * example=<js>"foobar"</js> 910 * ) 911 * </p> 912 * <p class='bcode w800'> 913 * <jc>// Free-form</jc> 914 * <ja>@Header</ja>( 915 * name=<js>"api_key"</js>, 916 * api={ 917 * <js>"description: 'Security API key',"</js>, 918 * <js>"required: true,"</js>, 919 * <js>"example: 'foobar'"</js> 920 * } 921 * ) 922 * </p> 923 * <p class='bcode w800'> 924 * <jc>// Free-form with variables</jc> 925 * <ja>@Header</ja>( 926 * name=<js>"api_key"</js>, 927 * api=<js>"$L{apiKeySwagger}"</js> 928 * ) 929 * </p> 930 * <p class='bcode w800'> 931 * <mc>// Contents of MyResource.properties</mc> 932 * <mk>apiKeySwagger</mk> = <mv>{ description: "Security API key", required: true, example: "foobar" }</mv> 933 * </p> 934 * 935 * <p> 936 * The reasons why you may want to use this field include: 937 * <ul> 938 * <li>You want to pull in the entire Swagger JSON definition for this field from an external source such as a properties file. 939 * <li>You want to add extra fields to the Swagger documentation that are not officially part of the Swagger specification. 940 * </ul> 941 * 942 * <h5 class='section'>Used for:</h5> 943 * <ul class='spaced-list'> 944 * <li> 945 * Server-side generated Swagger documentation. 946 * </ul> 947 * 948 * <ul class='notes'> 949 * <li> 950 * 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. 951 * <li> 952 * The format is a {@doc SimpleJson} object. 953 * <li> 954 * Automatic validation is NOT performed on input based on attributes in this value. 955 * <li> 956 * The leading/trailing <c>{ }</c> characters are optional. 957 * <br>The following two example are considered equivalent: 958 * <p class='bcode w800'> 959 * <ja>@Header</ja>(api=<js>"{required: true}"</js>) 960 * </p> 961 * <p class='bcode w800'> 962 * <ja>@Header</ja>(api=<js>"required: true"</js>) 963 * </p> 964 * <li> 965 * Multiple lines are concatenated with newlines so that you can format the value to be readable. 966 * <li> 967 * Supports {@doc DefaultRestSvlVariables} 968 * (e.g. <js>"$L{my.localized.variable}"</js>). 969 * <li> 970 * Values defined in this field supersede values pulled from the Swagger JSON file and are superseded by individual values defined on this annotation. 971 * </ul> 972 */ 973 String[] api() default {}; 974}