0
# HTTP Request Operations
1

2
The Request class provides a fluent interface for building and configuring HTTP requests. All methods return the Request instance for method chaining.
3

4
## Request Factory Methods
5

6
Create HTTP requests using static factory methods for each HTTP method:
7

8
```java { .api }
9
public static Request Get(String uri);
10
public static Request Get(URI uri);
11
public static Request Post(String uri);
12
public static Request Post(URI uri);
13
public static Request Put(String uri);
14
public static Request Put(URI uri);
15
public static Request Delete(String uri);
16
public static Request Delete(URI uri);
17
public static Request Head(String uri);
18
public static Request Head(URI uri);
19
public static Request Options(String uri);
20
public static Request Options(URI uri);
21
public static Request Patch(String uri);
22
public static Request Patch(URI uri);
23
public static Request Trace(String uri);
24
public static Request Trace(URI uri);
25
```
26

27
### Usage Examples
28

29
```java
30
// GET request
31
Request getRequest = Request.Get("https://api.example.com/users");
32

33
// POST request  
34
Request postRequest = Request.Post("https://api.example.com/users");
35

36
// PUT request with URI object
37
URI uri = new URI("https://api.example.com/users/123");
38
Request putRequest = Request.Put(uri);
39
```
40

41
## Request Execution
42

43
Execute the configured request and get a Response object:
44

45
```java { .api }
46
public Response execute() throws ClientProtocolException, IOException;
47
public void abort() throws UnsupportedOperationException;
48
```
49

50
### Usage Examples
51

52
```java
53
// Execute and get response
54
Response response = Request.Get("https://api.example.com/data").execute();
55

56
// Abort a request (if still in progress)
57
Request request = Request.Get("https://slow-api.example.com/data");
58
request.abort();
59
```
60

61
## Header Configuration
62

63
Configure HTTP headers using various methods:
64

65
```java { .api }
66
public Request addHeader(Header header);
67
public Request addHeader(String name, String value);
68
public Request setHeader(Header header);
69
public Request setHeader(String name, String value);
70
public Request removeHeader(Header header);
71
public Request removeHeaders(String name);
72
public Request setHeaders(Header... headers);
73
public Request setCacheControl(String cacheControl);
74
public Request setDate(Date date);
75
public Request setIfModifiedSince(Date date);
76
public Request setIfUnmodifiedSince(Date date);
77
```
78

79
### Usage Examples
80

81
```java
82
import org.apache.http.message.BasicHeader;
83
import java.util.Date;
84

85
Request request = Request.Post("https://api.example.com/data")
86
    .addHeader("Authorization", "Bearer token123")
87
    .addHeader("Content-Type", "application/json")
88
    .setHeader(new BasicHeader("X-API-Version", "v1"))
89
    .setCacheControl("no-cache")
90
    .setDate(new Date())
91
    .setIfModifiedSince(new Date(System.currentTimeMillis() - 86400000)); // 24 hours ago
92
```
93

94
## HTTP Protocol Configuration
95

96
Configure HTTP protocol settings:
97

98
```java { .api }
99
public Request version(HttpVersion version);
100
public Request useExpectContinue();
101
public Request userAgent(String agent);
102
```
103

104
### Usage Examples
105

106
```java
107
import org.apache.http.HttpVersion;
108

109
Request request = Request.Post("https://api.example.com/upload")
110
    .version(HttpVersion.HTTP_1_1)
111
    .useExpectContinue()
112
    .userAgent("MyApp/1.0");
113
```
114

115
## Connection Configuration
116

117
Configure connection timeouts and proxy settings:
118

119
```java { .api }
120
public Request socketTimeout(int timeout);
121
public Request connectTimeout(int timeout);
122
public Request viaProxy(HttpHost proxy);
123
public Request viaProxy(String proxy);
124
```
125

126
### Usage Examples
127

128
```java
129
import org.apache.http.HttpHost;
130

131
Request request = Request.Get("https://api.example.com/data")
132
    .connectTimeout(5000)    // 5 second connection timeout
133
    .socketTimeout(30000)    // 30 second socket timeout
134
    .viaProxy(new HttpHost("proxy.example.com", 8080))
135
    .viaProxy("proxy.example.com:8080");
136
```
137

