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.

PartDescription
StringPartThe 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.
FilePartThe 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 .