FormHttpMessageConverter (Spring Framework 3.2.1.RELEASE API)
Date: 2013-01-24

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
    Modifier and Type | Method and Description
    --- | ---
    `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