org.springframework.http.converter

Class FormHttpMessageConverter

  • java.lang.Object
    • org.springframework.http.converter.FormHttpMessageConverter
  • All Implemented Interfaces:
    HttpMessageConverter<MultiValueMap<java.lang.String,?>>
    Direct Known Subclasses:
    AllEncompassingFormHttpMessageConverter


    public class FormHttpMessageConverter
    extends java.lang.Object
    implements HttpMessageConverter<MultiValueMap<java.lang.String,?>>
    Implementation of HttpMessageConverter to read and write 'normal' HTML forms and also to write (but not read) multipart data (e.g. file uploads).

    In other words, this converter can read and write the "application/x-www-form-urlencoded" media type as MultiValueMap<String, String> and it can also write (but not read) the "multipart/form-data" media type as MultiValueMap<String, Object>.

    When writing multipart data, this converter uses other HttpMessageConverters to write the respective MIME parts. By default, basic converters are registered (for Strings and Resources). These can be overridden through the partConverters property.

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

     RestTemplate template = new RestTemplate();
     // AllEncompassingFormHttpMessageConverter is configured by default
    
     MultiValueMap<String, String> form = new LinkedMultiValueMap<>();
     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<>();
     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 org.apache.commons.httpclient.methods.multipart.MultipartRequestEntity.

    Since:
    3.0
    Author:
    Arjen Poutsma, Rossen Stoyanchev, Juergen Hoeller
    See Also:
    AllEncompassingFormHttpMessageConverter, MultiValueMap
    • Field Summary

      Fields 
      Modifier and Type Field and Description
      static java.nio.charset.Charset DEFAULT_CHARSET
      The default charset used by the converter.
    • Field Detail

      • DEFAULT_CHARSET

        public static final java.nio.charset.Charset DEFAULT_CHARSET
        The default charset used by the converter.
    • Constructor Detail

      • FormHttpMessageConverter

        public FormHttpMessageConverter()
    • Method Detail

      • setSupportedMediaTypes

        public void setSupportedMediaTypes(java.util.List<MediaType> supportedMediaTypes)
        Set the list of MediaType objects supported by this converter.
      • setPartConverters

        public void setPartConverters(java.util.List<HttpMessageConverter<?>> partConverters)
        Set the message body converters to use. These converters are used to convert objects to MIME parts.
      • addPartConverter

        public void addPartConverter(HttpMessageConverter<?> partConverter)
        Add a message body converter. Such a converter is used to convert objects to MIME parts.
      • setCharset

        public void setCharset(@Nullable
                               java.nio.charset.Charset charset)
        Set the default character set to use for reading and writing form data when the request or response Content-Type header does not explicitly specify it.

        As of 4.3, this is also used as the default charset for the conversion of text bodies in a multipart request.

        As of 5.0 this is also used for part headers including "Content-Disposition" (and its filename parameter) unless (the mutually exclusive) setMultipartCharset(java.nio.charset.Charset) is also set, in which case part headers are encoded as ASCII and filename is encoded with the "encoded-word" syntax from RFC 2047.

        By default this is set to "UTF-8".

      • setMultipartCharset

        public void setMultipartCharset(java.nio.charset.Charset charset)
        Set the character set to use when writing multipart data to encode file names. Encoding is based on the "encoded-word" syntax defined in RFC 2047 and relies on MimeUtility from "javax.mail".

        As of 5.0 by default part headers, including Content-Disposition (and its filename parameter) will be encoded based on the setting of setCharset(Charset) or UTF-8 by default.

        Since:
        4.1.1
        See Also:
        Encoded-Word
      • canRead

        public boolean canRead(java.lang.Class<?> clazz,
                               @Nullable
                               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<java.lang.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(java.lang.Class<?> clazz,
                                @Nullable
                                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<java.lang.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
      • write

        public void write(MultiValueMap<java.lang.String,?> map,
                          @Nullable
                          MediaType contentType,
                          HttpOutputMessage outputMessage)
                   throws java.io.IOException,
                          HttpMessageNotWritableException
        Description copied from interface: HttpMessageConverter
        Write an given object to the given output message.
        Specified by:
        write in interface HttpMessageConverter<MultiValueMap<java.lang.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:
        java.io.IOException - in case of I/O errors
        HttpMessageNotWritableException - in case of conversion errors
      • serializeForm

        protected java.lang.String serializeForm(MultiValueMap<java.lang.String,java.lang.String> formData,
                                                 java.nio.charset.Charset charset)
      • getHttpEntity

        protected HttpEntity<?> getHttpEntity(java.lang.Object part)
        Return an HttpEntity for the given part Object.
        Parameters:
        part - the part to return an HttpEntity for
        Returns:
        the part Object itself it is an HttpEntity, or a newly built HttpEntity wrapper for that part
      • getFilename

        @Nullable
        protected java.lang.String getFilename(java.lang.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