0
# Form Part Customization
1

2
Advanced form part creation with custom headers and fine-grained control over multipart section properties. This provides low-level access to multipart form construction for scenarios requiring custom headers or special formatting.
3

4
## Capabilities
5

6
### FormBodyPartBuilder Factory and Configuration
7

8
Creates and configures individual form body parts with custom headers and properties.
9

10
```java { .api }
11
/**
12
 * Builder for individual form body parts with custom header support
13
 */
14
public class FormBodyPartBuilder {
15
    /**
16
     * Create a form body part builder with name and content body
17
     * @param name Field name for the form part
18
     * @param body Content body implementation for the part data
19
     * @return New FormBodyPartBuilder instance for method chaining
20
     */
21
    public static FormBodyPartBuilder create(String name, ContentBody body);
22
    
23
    /**
24
     * Create an empty form body part builder
25
     * @return New FormBodyPartBuilder instance for method chaining
26
     */
27
    public static FormBodyPartBuilder create();
28
    
29
    /**
30
     * Set the field name for the form part
31
     * @param name Field name to use in Content-Disposition header
32
     * @return This builder instance for method chaining
33
     */
34
    public FormBodyPartBuilder setName(String name);
35
    
36
    /**
37
     * Set the content body for the form part
38
     * @param body Content body implementation containing the part data
39
     * @return This builder instance for method chaining
40
     */
41
    public FormBodyPartBuilder setBody(ContentBody body);
42
    
43
    /**
44
     * Add a custom header field to the form part
45
     * @param name Header field name
46
     * @param value Header field value
47
     * @return This builder instance for method chaining
48
     */
49
    public FormBodyPartBuilder addField(String name, String value);
50
    
51
    /**
52
     * Set a header field, replacing any existing field with the same name
53
     * @param name Header field name
54
     * @param value Header field value
55
     * @return This builder instance for method chaining
56
     */
57
    public FormBodyPartBuilder setField(String name, String value);
58
    
59
    /**
60
     * Remove all header fields with the specified name
61
     * @param name Header field name to remove
62
     * @return This builder instance for method chaining
63
     */
64
    public FormBodyPartBuilder removeFields(String name);
65
    
66
    /**
67
     * Build the configured form body part
68
     * @return FormBodyPart instance ready for use in multipart entities
69
     */
70
    public FormBodyPart build();
71
}
72
```
73

74
### FormBodyPart Properties and Access
75

76
Represents a complete form part with headers, name, and content body for inclusion in multipart entities.
77

78
```java { .api }
79
/**
80
 * Individual form body part containing headers, name, and content
81
 * Automatically populates standard headers based on content body properties
82
 */
83
public class FormBodyPart {
84
    /**
85
     * Get the field name for this form part
86
     * @return Field name used in Content-Disposition header
87
     */
88
    public String getName();
89
    
90
    /**
91
     * Get the content body for this form part
92
     * @return ContentBody implementation containing the part data
93
     */
94
    public ContentBody getBody();
95
    
96
    /**
97
     * Get the header collection for this form part
98
     * @return Header object containing all headers for this part
99
     */
100
    public Header getHeader();
101
    
102
    /**
103
     * Add a header field to this form part
104
     * @param name Header field name
105
     * @param value Header field value
106
     */
107
    public void addField(String name, String value);
108
}
109
```
110

111
### Header Management
112

113
Container and utilities for managing MIME headers within form parts.
114

115
```java { .api }
116
/**
117
 * Container for MIME headers in form parts
118
 * Supports multiple values for the same header name
119
 */
120
public class Header {
121
    /**
122
     * Add a header field to the collection
123
     * @param field MinimalField containing name and value
124
     */
125
    public void addField(MinimalField field);
126
    
127
    /**
128
     * Get all header fields
129
     * @return List of all MinimalField instances
130
     */
131
    public List<MinimalField> getFields();
132
    
133
    /**
134
     * Get the first header field with the specified name
135
     * @param name Header field name to search for
136
     * @return First matching MinimalField or null if not found
137
     */
138
    public MinimalField getField(String name);
139
    
140
    /**
141
     * Get all header fields with the specified name
142
     * @param name Header field name to search for
143
     * @return List of all matching MinimalField instances
144
     */
145
    public List<MinimalField> getFields(String name);
146
    
147
    /**
148
     * Remove all header fields with the specified name
149
     * @param name Header field name to remove
150
     * @return Number of fields removed
151
     */
152
    public int removeFields(String name);
153
    
154
    /**
155
     * Set a header field, replacing any existing fields with the same name
156
     * @param field MinimalField to set (replaces existing fields with same name)
157
     */
158
    public void setField(MinimalField field);
159
    
160
    /**
161
     * Iterate over all header fields
162
     * @return Iterator for all MinimalField instances
163
     */
164
    public Iterator<MinimalField> iterator();
165
}
166
```
167

