Multipart Upload with Apache HttpClient – 用Apache HttpClient进行多部分上传

1. Overview

1.概述

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

在本教程中，我们将说明如何使用HttpClient进行多部分上传操作。

We’ll use http://echo.200please.com as a test server because it’s public and it accepts most types of content.

我们将使用http://echo.200please.com作为测试服务器，因为它是公共的，而且它接受大多数类型的内容。

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

如果你想更深入地挖掘和了解你可以用HttpClient做的其他酷事–请到主要的HttpClient教程.

2. Using the AddPart Method

2.使用AddPart方法

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.

让我们先看看MultipartEntityBuilder对象，以向一个Http实体添加部件，然后通过POST操作上传。

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

这是一个通用方法，用于向代表表单的HttpEntity添加部件。

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

例2.1.- 上传一个带有两个文本部分和一个文件的表单。

File file = new File(textFileName);
HttpPost post = new HttpPost("http://echo.200please.com");
FileBody fileBody = new FileBody(file, ContentType.DEFAULT_BINARY);
StringBody stringBody1 = new StringBody("Message 1", ContentType.MULTIPART_FORM_DATA);
StringBody stringBody2 = new StringBody("Message 2", ContentType.MULTIPART_FORM_DATA);
// 
MultipartEntityBuilder builder = MultipartEntityBuilder.create();
builder.setMode(HttpMultipartMode.BROWSER_COMPATIBLE);
builder.addPart("upfile", fileBody);
builder.addPart("text1", stringBody1);
builder.addPart("text2", stringBody2);
HttpEntity entity = builder.build();
//
post.setEntity(entity);
HttpResponse response = client.execute(post);

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

请注意，我们在实例化文件对象时，还指定了将被服务器使用的ContentType值。

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 simply ignored.

另外，注意addPart方法有两个参数，就像表单的key/value对。这些参数只有在服务器端实际期望并使用参数名时才有意义–否则，它们会被简单地忽略。

3. Using the addBinaryBody and addTextBody Methods

3.使用addBinaryBody和addTextBody方法

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.

创建多部分实体的一个更直接的方法是使用 addBinaryBody和AddTextBody方法。这些方法可用于上传文本、文件、字符数组和InputStream对象。让我们用简单的例子来说明一下。

Example 3.1. – Uploading Text and a Text File Part

例3.1.- 上传文本和一个文本文件部分。

HttpPost post = new HttpPost("http://echo.200please.com");
File file = new File(textFileName);
String message = "This is a multipart post";
MultipartEntityBuilder builder = MultipartEntityBuilder.create();
builder.setMode(HttpMultipartMode.BROWSER_COMPATIBLE);
builder.addBinaryBody("upfile", file, ContentType.DEFAULT_BINARY, textFileName);
builder.addTextBody("text", message, ContentType.DEFAULT_BINARY);
// 
HttpEntity entity = builder.build();
post.setEntity(entity);
HttpResponse response = client.execute(post);

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

注意，这里不需要FileBody和StringBody对象。

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

同样重要的是，大多数服务器不检查文本体的ContentType，所以addTextBody方法可能省略了ContentType值。

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.

addBinaryBody API接受一个ContentType–但也可以仅从一个二进制体和容纳文件的表单参数名称来创建实体。正如上一节所述，如果没有指定ContentType值，一些服务器将无法识别该文件。

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

接下来，我们将以InputStream,的形式添加一个zip文件，而图像文件将以File的形式添加。

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

例3.2.- 上传一个Zip文件、一个图像文件和一个文本部分。

HttpPost post = new HttpPost("http://echo.200please.com");
InputStream inputStream = new FileInputStream(zipFileName);
File file = new File(imageFileName);
String message = "This is a multipart post";
MultipartEntityBuilder builder = MultipartEntityBuilder.create();         
builder.setMode(HttpMultipartMode.BROWSER_COMPATIBLE);
builder.addBinaryBody
  ("upfile", file, ContentType.DEFAULT_BINARY, imageFileName);
builder.addBinaryBody
  ("upstream", inputStream, ContentType.create("application/zip"), zipFileName);
builder.addTextBody("text", message, ContentType.TEXT_PLAIN);
// 
HttpEntity entity = builder.build();
post.setEntity(entity);
HttpResponse response = client.execute(post);

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

请注意，ContentType值可以即时创建，就像上面例子中的zip文件一样。

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

最后，不是所有的服务器都承认 InputStream部分。我们在第一行代码中实例化的服务器承认 InputStreams。

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

现在让我们看看另一个例子，addBinaryBody直接与一个字节数组工作。

Example 3.3. – Uploading a Byte Array and Text

例3.3.- 上传一个字节数组和文本。

HttpPost post = new HttpPost("http://echo.200please.com");
String message = "This is a multipart post";
byte[] bytes = "binary code".getBytes(); 
// 
MultipartEntityBuilder builder = MultipartEntityBuilder.create();
builder.setMode(HttpMultipartMode.BROWSER_COMPATIBLE);
builder.addBinaryBody("upfile", bytes, ContentType.DEFAULT_BINARY, textFileName);
builder.addTextBody("text", message, ContentType.TEXT_PLAIN);
// 
HttpEntity entity = builder.build();
post.setEntity(entity);
HttpResponse response = client.execute(post);

Notice the ContentType – which is now specifying binary data.

注意ContentType–现在指定的是二进制数据。

4. Conclusion

4.结论

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

本文介绍了MultipartEntityBuilder，它是一个灵活的对象，为创建多部分表单提供了多种API选择。

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

这些例子还显示了如何使用HttpClient来上传一个类似于表单实体的HttpEntity。

The implementation of all these examples and code snippets can be found in our GitHub project – this is an Eclipse-based project, so it should be easy to import and run as it is.

所有这些例子和代码片段的实现可以在我们的GitHub项目中找到 – 这是一个基于Eclipse的项目，所以它应该很容易导入并按原样运行。