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