1. Overview

In this tutorial, we will illustrate how to do a multipart upload operation using HttpClient 5.

If you want to dig deeper and learn other cool things you can do with the HttpClient, head over to the main HttpClient tutorial.

2. Using the AddPart Method

Let’s start by looking at the MultipartEntityBuilder object to add parts to an Http entity which will then be uploaded via a POST operation.

This is a generic method to add parts to an HttpEntity representing the form.

Example 2.1. – Uploading a Form with Two Text Parts and a File

final File file = new File(url.getPath());
final FileBody fileBody = new FileBody(file, ContentType.DEFAULT_BINARY);
final StringBody stringBody1 = new StringBody("This is message 1", ContentType.MULTIPART_FORM_DATA);
final StringBody stringBody2 = new StringBody("This is message 2", ContentType.MULTIPART_FORM_DATA);

final MultipartEntityBuilder builder = MultipartEntityBuilder.create();
builder.setMode(HttpMultipartMode.LEGACY);
builder.addPart("file", fileBody);
builder.addPart("text1", stringBody1);
builder.addPart("text2", stringBody2);
final HttpEntity entity = builder.build();

post.setEntity(entity);
try(CloseableHttpClient client = HttpClientBuilder.create()
 .build()) {

 client.execute(post, response -> { 
 //do something with response
 });
}

Note that we’re instantiating the File object by also specifying the ContentType value to be used by the server.

Also, note that the addPart method has two arguments, acting like key/value pairs for the form. These are only relevant if the server side actually expects and uses parameter names – otherwise, they’re ignored.

3. Using the addBinaryBody and addTextBody Methods

A more direct way to create a multipart entity is to use the addBinaryBody and AddTextBody methods. These methods work for uploading text, files, character arrays, and InputStream objects. Let’s illustrate how with simple examples.

Example 3.1. – Uploading Text and a Text File Part

final File file = new File(url.getPath());
final String message = "This is a multipart post";
final MultipartEntityBuilder builder = MultipartEntityBuilder.create();
builder.setMode(HttpMultipartMode.LEGACY);
builder.addBinaryBody("file", file, ContentType.DEFAULT_BINARY, TEXTFILENAME);
builder.addTextBody("text", message, ContentType.DEFAULT_BINARY);
final HttpEntity entity = builder.build();
post.setEntity(entity);

try(CloseableHttpClient client = HttpClientBuilder.create()
 .build()) {

 client.execute(post, response -> { 
 //do something with response
 });
}

Note that the FileBody and StringBody objects are not needed here.

Also important, most servers do not check the ContentType of the text body, so the addTextBody method may omit the ContentType value.

The addBinaryBody API accepts a ContentType – but it is also possible to create the entity just from a binary body and the name of the form parameter holding the file. As stated in the previous section, some servers will not recognize the file if the ContentType value is not specified.

Next, we’ll add a zip file as an InputStream, while the image file will be added as a File object:

Example 3.2. – Uploading aZip File, an Image File, and a Text Part

final URL url = Thread.currentThread()
 .getContextClassLoader()
 .getResource("uploads/" + ZIPFILENAME);
final URL url2 = Thread.currentThread()
 .getContextClassLoader()
 .getResource("uploads/" + IMAGEFILENAME);
final InputStream inputStream = new FileInputStream(url.getPath());
final File file = new File(url2.getPath());
final String message = "This is a multipart post";
final MultipartEntityBuilder builder = MultipartEntityBuilder.create();
builder.setMode(HttpMultipartMode.LEGACY);
builder.addBinaryBody("file", file, ContentType.DEFAULT_BINARY, IMAGEFILENAME);
builder.addBinaryBody("upstream", inputStream, ContentType.create("application/zip"), ZIPFILENAME);
builder.addTextBody("text", message, ContentType.TEXT_PLAIN);
final HttpEntity entity = builder.build();
post.setEntity(entity);

try(CloseableHttpClient client = HttpClientBuilder.create()
 .build()) {

 client.execute(post, response -> { 
 //do something with response
 });
}

Note that the ContentType value can be created on the fly, as in the example above for the zip file.

Finally, not all servers acknowledge InputStream parts. The server we instantiated in the first line of the code recognizes InputStreams.

Let’s now look at another example where addBinaryBody is working directly with a byte array:

Example 3.3. – Uploading a Byte Array and Text

final String message = "This is a multipart post";
final byte[] bytes = "binary code".getBytes();
final MultipartEntityBuilder builder = MultipartEntityBuilder.create();
builder.setMode(HttpMultipartMode.LEGACY);
builder.addBinaryBody("file", bytes, ContentType.DEFAULT_BINARY, TEXTFILENAME);
builder.addTextBody("text", message, ContentType.TEXT_PLAIN);
final HttpEntity entity = builder.build();
post.setEntity(entity);

try(CloseableHttpClient client = HttpClientBuilder.create()
 .build()) {

 client.execute(post, response -> { 
 //do something with response
 });
}

Notice the ContentType – which is now specifying binary data.

4. Conclusion

This article has presented the MultipartEntityBuilder as a flexible object which offers multiple API choices to create a multipart form.

The examples have also shown how to use the HttpClient to upload a HttpEntity that is similar to a form entity.