0
# Apache HttpComponents HttpMime
1

2
Apache HttpComponents HttpMime provides comprehensive support for MIME multipart encoded entities and form-based file uploads for the Apache HttpClient library. It enables developers to handle multipart/form-data requests, file uploads, and complex form submissions in HTTP client applications with efficient memory management and streaming capabilities.
3

4
## Package Information
5

6
- **Package Name**: org.apache.httpcomponents:httpmime
7
- **Package Type**: maven
8
- **Language**: Java
9
- **Installation**: Add to your Maven dependencies:
10
  ```xml
11
  <dependency>
12
    <groupId>org.apache.httpcomponents</groupId>
13
    <artifactId>httpmime</artifactId>
14
    <version>4.5.14</version>
15
  </dependency>
16
  ```
17

18
## Core Imports
19

20
```java
21
import org.apache.http.entity.mime.MultipartEntityBuilder;
22
import org.apache.http.entity.mime.FormBodyPartBuilder;
23
import org.apache.http.entity.mime.HttpMultipartMode;
24
import org.apache.http.entity.mime.content.StringBody;
25
import org.apache.http.entity.mime.content.FileBody;
26
import org.apache.http.entity.mime.content.ByteArrayBody;
27
import org.apache.http.entity.mime.content.InputStreamBody;
28
import org.apache.http.HttpEntity;
29
```
30

31
## Basic Usage
32

33
```java
34
import org.apache.http.entity.mime.MultipartEntityBuilder;
35
import org.apache.http.HttpEntity;
36
import org.apache.http.entity.ContentType;
37
import java.io.File;
38

39
// Simple form with text fields
40
HttpEntity entity = MultipartEntityBuilder.create()
41
    .addTextBody("username", "john_doe")
42
    .addTextBody("description", "User profile update")
43
    .build();
44

45
// File upload with form data
46
HttpEntity fileUploadEntity = MultipartEntityBuilder.create()
47
    .addBinaryBody("file", new File("document.pdf"), 
48
                   ContentType.APPLICATION_PDF, "document.pdf")
49
    .addTextBody("title", "Important Document")
50
    .addTextBody("category", "reports")
51
    .build();
52

53
// Mixed content with different body types
54
byte[] imageData = // ... image bytes
55
HttpEntity mixedEntity = MultipartEntityBuilder.create()
56
    .setMode(HttpMultipartMode.BROWSER_COMPATIBLE)
57
    .addTextBody("description", "Profile image")
58
    .addBinaryBody("avatar", imageData, ContentType.IMAGE_JPEG, "avatar.jpg")
59
    .addBinaryBody("document", new File("resume.pdf"))
60
    .build();
61
```
62

63
## Architecture
64

65
HttpMime is built around several key components:
66

67
- **MultipartEntityBuilder**: Main fluent API for creating multipart entities with chainable method calls
68
- **Content Bodies**: Specialized implementations for different data types (text, files, byte arrays, streams)
69
- **Form Parts**: Individual multipart sections with headers and content
70
- **Multipart Modes**: Different encoding standards (strict RFC compliance, browser compatibility, Unicode support)
71
- **Streaming Support**: Efficient handling of large files and data without loading everything into memory
72

73
## Capabilities
74

75
### Multipart Entity Building
76

77
Core functionality for creating multipart HTTP entities using a fluent builder pattern. Essential for file uploads and complex form submissions.
78

79
```java { .api }
80
public class MultipartEntityBuilder {
81
    public static MultipartEntityBuilder create();
82
    public MultipartEntityBuilder setMode(HttpMultipartMode mode);
83
    public MultipartEntityBuilder addTextBody(String name, String text);
84
    public MultipartEntityBuilder addBinaryBody(String name, File file);
85
    public HttpEntity build();
86
}
87
```
88

89
[Multipart Entity Building](./multipart-entity-building.md)
90

91
### Content Body Types
92

93
Different content body implementations for handling various data types in multipart forms, from simple text to binary files and streams.
94

95
```java { .api }
96
public interface ContentBody extends ContentDescriptor {
97
    String getFilename();
98
    void writeTo(OutputStream out) throws IOException;
99
}
100

101
public class StringBody extends AbstractContentBody {
102
    public StringBody(String text, ContentType contentType);
103
}
104

105
public class FileBody extends AbstractContentBody {
106
    public FileBody(File file, ContentType contentType, String filename);
107
}
108
```
109

110
[Content Body Types](./content-body-types.md)
111

112
### Form Part Customization
113

114
Advanced form part creation with custom headers and fine-grained control over multipart section properties.
115

116
```java { .api }
117
public class FormBodyPartBuilder {
118
    public static FormBodyPartBuilder create(String name, ContentBody body);
119
    public FormBodyPartBuilder addField(String name, String value);
120
    public FormBodyPart build();
121
}
122

123
public class FormBodyPart {
124
    public String getName();
125
    public ContentBody getBody();
126
    public Header getHeader();
127
}
128
```
129

130
[Form Part Customization](./form-part-customization.md)
131

132
## Types
133

134
```java { .api }
135
public enum HttpMultipartMode {
136
    /** RFC 822, RFC 2045, RFC 2046 compliant */
137
    STRICT,
138
    /** Browser-compatible mode, only write Content-Disposition; use content charset */
139
    BROWSER_COMPATIBLE,
140
    /** RFC 6532 compliant */
141
    RFC6532
142
}
143

144
public interface ContentDescriptor {
145
    String getMimeType();
146
    String getMediaType();
147
    String getSubType(); 
148
    String getCharset();
149
    String getTransferEncoding();
150
    long getContentLength();
151
}
152

153
public class Header {
154
    public void addField(MinimalField field);
155
    public MinimalField getField(String name);
156
    public List<MinimalField> getFields();
157
    public List<MinimalField> getFields(String name);
158
    public int removeFields(String name);
159
    public void setField(MinimalField field);
160
    public Iterator<MinimalField> iterator();
161
}
162

163
public class MinimalField {
164
    public MinimalField(String name, String value);
165
    public String getName();
166
    public String getBody();
167
}
168
```