org.springframework.http.converter
Class FormHttpMessageConverter

java.lang.Object
  extended by org.springframework.http.converter.FormHttpMessageConverter
All Implemented Interfaces:
HttpMessageConverter<MultiValueMap<String,?>>
Direct Known Subclasses:
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
FormHttpMessageConverter()
           
 
Method Summary
 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 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

addPartConverter

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


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.


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

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.

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.

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