0
# Form Data and Multipart
1

2
Builders for HTML form encoding and multipart form data with file upload support.
3

4
## Capabilities
5

6
### FormEncodingBuilder
7

8
Builder for HTML form-encoded request bodies (application/x-www-form-urlencoded).
9

10
```java { .api }
11
/**
12
 * Builder for HTML form-encoded request bodies.
13
 */
14
public final class FormEncodingBuilder {
15
    public FormEncodingBuilder();
16
    public FormEncodingBuilder add(String name, String value);
17
    public FormEncodingBuilder addEncoded(String name, String value);
18
    public RequestBody build();
19
}
20
```
21

22
**Usage Examples:**
23

24
```java
25
// Simple form data
26
RequestBody formBody = new FormEncodingBuilder()
27
    .add("username", "john")
28
    .add("password", "secret")
29
    .add("remember", "true")
30
    .build();
31

32
Request request = new Request.Builder()
33
    .url("https://example.com/login")
34
    .post(formBody)
35
    .build();
36

37
// Using encoded values (pre-encoded data)
38
RequestBody encodedFormBody = new FormEncodingBuilder()
39
    .addEncoded("query", "search%20term")  // Already URL-encoded
40
    .add("filter", "active")               // Will be encoded automatically
41
    .build();
42
```
43

44
### Form Field Management
45

46
Add form fields with automatic URL encoding or pre-encoded values.
47

48
```java { .api }
49
/**
50
 * Add a form field with the specified name and value. Both name and value
51
 * will be URL-encoded.
52
 * @param name the form field name
53
 * @param value the form field value
54
 * @return this builder for method chaining
55
 */
56
public FormEncodingBuilder add(String name, String value);
57

58
/**
59
 * Add a form field with the specified name and value. Assumes both name
60
 * and value are already URL-encoded.
61
 * @param name the form field name (already encoded)
62
 * @param value the form field value (already encoded)
63
 * @return this builder for method chaining
64
 */
65
public FormEncodingBuilder addEncoded(String name, String value);
66

67
/**
68
 * Build the RequestBody with all added form fields.
69
 * @return RequestBody with Content-Type application/x-www-form-urlencoded
70
 */
71
public RequestBody build();
72
```
73

74
**Usage Examples:**
75

76
```java
77
// Complex form with special characters
78
RequestBody complexForm = new FormEncodingBuilder()
79
    .add("user_name", "john@example.com")      // Email will be encoded
80
    .add("bio", "Software developer & mentor") // Special chars encoded
81
    .add("preferences", "setting1,setting2")   // Comma will be encoded
82
    .build();
83

84
// Mixed encoded/unencoded (when you control encoding)
85
String preEncodedValue = URLEncoder.encode("value with spaces", "UTF-8");
86
RequestBody mixedForm = new FormEncodingBuilder()
87
    .add("normal_field", "normal value")       // Auto-encoded
88
    .addEncoded("custom_field", preEncodedValue) // Pre-encoded
89
    .build();
90
```
91

92
### MultipartBuilder
93

94
Builder for multipart request bodies supporting form data and file uploads.
95

96
```java { .api }
97
/**
98
 * Builder for multipart request bodies.
99
 */
100
public final class MultipartBuilder {
101
    public static final MediaType MIXED;
102
    public static final MediaType ALTERNATIVE;
103
    public static final MediaType DIGEST;
104
    public static final MediaType PARALLEL;
105
    public static final MediaType FORM;
106
    
107
    public MultipartBuilder();
108
    public MultipartBuilder(String boundary);
109
    public MultipartBuilder type(MediaType type);
110
    public MultipartBuilder addPart(RequestBody body);
111
    public MultipartBuilder addPart(Headers headers, RequestBody body);
112
    public MultipartBuilder addFormDataPart(String name, String value);
113
    public MultipartBuilder addFormDataPart(String name, String filename, RequestBody value);
114
    public RequestBody build();
115
}
116
```
117

118
**Usage Examples:**
119

120
```java
121
// Form with file upload
122
File file = new File("document.pdf");
123
RequestBody fileBody = RequestBody.create(MediaType.parse("application/pdf"), file);
124

125
RequestBody multipartBody = new MultipartBuilder()
126
    .type(MultipartBuilder.FORM)
127
    .addFormDataPart("title", "My Document")
128
    .addFormDataPart("description", "Important document")
129
    .addFormDataPart("file", "document.pdf", fileBody)
130
    .build();
131

132
Request request = new Request.Builder()
133
    .url("https://api.example.com/upload")
134
    .post(multipartBody)
135
    .build();
136
```
137

138
### Multipart Type Configuration
139

140
Set the multipart content type using predefined constants.
141

142
```java { .api }
143
/**
144
 * Set the multipart type. Default is MIXED if not specified.
145
 * @param type the MediaType for multipart content
146
 * @return this builder for method chaining
147
 */
148
public MultipartBuilder type(MediaType type);
149

150
// Predefined multipart types
151
public static final MediaType MIXED;        // multipart/mixed
152
public static final MediaType ALTERNATIVE;  // multipart/alternative  
153
public static final MediaType DIGEST;       // multipart/digest
154
public static final MediaType PARALLEL;     // multipart/parallel
155
public static final MediaType FORM;         // multipart/form-data
156
```
157

