Introduction
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.
Typical Usage
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. |
Part Sources
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.
Common Problems
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.
RFC Section
The multipart form data uses the POST method from the HTTP standard
which is defined in section 8.3 of RFC1945 and similarly
redefined for HTTP 1.1 in section 9.5 of RFC2616.
The multipart/form-data MIME type used to format the body of the
request is defined in RFC1867.
