@FormData
The {@link oaj.http.annotation.FormData @FormData} annotation is used to retrieve request form post entries.
- {@link oaj.http.annotation.FormData}
- {@link oaj.http.annotation.FormData#_default() _default} - Default value if not present.
- {@link oaj.http.annotation.FormData#_enum() _enum} - Input validation. Must match one of the values.
- {@link oaj.http.annotation.FormData#allowEmptyValue() allowEmptyValue} - Input validation. Allow empty value.
- {@link oaj.http.annotation.FormData#api() api()} - Free-form Swagger JSON.
- {@link oaj.http.annotation.FormData#collectionFormat() collectionFormat} - How collections of items are formatted.
- {@link oaj.http.annotation.FormData#description() description} - Description.
- {@link oaj.http.annotation.FormData#example() example()} - Serialized example.
- {@link oaj.http.annotation.FormData#exclusiveMaximum() exclusiveMaximum} - Input validation. Whether maximum is exclusive.
- {@link oaj.http.annotation.FormData#exclusiveMinimum() exclusiveMinimum} - Input validation. Whether minimum is exclusive.
- {@link oaj.http.annotation.FormData#format() format} - The schema type format.
- {@link oaj.http.annotation.FormData#items() items} - The schema of items in a collection.
- {@link oaj.http.annotation.FormData#maximum() maximum} - Input validation. Maximum numeric value.
- {@link oaj.http.annotation.FormData#maxItems() maxItems} - Input validation. Maximum number of items in a collection.
- {@link oaj.http.annotation.FormData#maxLength() maxLength} - Input validation. Maximum length of a string.
- {@link oaj.http.annotation.FormData#minimum() minimum} - Input validation. Minimum numeric value.
- {@link oaj.http.annotation.FormData#minItems() minItems} - Input validation. Minimum number of items in a collection.
- {@link oaj.http.annotation.FormData#minLength() minLength} - Input validation. Minimum length of a string.
- {@link oaj.http.annotation.FormData#multipleOf() multipleOf} - Input validation. Number must be a multiple of.
- {@link oaj.http.annotation.FormData#name() name} - Form data entry name.
- {@link oaj.http.annotation.FormData#parser() parser} - Override the part parser.
- {@link oaj.http.annotation.FormData#pattern() pattern} - Input validation. Must match regular expression.
- {@link oaj.http.annotation.FormData#required() required} - Input validation. Form data entry must be present.
- {@link oaj.http.annotation.FormData#type() type} - The schema type.
- {@link oaj.http.annotation.FormData#uniqueItems() uniqueItems} - Input validation. Collections must contain unique items only.
- {@link oaj.http.annotation.FormData#value() value} - Free-form Swagger JSON.
The most typical scenario is to simply use the value field to define form data parameter names:
@RestMethod(name=POST)
public void doPost(
@FormData("p1") int p1,
@FormData("p2") String p2,
@FormData("p3") UUID p3) {...}
This is functionally equivalent to the following code:
@RestMethod(name=POST)
public void doPost(RestRequest req) {
RequestFormData fd = req.getFormData();
int p1 = fd.get("p1", 0, int.class);
String p2 = fd.get("p2", String.class);
UUID p3 = fd.get("p3", UUID.class);
}
The special name "*" (or blank) can be used to represent all values.
When used, the data type must be a Map or bean.
// Multiple values passed as a map.
@RestMethod(name=POST)
public void doPost(@FormData("*") Map<String,Object> map) {...}
// Same, but name "*" is inferred.
@RestMethod(name=POST)
public void doPost(@FormData Map<String,Object> map) {...}
// Multiple values passed as a bean.
@RestMethod(name=POST)
public void doPost(@FormData MyBean bean) {...}
The registered {@link oajr.RestContext#REST_partParser REST_partParser} is used to convert strings
to POJOs and controls what POJO types are supported.
By default, this is the {@link oaj.oapi.OpenApiParser} which supports the standard Swagger-based rules for parsing.
For example, the following shows how a pipe-delimited list of comma-delimited numbers (e.g. "1,2,3|4,5,6|7,8,9") can be converted to a 2-dimensional array of Longs:
@RestMethod(method="POST", path="/testFormData")
public void testFormData(
@FormData(
name="formDataParamName",
collectionFormat="pipes",
items=@SubItems(
collectionFormat="csv",
type="integer",
format="int64",
minimum="0",
maximum="100"
minLength=1,
maxLength=10
),
minLength=1,
maxLength=10
)
Long[][] formDataParameter
) {...}
Input will be converted based on the types and formats defined in the schema definition.
Input validations such as minLength/maxLength that don't match the input will result in automatic 400 Bad Request responses.
For more information about valid parameter types, see {@doc juneau-marshall.OpenApiDetails.Parsers OpenAPI Parsers}
The @FormData annotation is also used for supplying swagger information about the HTTP part.
This information is used to populate the auto-generated Swagger documentation and UI.
// Normal
@FormData(
name="name",
description="Pet name",
required=true,
example="Doggie"
)
// Free-form
// Note the extra field
@FormData(
name="name",
api={
"description: 'Pet name',",
"required: true,",
"example: 'Doggie',"
"x-extra: 'extra field'"
}
)
{@doc DefaultRestSvlVariables} (e.g. "$L{my.localized.variable}")
are supported on annotation fields.
@FormData(
description="$L{PetNameDescription}"
)
This annotation should not be combined with the {@link oaj.http.annotation.Body @Body} annotation or {@link oajr.RestRequest#getBody()} method
for application/x-www-form-urlencoded POST posts, since it will trigger the underlying servlet
API to parse the body content as key-value pairs resulting in empty content.
The {@link oaj.http.annotation.Query @Query} annotation can be used to retrieve a URL parameter in the URL string without triggering the
servlet to drain the body content.
If using this annotation on a Spring bean, note that you are likely to encounter issues when using on parameterized
types such as List<MyBean>
. This is due to the fact that Spring uses CGLIB to recompile classes
at runtime, and CGLIB was written before generics were introduced into Java and is a virtually-unsupported library.
Therefore, parameterized types will often be stripped from class definitions and replaced with unparameterized types
(e.g. List
). Under these circumstances, you are likely to get ClassCastExceptions
when trying to access generalized ObjectMaps
as beans. The best solution to this issue is to either
specify the parameter as a bean array (e.g. MyBean[]
) or declare the method as final so that CGLIB
will not try to recompile it.
- {@link oajr.RequestFormData}
- {@doc juneau-rest-server.OpenApiSchemaPartParsing}