juneau-doc/docs/Topics/09.juneau-rest-client/01.RestProxies/04.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.
 ***************************************************************************************************************************/
 -->

@FormData

<p>
	The {@link oaj.http.annotation.FormData @FormData} annotation can be applied to arguments of <ja>@RemoteMethod</ja>-annotated methods
	to denote that they are form-data parameters on the request.
</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#collectionFormat() collectionFormat} - How collections of items are formatted.
		<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#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#serializer() serializer}- Override the part serializer.
		<li class='jf'>{@link oaj.http.annotation.FormData#skipIfEmpty() skipIfEmpty}- Don't add if value is null or empty.
		<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.
	</ul>
</ul>

<h5 class='figure'>Example:</h5>
<p class='bpcode w800'>
	<ja>@Remote</ja>(path=<js>"/myproxy"</js>)
	<jk>public interface</jk> MyProxy {

		<jc>// Explicit names specified for form data parameters.</jc>
		<ja>@RemoteMethod</ja>
		String postParameters(
			<ja>@FormData</ja>(<js>"foo"</js>)</ja> String foo,
			<ja>@FormData</ja>(<js>"bar"</js>)</ja> MyPojo pojo
		);

		<jc>// Multiple values pulled from a NameValuePairs object.</jc>
		<jc>// Name "*" is inferred.</jc>
		<ja>@RemoteMethod</ja>
		String postNameValuePairs(<ja>@FormData</ja> NameValuePairs nameValuePairs);

		<jc>// Multiple values pulled from a Map.</jc>
		<ja>@RemoteMethod</ja>
		String postMap(<ja>@FormData</ja> Map&lt;String,Object&gt; map);

		<jc>// Multiple values pulled from a bean.</jc>
		<ja>@RemoteMethod</ja>
		String postBean(<ja>@FormData</ja> MyBean bean);

		<jc>// An entire form-data HTTP body as a String.</jc>
		<ja>@RemoteMethod</ja>
		String postString(<ja>@FormData</ja> String string);

		<jc>// An entire form-data HTTP body as a Reader.</jc>
		<ja>@RemoteMethod</ja>
		String postReader(<ja>@FormData</ja> Reader reader);
	}
</p>

<p>
	Single-part arguments (i.e. those with name != <js>"*"</js>) can be any of the following types:
</p>
<ul class='spaced-list'>
	<li>
		Any serializable POJO - Converted to a string using the {@link oaj.httppart.HttpPartSerializer} registered with the
		<c>RestClient</c> ({@link oaj.oapi.OpenApiSerializer} by default) or associated via the {@link oaj.http.annotation.FormData#serializer() @FormData(serializer)} annotation.
</ul>
<p>
	Multi-part arguments (i.e. those with name == <js>"*"</js> or empty) can be any of the following types:
</p>
<ul class='spaced-list'>
	<li>
		{@link java.io.Reader} - Raw contents of {@code Reader} will be serialized to remote resource.
	<li>
		{@link java.io.InputStream} - Raw contents of {@code InputStream} will be serialized to remote resource.
	<li>
		<c>NameValuePairs</c> - Converted to a URL-encoded FORM post.
	<li>
		<c>Map</c> - Converted to key-value pairs.
			<br>Values serialized using the registered {@link oaj.httppart.HttpPartSerializer} ({@link oaj.oapi.OpenApiSerializer} by default).
	<li>
		Bean - Converted to key-value pairs.
			<br>Values serialized using the registered {@link oaj.httppart.HttpPartSerializer} ({@link oaj.oapi.OpenApiSerializer} by default).
	<li>
		<c>CharSequence</c> - Used directly as am <js>"application/x-www-form-urlencoded"</js> entity.
</ul>
<p>
	See the link below for information about supported data types in OpenAPI serialization.
</p>

<ul class='seealso'>
	<li class='link'>{@doc juneau-marshall.OpenApiDetails.Serializers}
</ul>