168
### MinimalField
169

170
Individual header field implementation for name-value pairs in MIME headers.
171

172
```java { .api }
173
/**
174
 * Individual MIME header field with name and value
175
 */
176
public class MinimalField {
177
    /**
178
     * Create a header field with name and value
179
     * @param name Header field name
180
     * @param value Header field value
181
     */
182
    public MinimalField(String name, String value);
183
    
184
    /**
185
     * Get the header field name
186
     * @return Header field name
187
     */
188
    public String getName();
189
    
190
    /**
191
     * Get the header field value
192
     * @return Header field value
193
     */
194
    public String getBody();
195
    
196
    /**
197
     * Get formatted header field as "name: value"
198
     * @return Formatted header field string
199
     */
200
    public String toString();
201
}
202
```
203

204
### MIME Constants
205

206
Utility class containing standard MIME header names and encoding constants.
207

208
```java { .api }
209
/**
210
 * MIME-related constants and utilities
211
 */
212
public class MIME {
213
    // Header name constants
214
    public static final String CONTENT_TYPE = "Content-Type";
215
    public static final String CONTENT_TRANSFER_ENC = "Content-Transfer-Encoding";
216
    public static final String CONTENT_DISPOSITION = "Content-Disposition";
217
    
218
    // Transfer encoding constants
219
    public static final String ENC_8BIT = "8bit";
220
    public static final String ENC_BINARY = "binary";
221
    
222
    // Character set constants
223
    public static final Charset DEFAULT_CHARSET; // US-ASCII
224
    public static final Charset UTF8_CHARSET; // UTF-8
225
}
226
```
227

228
**Usage Examples:**
229

230
```java
231
import org.apache.http.entity.mime.*;
232
import org.apache.http.entity.mime.content.*;
233
import org.apache.http.entity.ContentType;
234
import java.io.File;
235

236
// Basic custom form part with additional headers
237
FormBodyPart customPart = FormBodyPartBuilder
238
    .create("document", new FileBody(new File("report.pdf"), ContentType.APPLICATION_PDF))
239
    .addField("Content-Description", "Monthly Sales Report")
240
    .addField("X-Document-Type", "financial")
241
    .addField("X-Department", "sales")
242
    .build();
243

244
// Text part with custom headers
245
StringBody jsonBody = new StringBody("{\"version\":\"1.0\",\"format\":\"report\"}", 
246
                                     ContentType.APPLICATION_JSON);
247
FormBodyPart metadataPart = FormBodyPartBuilder
248
    .create("metadata", jsonBody)
249
    .addField("Content-Description", "Report Metadata")
250
    .addField("X-Schema-Version", "2.1")
251
    .build();
252

253
// Image with custom disposition and headers
254
ByteArrayBody imageBody = new ByteArrayBody(imageBytes, ContentType.IMAGE_JPEG, "profile.jpg");
255
FormBodyPart imagePart = FormBodyPartBuilder
256
    .create("avatar", imageBody)
257
    .addField("Content-Description", "User Profile Picture")
258
    .addField("X-Image-Source", "camera")
259
    .addField("X-Compression", "high")
260
    .build();
261

262
// Use custom parts in multipart entity
263
HttpEntity entity = MultipartEntityBuilder.create()
264
    .addPart(customPart)
265
    .addPart(metadataPart)
266
    .addPart(imagePart)
267
    .addTextBody("username", "johndoe")  // Standard parts can be mixed in
268
    .build();
269

270
// Access part properties
271
String partName = customPart.getName();  // "document"
272
ContentBody body = customPart.getBody(); // FileBody instance
273
Header headers = customPart.getHeader();
274

275
// Work with headers directly
276
Header customHeaders = new Header();
277
customHeaders.addField(new MinimalField("Content-Language", "en-US"));
278
customHeaders.addField(new MinimalField("X-Priority", "high"));
279
customHeaders.addField(new MinimalField("X-Department", "engineering"));
280

281
// Get header values
282
MinimalField priority = customHeaders.getField("X-Priority");
283
List<MinimalField> allFields = customHeaders.getFields();
284
String priorityValue = priority != null ? priority.getBody() : "normal";
285

286
// Complex form part with streaming content and multiple headers
287
FileInputStream largeFileStream = new FileInputStream("large-dataset.csv");
288
InputStreamBody streamBody = new InputStreamBody(largeFileStream, 
289
                                                  ContentType.create("text/csv"), 
290
                                                  "dataset.csv");
291

292
FormBodyPart streamPart = FormBodyPartBuilder
293
    .create("data", streamBody)
294
    .addField("Content-Description", "Machine Learning Dataset")
295
    .addField("X-Data-Format", "CSV")
296
    .addField("X-Record-Count", "1000000")
297
    .addField("X-Columns", "name,age,score,category")
298
    .addField("X-Encoding", "UTF-8")
299
    .build();
300
```