Package org.springframework.http.converter

Class FormHttpMessageConverter

  • All Implemented Interfaces:
    HttpMessageConverter<MultiValueMap<String,​?>>
    Direct Known Subclasses:
    AllEncompassingFormHttpMessageConverter
    public class FormHttpMessageConverter
extends Object
implements HttpMessageConverter<MultiValueMap<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" and "multipart/mixed" media types as MultiValueMap<String, Object>.

    Multipart Data

    By default, "multipart/form-data" is used as the content type when writing multipart data. As of Spring Framework 5.2 it is also possible to write multipart data using other multipart subtypes such as "multipart/mixed" and "multipart/related", as long as the multipart subtype is registered as a supported media typeand the desired multipart subtype is specified as the content type when writing the multipart data. Note that "multipart/mixed" is registered as a supported media type by default.

    When writing multipart data, this converter uses other HttpMessageConverters to write the respective MIME parts. By default, basic converters are registered for byte array, String, and Resource. These can be overridden via setPartConverters(java.util.List<org.springframework.http.converter.HttpMessageConverter<?>>) or augmented via addPartConverter(org.springframework.http.converter.HttpMessageConverter<?>).

    Examples

    The following snippet shows how to submit an HTML form using the "multipart/form-data" content type. 

     RestTemplate restTemplate = new RestTemplate();
 // AllEncompassingFormHttpMessageConverter is configured by default

 MultiValueMap<String, Object> form = new LinkedMultiValueMap<>();
 form.add("field 1", "value 1");
 form.add("field 2", "value 2");
 form.add("field 2", "value 3");
 form.add("field 3", 4);  // non-String form values supported as of 5.1.4

 restTemplate.postForLocation("https://example.com/myForm", form);

    The following snippet shows how to do a file upload using the "multipart/form-data" content type. 

     MultiValueMap<String, Object> parts = new LinkedMultiValueMap<>();
 parts.add("field 1", "value 1");
 parts.add("file", new ClassPathResource("myFile.jpg"));

 restTemplate.postForLocation("https://example.com/myFileUpload", parts);

    The following snippet shows how to do a file upload using the "multipart/mixed" content type. 

     MultiValueMap<String, Object> parts = new LinkedMultiValueMap<>();
 parts.add("field 1", "value 1");
 parts.add("file", new ClassPathResource("myFile.jpg"));

 HttpHeaders requestHeaders = new HttpHeaders();
 requestHeaders.setContentType(MediaType.MULTIPART_MIXED);

 restTemplate.postForLocation("https://example.com/myFileUpload",
     new HttpEntity<>(parts, requestHeaders));

    The following snippet shows how to do a file upload using the "multipart/related" content type. 

     MediaType multipartRelated = new MediaType("multipart", "related");

 restTemplate.getMessageConverters().stream()
     .filter(FormHttpMessageConverter.class::isInstance)
     .map(FormHttpMessageConverter.class::cast)
     .findFirst()
     .orElseThrow(() -> new IllegalStateException("Failed to find FormHttpMessageConverter"))
     .addSupportedMediaTypes(multipartRelated);

 MultiValueMap<String, Object> parts = new LinkedMultiValueMap<>();
 parts.add("field 1", "value 1");
 parts.add("file", new ClassPathResource("myFile.jpg"));

 HttpHeaders requestHeaders = new HttpHeaders();
 requestHeaders.setContentType(multipartRelated);

 restTemplate.postForLocation("https://example.com/myFileUpload",
     new HttpEntity<>(parts, requestHeaders));

    Miscellaneous

    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, Sam Brannen
    See Also:
    AllEncompassingFormHttpMessageConverter, MultiValueMap