138
## Request Body Configuration
139

140
Configure request body for entity-enclosing requests (POST, PUT, PATCH):
141

142
```java { .api }
143
public Request body(HttpEntity entity);
144
public Request bodyString(String s, ContentType contentType);
145
public Request bodyFile(File file, ContentType contentType);
146
public Request bodyByteArray(byte[] b);
147
public Request bodyByteArray(byte[] b, ContentType contentType);
148
public Request bodyByteArray(byte[] b, int off, int len);
149
public Request bodyByteArray(byte[] b, int off, int len, ContentType contentType);
150
public Request bodyStream(InputStream inStream);
151
public Request bodyStream(InputStream inStream, ContentType contentType);
152
public Request bodyForm(Iterable<? extends NameValuePair> formParams);
153
public Request bodyForm(Iterable<? extends NameValuePair> formParams, Charset charset);
154
public Request bodyForm(NameValuePair... formParams);
155
```
156

157
### Usage Examples
158

159
```java
160
import org.apache.http.entity.ContentType;
161
import org.apache.http.client.fluent.Form;
162
import java.io.File;
163
import java.io.FileInputStream;
164
import java.nio.charset.StandardCharsets;
165

166
// JSON string body
167
Request jsonRequest = Request.Post("https://api.example.com/users")
168
    .bodyString("{\"name\":\"John\",\"email\":\"john@example.com\"}", ContentType.APPLICATION_JSON);
169

170
// File body
171
File file = new File("/path/to/document.pdf");
172
Request fileRequest = Request.Put("https://api.example.com/documents")
173
    .bodyFile(file, ContentType.APPLICATION_OCTET_STREAM);
174

175
// Byte array body
176
byte[] data = "Hello World".getBytes(StandardCharsets.UTF_8);
177
Request byteRequest = Request.Post("https://api.example.com/data")
178
    .bodyByteArray(data, ContentType.TEXT_PLAIN);
179

180
// Stream body
181
FileInputStream stream = new FileInputStream(file);
182
Request streamRequest = Request.Post("https://api.example.com/upload")
183
    .bodyStream(stream, ContentType.APPLICATION_OCTET_STREAM);
184

185
// Form data body
186
Request formRequest = Request.Post("https://api.example.com/login")
187
    .bodyForm(Form.form()
188
        .add("username", "user")
189
        .add("password", "pass")
190
        .build());
191

192
// Form with custom charset
193
Request formWithCharset = Request.Post("https://api.example.com/submit")
194
    .bodyForm(Form.form()
195
        .add("comment", "Héllo Wörld")
196
        .build(), StandardCharsets.UTF_8);
197
```
198

199
## Constants
200

201
```java { .api }
202
public static final String DATE_FORMAT = "EEE, dd MMM yyyy HH:mm:ss zzz";
203
public static final Locale DATE_LOCALE = Locale.US;
204
public static final TimeZone TIME_ZONE = TimeZone.getTimeZone("GMT");
205
```
206

207
## Deprecated Methods
208

209
These methods are deprecated and have no effect:
210

211
```java { .api }
212
@Deprecated public Request config(String param, Object object);
213
@Deprecated public Request removeConfig(String param);
214
@Deprecated public Request elementCharset(String charset);
215
@Deprecated public Request staleConnectionCheck(boolean b);
216
```
217

218
## Error Handling
219

220
Request methods can throw:
221

222
- `IllegalStateException` - When trying to set body on non-entity-enclosing requests (GET, HEAD, etc.)
223
- `UnsupportedOperationException` - When calling abort() on completed requests
224
- Parameter validation occurs during execution, not during request building
225

226
### Usage Examples
227

228
```java
229
try {
230
    // This will throw IllegalStateException
231
    Request.Get("https://api.example.com/data")
232
        .bodyString("data", ContentType.TEXT_PLAIN)
233
        .execute();
234
} catch (IllegalStateException e) {
235
    System.err.println("Cannot set body on GET request: " + e.getMessage());
236
}
237
```