juneau-doc/docs/Topics/06.juneau-rest-server/10.HttpPartAnnotations/02.FormData.html

<!--
/***************************************************************************************************************************
 * Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements.  See the NOTICE file
 * distributed with this work for additional information regarding copyright ownership.  The ASF licenses this file
 * to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance
 * with the License.  You may obtain a copy of the License at
 *  
 *  http://www.apache.org/licenses/LICENSE-2.0
 *  
 * Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an
 * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.  See the License for the
 * specific language governing permissions and limitations under the License.
 ***************************************************************************************************************************/
 -->

{8.1.0-updated} 
@FormData

<p>
	The {@link oaj.http.annotation.FormData @FormData} annotation is used to retrieve request form post entries.
</p>
<ul class='javatree'>
	<li class='ja'>{@link oaj.http.annotation.FormData}
	<ul>
		<li class='jf'>{@link oaj.http.annotation.FormData#_default() _default} - Default value if not present.
		<li class='jf'>{@link oaj.http.annotation.FormData#_enum() _enum} - Input validation.  Must match one of the values.
		<li class='jf'>{@link oaj.http.annotation.FormData#allowEmptyValue() allowEmptyValue} - Input validation.  Allow empty value.
		<li class='jf'>{@link oaj.http.annotation.FormData#api() api()} - Free-form Swagger JSON.
		<li class='jf'>{@link oaj.http.annotation.FormData#collectionFormat() collectionFormat} - How collections of items are formatted.
		<li class='jf'>{@link oaj.http.annotation.FormData#description() description} - Description.
		<li class='jf'>{@link oaj.http.annotation.FormData#example() example()} - Serialized example.
		<li class='jf'>{@link oaj.http.annotation.FormData#exclusiveMaximum() exclusiveMaximum} - Input validation.  Whether maximum is exclusive.
		<li class='jf'>{@link oaj.http.annotation.FormData#exclusiveMinimum() exclusiveMinimum} - Input validation.  Whether minimum is exclusive.
		<li class='jf'>{@link oaj.http.annotation.FormData#format() format} - The schema type format. 
		<li class='jf'>{@link oaj.http.annotation.FormData#items() items} - The schema of items in a collection.
		<li class='jf'>{@link oaj.http.annotation.FormData#maximum() maximum} - Input validation.  Maximum numeric value. 
		<li class='jf'>{@link oaj.http.annotation.FormData#maxItems() maxItems} - Input validation.  Maximum number of items in a collection.
		<li class='jf'>{@link oaj.http.annotation.FormData#maxLength() maxLength} - Input validation.  Maximum length of a string.
		<li class='jf'>{@link oaj.http.annotation.FormData#minimum() minimum} - Input validation.  Minimum numeric value.
		<li class='jf'>{@link oaj.http.annotation.FormData#minItems() minItems} - Input validation.  Minimum number of items in a collection.
		<li class='jf'>{@link oaj.http.annotation.FormData#minLength() minLength} - Input validation.  Minimum length of a string.
		<li class='jf'>{@link oaj.http.annotation.FormData#multipleOf() multipleOf} - Input validation.  Number must be a multiple of.
		<li class='jf'>{@link oaj.http.annotation.FormData#name() name} - Form data entry name.
		<li class='jf'>{@link oaj.http.annotation.FormData#parser() parser} - Override the part parser.
		<li class='jf'>{@link oaj.http.annotation.FormData#pattern() pattern} - Input validation.  Must match regular expression.
		<li class='jf'>{@link oaj.http.annotation.FormData#required() required} - Input validation.  Form data entry must be present.
		<li class='jf'>{@link oaj.http.annotation.FormData#type() type} - The schema type.
		<li class='jf'>{@link oaj.http.annotation.FormData#uniqueItems() uniqueItems} - Input validation. Collections must contain unique items only.
		<li class='jf'>{@link oaj.http.annotation.FormData#value() value} - Free-form Swagger JSON.
	</ul>
</ul>

<p>
	The most typical scenario is to simply use the <c>value</c> field to define form data parameter names:
</p>
<h5 class='figure'>Example:</h5>
<p class='bpcode w800'>	
	<ja>@RestMethod</ja>(name=<jsf>POST</jsf>)
	<jk>public void</jk> doPost(
		<ja>@FormData</ja>(<js>"p1"</js>) <jk>int</jk> p1, 
		<ja>@FormData</ja>(<js>"p2"</js>) String p2, 
		<ja>@FormData</ja>(<js>"p3"</js>) UUID p3) {...}
</p>
<p>
	This is functionally equivalent to the following code:
</p>
<p class='bpcode w800'>
	<ja>@RestMethod</ja>(name=<jsf>POST</jsf>)
	<jk>public void</jk> doPost(RestRequest req) {
		RequestFormData fd = req.getFormData();
		<jk>int</jk> p1 = fd.get(<js>"p1"</js>, 0, <jk>int</jk>.<jk>class</jk>);
		String p2 = fd.get(<js>"p2"</js>, String.<jk>class</jk>);
		UUID p3 = fd.get(<js>"p3"</js>, UUID.<jk>class</jk>);
	}
</p>

<p>
	The special name <js>"*"</js> (or blank) can be used to represent all values.
	When used, the data type must be a <c>Map</c> or bean.
</p>
<h5 class='figure'>Examples:</h5>
<p class='bpcode w800'>
	<jc>// Multiple values passed as a map.</jc>
	<ja>@RestMethod</ja>(name=<jsf>POST</jsf>)
	<jk>public void</jk> doPost(<ja>@FormData</ja>(<js>"*"</js>) Map&lt;String,Object&gt; map) {...}
</p>
<p class='bpcode w800'>
	<jc>// Same, but name "*" is inferred.</jc>
	<ja>@RestMethod</ja>(name=<jsf>POST</jsf>)
	<jk>public void</jk> doPost(<ja>@FormData</ja> Map&lt;String,Object&gt; map) {...}
</p>
<p class='bpcode w800'>
	<jc>// Multiple values passed as a bean.</jc>
	<ja>@RestMethod</ja>(name=<jsf>POST</jsf>)
	<jk>public void</jk> doPost(<ja>@FormData</ja> MyBean bean) {...}
</p>

<p>
	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.
</p>
<p>
	For example, the following shows how a pipe-delimited list of comma-delimited numbers (e.g. <js>"1,2,3|4,5,6|7,8,9"</js>) can be converted to a 2-dimensional array of <c>Longs</c>:
</p>
<p class='bpcode w800'>
	<ja>@RestMethod</ja>(method=<js>"POST"</js>, path=<js>"/testFormData"</js>)	
	<jk>public void</jk> testFormData(
		<ja>@FormData</ja>(
			name=<js>"formDataParamName"</js>,
			collectionFormat=<js>"pipes"</js>,
			items=<ja>@SubItems</ja>(
				collectionFormat=<js>"csv"</js>,
				type=<js>"integer"</js>, 
				format=<js>"int64"</js>,
				minimum=<js>"0"</js>,
				maximum=<js>"100"</js>
				minLength=1,
				maxLength=10
			),
			minLength=1,
			maxLength=10
		)
		Long[][] formDataParameter
	) {...}
</p>
<p>
	Input will be converted based on the types and formats defined in the schema definition.
	Input validations such as <c>minLength/maxLength</c> that don't match the input will result in automatic <c>400 Bad Request</c> responses.
</p>
<p>
	For more information about valid parameter types, see {@doc juneau-marshall.OpenApiDetails.Parsers OpenAPI Parsers}
</p>

<p>
	The <ja>@FormData</ja> 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.
</p>
<h5 class='figure'>Examples:</h5>
<p class='bpcode w800'>
	<jc>// Normal</jc>
	<ja>@FormData</ja>(
		name=<js>"name"</js>,
		description=<js>"Pet name"</js>,
		required=<jk>true</jk>,
		example=<js>"Doggie"</js>
	)
</p>
<p class='bpcode w800'>
	<jc>// Free-form</jc>
	<jc>// Note the extra field</jc>
	<ja>@FormData</ja>(
		name=<js>"name"</js>,
		api={
			<js>"description: 'Pet name',"</js>,
			<js>"required: true,"</js>,
			<js>"example: 'Doggie',"</js>
			<js>"x-extra: 'extra field'"</js>
		}
	)
</p>
<p>
	{@doc DefaultRestSvlVariables} (e.g. "$L{my.localized.variable}")
	are supported on annotation fields.
</p>
<h5 class='figure'>Example:</h5>
<p class='bpcode w800'>
	<ja>@FormData</ja>(
		description=<js>"$L{PetNameDescription}"</js>
	)
</p>

<div class='warn'>
	This annotation should not be combined with the {@link oaj.http.annotation.Body @Body} annotation or {@link oajr.RestRequest#getBody()} method
	for <c>application/x-www-form-urlencoded POST</c> posts, since it will trigger the underlying servlet
	API to parse the body content as key-value pairs resulting in empty content.
	<br>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.
</div>

<div class='warn'>
	If using this annotation on a Spring bean, note that you are likely to encounter issues when using on parameterized
	types such as <code>List&lt;MyBean&gt;</code>.  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. <code>List</code>).  Under these circumstances, you are likely to get <code>ClassCastExceptions</code>
	when trying to access generalized <code>ObjectMaps</code> as beans.  The best solution to this issue is to either
	specify the parameter as a bean array (e.g. <code>MyBean[]</code>) or declare the method as final so that CGLIB
	will not try to recompile it.
</div>

<ul class='seealso'>
	<li class='jc'>{@link oajr.RequestFormData}
	<li class='link'>{@doc juneau-rest-server.OpenApiSchemaPartParsing}
</ul>