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, XmlAwareFormHttpMessageConverter

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();  // 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 org.apache.commons.httpclient.methods.multipart.MultipartRequestEntity.

Since:

3.0

Author:

Arjen Poutsma, Rossen Stoyanchev

See Also:

MultiValueMap

Nested Class Summary

Nested Classes

Modifier and Type	Class and Description
private static class	FormHttpMessageConverter.MimeDelegate Inner class to avoid a hard dependency on the JavaMail API.
private static class	FormHttpMessageConverter.MultipartHttpOutputMessage Implementation of HttpOutputMessage used to write a MIME multipart.

Field Summary

Fields

Modifier and Type	Field and Description
private java.nio.charset.Charset	charset
static java.nio.charset.Charset	DEFAULT_CHARSET
private java.nio.charset.Charset	multipartCharset
private java.util.List<HttpMessageConverter<?>>	partConverters
private java.util.List<MediaType>	supportedMediaTypes

Constructor Summary

Constructors

Constructor and Description
FormHttpMessageConverter()

Method Summary

Modifier and Type	Method and Description
void	addPartConverter(HttpMessageConverter<?> partConverter) Add a message body converter.
boolean	canRead(java.lang.Class<?> clazz, MediaType mediaType) Indicates whether the given class can be read by this converter.
boolean	canWrite(java.lang.Class<?> clazz, MediaType mediaType) Indicates whether the given class can be written by this converter.
protected byte[]	generateMultipartBoundary() Generate a multipart boundary.
protected java.lang.String	getFilename(java.lang.Object part) Return the filename of the given multipart part.
protected HttpEntity<?>	getHttpEntity(java.lang.Object part) Return an HttpEntity for the given part Object.
java.util.List<MediaType>	getSupportedMediaTypes() Return the list of MediaType objects supported by this converter.
private boolean	isMultipart(MultiValueMap<java.lang.String,?> map, MediaType contentType)
MultiValueMap<java.lang.String,java.lang.String>	read(java.lang.Class<? extends MultiValueMap<java.lang.String,?>> clazz, HttpInputMessage inputMessage) Read an object of the given type form the given input message, and returns it.
void	setCharset(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.
void	setMultipartCharset(java.nio.charset.Charset multipartCharset) Set the character set to use when writing multipart data to encode file names.
void	setPartConverters(java.util.List<HttpMessageConverter<?>> partConverters) Set the message body converters to use.
void	setSupportedMediaTypes(java.util.List<MediaType> supportedMediaTypes) Set the list of MediaType objects supported by this converter.
void	write(MultiValueMap<java.lang.String,?> map, MediaType contentType, HttpOutputMessage outputMessage) Write an given object to the given output message.
private void	writeBoundary(java.io.OutputStream os, byte[] boundary)
private static void	writeEnd(java.io.OutputStream os, byte[] boundary)
private void	writeForm(MultiValueMap<java.lang.String,java.lang.String> form, MediaType contentType, HttpOutputMessage outputMessage)
private void	writeMultipart(MultiValueMap<java.lang.String,java.lang.Object> parts, HttpOutputMessage outputMessage)
private static void	writeNewLine(java.io.OutputStream os)
private void	writePart(java.lang.String name, HttpEntity<?> partEntity, java.io.OutputStream os)
private void	writeParts(java.io.OutputStream os, MultiValueMap<java.lang.String,java.lang.Object> parts, byte[] boundary)

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

DEFAULT_CHARSET

public static final java.nio.charset.Charset DEFAULT_CHARSET

charset

private java.nio.charset.Charset charset

multipartCharset

private java.nio.charset.Charset multipartCharset

supportedMediaTypes

private java.util.List<MediaType> supportedMediaTypes

partConverters

private java.util.List<HttpMessageConverter<?>> partConverters

Constructor Detail

FormHttpMessageConverter

public FormHttpMessageConverter()

Method Detail

setCharset

public void setCharset(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.

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

setMultipartCharset

public void setMultipartCharset(java.nio.charset.Charset multipartCharset)

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".

If not set file names will be encoded as US-ASCII.

Parameters:

multipartCharset - the charset to use

Since:

4.1.1

See Also:

Encoded-Word

setSupportedMediaTypes

public void setSupportedMediaTypes(java.util.List<MediaType> supportedMediaTypes)

Set the list of MediaType objects supported by this converter.

getSupportedMediaTypes

public java.util.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<java.lang.String,?>>

Returns:

the list of supported media types

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.

canRead

public boolean canRead(java.lang.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<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,
                        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

read

public MultiValueMap<java.lang.String,java.lang.String> read(java.lang.Class<? extends MultiValueMap<java.lang.String,?>> clazz,
                                                             HttpInputMessage inputMessage)
                                                      throws java.io.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<java.lang.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:

java.io.IOException - in case of I/O errors

HttpMessageNotReadableException - in case of conversion errors

write

public void write(MultiValueMap<java.lang.String,?> map,
                  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

isMultipart

private boolean isMultipart(MultiValueMap<java.lang.String,?> map,
                            MediaType contentType)

writeForm

private void writeForm(MultiValueMap<java.lang.String,java.lang.String> form,
                       MediaType contentType,
                       HttpOutputMessage outputMessage)
                throws java.io.IOException

Throws:

java.io.IOException

writeMultipart

private void writeMultipart(MultiValueMap<java.lang.String,java.lang.Object> parts,
                            HttpOutputMessage outputMessage)
                     throws java.io.IOException

Throws:

java.io.IOException

writeParts

private void writeParts(java.io.OutputStream os,
                        MultiValueMap<java.lang.String,java.lang.Object> parts,
                        byte[] boundary)
                 throws java.io.IOException

Throws:

java.io.IOException

writePart

private void writePart(java.lang.String name,
                       HttpEntity<?> partEntity,
                       java.io.OutputStream os)
                throws java.io.IOException

Throws:

java.io.IOException

generateMultipartBoundary

protected byte[] generateMultipartBoundary()

Generate a multipart boundary.

This implementation delegates to MimeTypeUtils.generateMultipartBoundary().

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

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

writeBoundary

private void writeBoundary(java.io.OutputStream os,
                           byte[] boundary)
                    throws java.io.IOException

Throws:

java.io.IOException

writeEnd

private static void writeEnd(java.io.OutputStream os,
                             byte[] boundary)
                      throws java.io.IOException

Throws:

java.io.IOException

writeNewLine

private static void writeNewLine(java.io.OutputStream os)
                          throws java.io.IOException

Throws:

java.io.IOException