158
**Usage Examples:**
159

160
```java
161
// File upload form (most common)
162
RequestBody formMultipart = new MultipartBuilder()
163
    .type(MultipartBuilder.FORM)
164
    .addFormDataPart("user_id", "123")
165
    .addFormDataPart("avatar", "profile.jpg", avatarBody)
166
    .build();
167

168
// Mixed content multipart  
169
RequestBody mixedMultipart = new MultipartBuilder()
170
    .type(MultipartBuilder.MIXED)
171
    .addPart(textBody)
172
    .addPart(imageBody)
173
    .build();
174

175
// Custom boundary
176
RequestBody customBoundary = new MultipartBuilder("CustomBoundary123")
177
    .type(MultipartBuilder.FORM)
178
    .addFormDataPart("data", "value")
179
    .build();
180
```
181

182
### Adding Parts
183

184
Add parts to multipart body with various content types and headers.
185

186
```java { .api }
187
/**
188
 * Add a part with just a body. Content-Disposition header will be omitted.
189
 * @param body the part body
190
 * @return this builder for method chaining
191
 */
192
public MultipartBuilder addPart(RequestBody body);
193

194
/**
195
 * Add a part with custom headers and body.
196
 * @param headers custom headers for this part
197
 * @param body the part body
198
 * @return this builder for method chaining
199
 */
200
public MultipartBuilder addPart(Headers headers, RequestBody body);
201

202
/**
203
 * Add a form data part with name and string value.
204
 * @param name the form field name
205
 * @param value the form field value
206
 * @return this builder for method chaining
207
 */
208
public MultipartBuilder addFormDataPart(String name, String value);
209

210
/**
211
 * Add a form data part with name, filename, and body (typically for file uploads).
212
 * @param name the form field name
213
 * @param filename the filename to include in Content-Disposition
214
 * @param value the RequestBody containing file data
215
 * @return this builder for method chaining
216
 */
217
public MultipartBuilder addFormDataPart(String name, String filename, RequestBody value);
218
```
219

220
**Usage Examples:**
221

222
```java
223
// Complex multipart with different content types
224
RequestBody jsonPart = RequestBody.create(
225
    MediaType.parse("application/json"), 
226
    "{\"metadata\":\"info\"}"
227
);
228

229
Headers customHeaders = new Headers.Builder()
230
    .add("Content-Disposition", "form-data; name=\"metadata\"")
231
    .add("Content-Type", "application/json")
232
    .build();
233

234
RequestBody complexMultipart = new MultipartBuilder()
235
    .type(MultipartBuilder.FORM)
236
    // Simple form field
237
    .addFormDataPart("user_id", "456")
238
    // JSON part with custom headers
239
    .addPart(customHeaders, jsonPart)
240
    // File upload
241
    .addFormDataPart("document", "report.pdf", 
242
        RequestBody.create(MediaType.parse("application/pdf"), pdfFile))
243
    // Image upload with different name/filename
244
    .addFormDataPart("photo", "vacation.jpg",
245
        RequestBody.create(MediaType.parse("image/jpeg"), imageFile))
246
    .build();
247

248
// Multiple file uploads
249
RequestBody multiFileUpload = new MultipartBuilder()
250
    .type(MultipartBuilder.FORM)
251
    .addFormDataPart("description", "Photo gallery upload")
252
    .addFormDataPart("photo1", "beach.jpg", 
253
        RequestBody.create(MediaType.parse("image/jpeg"), photo1))
254
    .addFormDataPart("photo2", "sunset.jpg",
255
        RequestBody.create(MediaType.parse("image/jpeg"), photo2))
256
    .addFormDataPart("photo3", "mountains.jpg",
257
        RequestBody.create(MediaType.parse("image/jpeg"), photo3))
258
    .build();
259
```
260

261
### Building the Multipart Body
262

263
Create the final RequestBody from all added parts.
264

265
```java { .api }
266
/**
267
 * Build the multipart RequestBody with all added parts.
268
 * @return RequestBody with appropriate multipart Content-Type
269
 */
270
public RequestBody build();
271
```
272

273
**Usage Examples:**
274

275
```java
276
// Build and use in request
277
MultipartBuilder builder = new MultipartBuilder()
278
    .type(MultipartBuilder.FORM)
279
    .addFormDataPart("field1", "value1")
280
    .addFormDataPart("field2", "value2");
281

282
// Can add more parts dynamically
283
if (includeFile) {
284
    builder.addFormDataPart("file", "data.txt", fileBody);
285
}
286

287
RequestBody multipartBody = builder.build();
288
Request request = new Request.Builder()
289
    .url("https://api.example.com/upload")
290
    .post(multipartBody)
291
    .build();
292
```