org.springframework.http.converter

## Class FormHttpMessageConverter

- java.lang.Object
- - org.springframework.http.converter.FormHttpMessageConverter

All Implemented Interfaces:
  HttpMessageConverter<MultiValueMap<String,?>>

Direct Known Subclasses:
  AllEncompassingFormHttpMessageConverter, XmlAwareFormHttpMessageConverter

    public class FormHttpMessageConverter
    extends Object
    implements HttpMessageConverter<MultiValueMap<String,?>>

Implementation of `HttpMessageConverter` that can handle form data, including multipart form data (i.e. file uploads).

This converter can write the `application/x-www-form-urlencoded` and `multipart/form-data` media types, and read the `application/x-www-form-urlencoded`) media type (but not `multipart/form-data`).

In other words, this converter can read and write 'normal' HTML forms (as `MultiValueMap<String, String>`), and it can write multipart form (as `MultiValueMap<String, Object>`. When writing multipart, this converter uses other `HttpMessageConverters` to write the respective MIME parts. By default, basic converters are registered (supporting `Strings` and `Resources`, for instance); these can be overridden by setting the `partConverters` property.

For example, the following snippet shows how to submit an HTML form:

     RestTemplate template =
     new RestTemplate(); // FormHttpMessageConverter is configured by default MultiValueMap<String, String> form =
     new LinkedMultiValueMap<String, String>(); form.add("field 1", "value 1"); form.add("field 2", "value 2");
     form.add("field 2", "value 3"); template.postForLocation("http://example.com/myForm", form);

The following snippet shows how to do a file upload:

     MultiValueMap<String, Object> parts = new
     LinkedMultiValueMap<String, Object>(); parts.add("field 1", "value 1"); parts.add("file", new
     ClassPathResource("myFile.jpg")); template.postForLocation("http://example.com/myFileUpload", parts);

Some methods in this class were inspired by `MultipartRequestEntity`.

Since:
  3.0
Author:
  Arjen Poutsma
See Also:
  `MultiValueMap`

### Constructor Summary

Constructors
Constructor and Description
`FormHttpMessageConverter()`

### Method Summary

Methods
`void` `addPartConverter(HttpMessageConverter<?> partConverter)` Add a message body converter.
`boolean` `canRead(Class<?> clazz, MediaType mediaType)` Indicates whether the given class can be read by this converter.
`boolean` `canWrite(Class<?> clazz, MediaType mediaType)` Indicates whether the given class can be written by this converter.
`protected byte[]` `generateMultipartBoundary()` Generate a multipart boundary.
`protected String` `getFilename(Object part)` Return the filename of the given multipart part.
`List<MediaType>` `getSupportedMediaTypes()` Return the list of `MediaType` objects supported by this converter.
`MultiValueMap<String,String>` `read(Class<? extends MultiValueMap<String,?>> clazz, HttpInputMessage inputMessage)` Read an object of the given type form the given input message, and returns it.
`void` `setCharset(Charset charset)` Sets the character set used for writing form data.
`void` `setPartConverters(List<HttpMessageConverter<?>> partConverters)` Set the message body converters to use.
`void` `setSupportedMediaTypes(List<MediaType> supportedMediaTypes)` Set the list of `MediaType` objects supported by this converter.
`void` `write(MultiValueMap<String,?> map, MediaType contentType, HttpOutputMessage outputMessage)` Write an given object to the given output message.

### Methods inherited from class java.lang.Object

`clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

### Constructor Detail

#### FormHttpMessageConverter

    public FormHttpMessageConverter()

### Method Detail

#### setPartConverters

    public final void setPartConverters(List<HttpMessageConverter<?>> partConverters)

Set the message body converters to use. These converters are used to convert objects to MIME parts.

#### addPartConverter

    public final void addPartConverter(HttpMessageConverter<?> partConverter)

Add a message body converter. Such a converters is used to convert objects to MIME parts.

#### setCharset

    public void setCharset(Charset charset)

Sets the character set used for writing form data.

#### canRead

    public boolean canRead(Class<?> clazz,
                  MediaType mediaType)

Description copied from interface: `HttpMessageConverter`
Indicates whether the given class can be read by this converter.

Specified by:
  `canRead` in interface `HttpMessageConverter<MultiValueMap<String,?>>`
Parameters:
  `clazz` - the class to test for readability
  `mediaType` - the media type to read, can be `null` if not specified. Typically the value of a `Content-Type` header.
Returns:
  `true` if readable; `false` otherwise

#### canWrite

    public boolean canWrite(Class<?> clazz,
                   MediaType mediaType)

Description copied from interface: `HttpMessageConverter`
Indicates whether the given class can be written by this converter.

Specified by:
  `canWrite` in interface `HttpMessageConverter<MultiValueMap<String,?>>`
Parameters:
  `clazz` - the class to test for writability
  `mediaType` - the media type to write, can be `null` if not specified. Typically the value of an `Accept` header.
Returns:
  `true` if writable; `false` otherwise

#### setSupportedMediaTypes

    public void setSupportedMediaTypes(List<MediaType> supportedMediaTypes)

Set the list of `MediaType` objects supported by this converter.

#### getSupportedMediaTypes

    public List<MediaType> getSupportedMediaTypes()

Description copied from interface: `HttpMessageConverter`
Return the list of `MediaType` objects supported by this converter.

Specified by:
  `getSupportedMediaTypes` in interface `HttpMessageConverter<MultiValueMap<String,?>>`
Returns:
  the list of supported media types

#### read

    public MultiValueMap<String,String> read(Class<? extends MultiValueMap<String,?>> clazz,
                                    HttpInputMessage inputMessage)
                                      throws IOException,
                                             HttpMessageNotReadableException

Description copied from interface: `HttpMessageConverter`
Read an object of the given type form the given input message, and returns it.

Specified by:
  `read` in interface `HttpMessageConverter<MultiValueMap<String,?>>`
Parameters:
  `clazz` - the type of object to return. This type must have previously been passed to the `canRead` method of this interface, which must have returned `true`.
  `inputMessage` - the HTTP input message to read from
Returns:
  the converted object
Throws:
  `IOException` - in case of I/O errors
  `HttpMessageNotReadableException` - in case of conversion errors

#### write

    public void write(MultiValueMap<String,?> map,
             MediaType contentType,
             HttpOutputMessage outputMessage)
               throws IOException,
                      HttpMessageNotWritableException

Description copied from interface: `HttpMessageConverter`
Write an given object to the given output message.

Specified by:
  `write` in interface `HttpMessageConverter<MultiValueMap<String,?>>`
Parameters:
  `map` - the object to write to the output message. The type of this object must have previously been passed to the `canWrite` method of this interface, which must have returned `true`.
  `contentType` - the content type to use when writing. May be `null` to indicate that the default content type of the converter must be used. If not `null`, this media type must have previously been passed to the `canWrite` method of this interface, which must have returned `true`.
  `outputMessage` - the message to write to
Throws:
  `IOException` - in case of I/O errors
  `HttpMessageNotWritableException` - in case of conversion errors

#### generateMultipartBoundary

    protected byte[] generateMultipartBoundary()

Generate a multipart boundary.

The default implementation returns a random boundary. Can be overridden in subclasses.

#### getFilename

    protected String getFilename(Object part)

Return the filename of the given multipart part. This value will be used for the `Content-Disposition` header.

The default implementation returns `Resource.getFilename()` if the part is a `Resource`, and `null` in other cases. Can be overridden in subclasses.

Parameters:
  `part` - the part to determine the file name for
Returns:
  the filename, or `null` if not known