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