The multipart post method is a different request body format for a POST method. The media-type multipart/form-data follows the rules of all multipart MIME data streams as outlined in RFC 1521. It is intended for use in returning the data that comes about from filling out a form, particularly when the form requires binary data to be uploaded such as the contents of a file.
Like for the standard POST method, there are two main steps to using the multipart post method, setting the request data and retrieving the response data.
The request data is specified by adding parameters to the method,
these are defined by the
org.apache.commons.httpclient.methods.multipart.Part class
and it's various subclasses. A description of each of these is below.
| Part | Description |
|---|---|
| StringPart | The string part is a simple part that takes a name for the part and the value of the part as a string. This is typically used for standard form elements such as a text area within a multipart form. |
| FilePart | The file part is actually a very generic type of part that can
contain any type of data and specify a name, content type and charset
for the data. In it's simplest form, it takes just a name and a File
object and uploads the contents of the file, however it can also be
passed a PartSource object to upload. See the part
source section below for more information. |
The PartSource interface provides a generic container
for providing data to the FilePart class. There are two concrete
implementations of PartSource provided with HttpClient (described
below) but you can also provide your own implementation easily. The
input for the multipart post could come from anywhere, perhaps it's
being received from another server or process, and all that the
PartSource class needs to be able to do is provide the length of the
data that will be provided, an input stream to retrieve the data from
and a file name (or some name identifying the data).
The two concrete implementations of PartSource are FilePartSource and ByteArrayPartSource. FilePartSource simply takes a File to upload whereas ByteArrayPartSource allows for the case where the data has been cached in memory and takes a file name and a byte array to upload.
The most common problem people run into with multipart uploads is that the length of the data must be known before hand. If the length of the data can not be determined in advance, it needs to be cached either in memory or to a file and then uploaded using either ByteArrayPartSource or FilePartSource. The HTTP specification does not allow for POST data to be of an unknown length.