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