Package org.springframework.http.converter

Class FormHttpMessageConverter

java.lang.Object
org.springframework.http.converter.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. 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 type and 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. 

 RestClient restClient = RestClient.create();
 // 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

 ResponseEntity<Void> response = restClient.post()
   .uri("https://example.com/myForm")
   .contentType(MULTIPART_FORM_DATA)
   .body(form)
   .retrieve()
   .toBodilessEntity();

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"));

 ResponseEntity<Void> response = restClient.post()
   .uri("https://example.com/myForm")
   .contentType(MULTIPART_FORM_DATA)
   .body(parts)
   .retrieve()
   .toBodilessEntity();

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"));

 ResponseEntity<Void> response = restClient.post()
   .uri("https://example.com/myForm")
   .contentType(MULTIPART_MIXED)
   .body(form)
   .retrieve()
   .toBodilessEntity();

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

 restClient = restClient.mutate()
   .messageConverters(l -> l.stream()
    .filter(FormHttpMessageConverter.class::isInstance)
     .map(FormHttpMessageConverter.class::cast)
     .findFirst()
     .orElseThrow(() -> new IllegalStateException("Failed to find FormHttpMessageConverter"))
     .addSupportedMediaTypes(MULTIPART_RELATED);

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

 ResponseEntity<Void> response = restClient.post()
   .uri("https://example.com/myForm")
   .contentType(MULTIPART_RELATED)
   .body(form)
   .retrieve()
   .toBodilessEntity();

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: