0
# Multipart Entity Building
1

2
Core functionality for creating multipart HTTP entities using the MultipartEntityBuilder fluent API. This is the primary entry point for building multipart/form-data requests with support for various content types, encoding modes, and streaming operations.
3

4
## Capabilities
5

6
### MultipartEntityBuilder Factory
7

8
Creates new builder instances for constructing multipart entities.
9

10
```java { .api }
11
/**
12
 * Creates a new MultipartEntityBuilder instance
13
 * @return New builder instance for method chaining
14
 */
15
public static MultipartEntityBuilder create();
16
```
17

18
### Multipart Mode Configuration
19

20
Controls the multipart encoding standard and compatibility mode used for the generated entity.
21

22
```java { .api }
23
/**
24
 * Set the multipart mode for encoding compliance
25
 * @param mode The multipart mode (STRICT, BROWSER_COMPATIBLE, or RFC6532)
26
 * @return This builder instance for method chaining
27
 */
28
public MultipartEntityBuilder setMode(HttpMultipartMode mode);
29

30
/**
31
 * Set browser-compatible mode (shortcut for BROWSER_COMPATIBLE mode)
32
 * @return This builder instance for method chaining
33
 */
34
public MultipartEntityBuilder setLaxMode();
35

36
/**
37
 * Set strict RFC-compliant mode (shortcut for STRICT mode)
38
 * @return This builder instance for method chaining
39
 */
40
public MultipartEntityBuilder setStrictMode();
41
```
42

43
### Boundary and Content Type Configuration
44

45
Customize the multipart boundary and content type settings for the entity.
46

47
```java { .api }
48
/**
49
 * Set a custom boundary string for the multipart entity
50
 * @param boundary Custom boundary string
51
 * @return This builder instance for method chaining
52
 */
53
public MultipartEntityBuilder setBoundary(String boundary);
54

55
/**
56
 * Set the MIME subtype for the multipart entity
57
 * @param subType MIME subtype (e.g., "form-data", "mixed")
58
 * @return This builder instance for method chaining
59
 */
60
public MultipartEntityBuilder setMimeSubtype(String subType);
61

62
/**
63
 * Set the complete content type for the multipart entity
64
 * @param contentType ContentType object with full type information
65
 * @return This builder instance for method chaining
66
 */
67
public MultipartEntityBuilder setContentType(ContentType contentType);
68

69
/**
70
 * Set the character encoding for the multipart entity
71
 * @param charset Character encoding to use
72
 * @return This builder instance for method chaining
73
 */
74
public MultipartEntityBuilder setCharset(Charset charset);
75
```
76

77
### Adding Text Content
78

79
Add text fields to the multipart form with various content type options.
80

81
```java { .api }
82
/**
83
 * Add a text field with default text/plain content type
84
 * @param name Field name for the form part
85
 * @param text Text content
86
 * @return This builder instance for method chaining
87
 */
88
public MultipartEntityBuilder addTextBody(String name, String text);
89

90
/**
91
 * Add a text field with specified content type
92
 * @param name Field name for the form part
93
 * @param text Text content
94
 * @param contentType Content type for the text (e.g., text/html, application/json)
95
 * @return This builder instance for method chaining
96
 */
97
public MultipartEntityBuilder addTextBody(String name, String text, ContentType contentType);
98
```
99

100
### Adding Binary Content
101

102
Add binary data from various sources including files, byte arrays, and input streams.
103

104
```java { .api }
105
/**
106
 * Add binary content from a byte array with default binary content type
107
 * @param name Field name for the form part
108
 * @param b Byte array containing the binary data
109
 * @return This builder instance for method chaining
110
 */
111
public MultipartEntityBuilder addBinaryBody(String name, byte[] b);
112

113
/**
114
 * Add binary content from a byte array with specified content type and filename
115
 * @param name Field name for the form part
116
 * @param b Byte array containing the binary data
117
 * @param contentType Content type for the binary data
118
 * @param filename Filename to use in Content-Disposition header
119
 * @return This builder instance for method chaining
120
 */
121
public MultipartEntityBuilder addBinaryBody(String name, byte[] b, ContentType contentType, String filename);
122

123
/**
124
 * Add binary content from a file with default binary content type
125
 * @param name Field name for the form part
126
 * @param file File to upload
127
 * @return This builder instance for method chaining
128
 */
129
public MultipartEntityBuilder addBinaryBody(String name, File file);
130

131
/**
132
 * Add binary content from a file with specified content type and filename
133
 * @param name Field name for the form part
134
 * @param file File to upload
135
 * @param contentType Content type for the file
136
 * @param filename Custom filename to use in Content-Disposition header
137
 * @return This builder instance for method chaining
138
 */
139
public MultipartEntityBuilder addBinaryBody(String name, File file, ContentType contentType, String filename);
140

141
/**
142
 * Add binary content from an input stream with default binary content type
143
 * @param name Field name for the form part
144
 * @param stream Input stream containing the binary data
145
 * @return This builder instance for method chaining
146
 */
147
public MultipartEntityBuilder addBinaryBody(String name, InputStream stream);
148

149
/**
150
 * Add binary content from an input stream with specified content type and filename
151
 * @param name Field name for the form part
152
 * @param stream Input stream containing the binary data
153
 * @param contentType Content type for the stream data
154
 * @param filename Filename to use in Content-Disposition header
155
 * @return This builder instance for method chaining
156
 */
157
public MultipartEntityBuilder addBinaryBody(String name, InputStream stream, ContentType contentType, String filename);
158
```
159

160
### Adding Custom Parts
161

162
Add pre-built form parts with custom headers and configuration.
163

164
```java { .api }
165
/**
166
 * Add a custom form body part with full control over headers and content
167
 * @param bodyPart Pre-configured FormBodyPart instance
168
 * @return This builder instance for method chaining
169
 */
170
public MultipartEntityBuilder addPart(FormBodyPart bodyPart);
171

172
/**
173
 * Add a part with a custom content body implementation
174
 * @param name Field name for the form part
175
 * @param contentBody Custom ContentBody implementation
176
 * @return This builder instance for method chaining
177
 */
178
public MultipartEntityBuilder addPart(String name, ContentBody contentBody);
179
```
180

181
### Building the Entity
182

183
Create the final HttpEntity from the configured multipart builder.
184

185
```java { .api }
186
/**
187
 * Build and return the configured multipart HttpEntity
188
 * @return HttpEntity suitable for use with HttpClient requests
189
 */
190
public HttpEntity build();
191
```
192

193
**Usage Examples:**
194

195
```java
196
import org.apache.http.entity.mime.MultipartEntityBuilder;
197
import org.apache.http.entity.mime.HttpMultipartMode;
198
import org.apache.http.entity.ContentType;
199
import java.io.File;
200
import java.io.FileInputStream;
201

202
// Basic form submission
203
HttpEntity basicForm = MultipartEntityBuilder.create()
204
    .addTextBody("username", "johndoe")
205
    .addTextBody("email", "john@example.com")
206
    .addTextBody("message", "Hello server!")
207
    .build();
208

209
// File upload with metadata
210
HttpEntity fileUpload = MultipartEntityBuilder.create()
211
    .setMode(HttpMultipartMode.BROWSER_COMPATIBLE)
212
    .addBinaryBody("document", new File("report.pdf"), 
213
                   ContentType.APPLICATION_PDF, "monthly-report.pdf")
214
    .addTextBody("category", "reports")
215
    .addTextBody("confidential", "true")
216
    .build();
217

218
// Mixed content with streams and custom boundary
219
HttpEntity mixedContent = MultipartEntityBuilder.create()
220
    .setBoundary("MyCustomBoundary123")
221
    .setCharset(StandardCharsets.UTF_8)
222
    .addTextBody("description", "Profile data", ContentType.TEXT_PLAIN)
223
    .addBinaryBody("avatar", new FileInputStream("avatar.jpg"), 
224
                   ContentType.IMAGE_JPEG, "avatar.jpg")
225
    .addBinaryBody("resume", resumeBytes, ContentType.APPLICATION_PDF, "resume.pdf")
226
    .build();
227

228
// JSON data with file
229
HttpEntity jsonWithFile = MultipartEntityBuilder.create()
230
    .addTextBody("metadata", "{\"type\":\"document\",\"version\":1}", 
231
                 ContentType.APPLICATION_JSON)
232
    .addBinaryBody("file", document, ContentType.APPLICATION_OCTET_STREAM, "data.bin")
233
    .build();
234
```