1 package com.atlassian.httpclient.api;
2
3 import java.net.URI;
4 import java.util.Map;
5
6 /**
7 * An interface for building and executing HTTP requests.
8 */
9 public interface Request extends Message {
10 enum Method {GET, POST, PUT, DELETE, OPTIONS, HEAD, TRACE}
11
12 /**
13 * Returns this request's URI, if set.
14 *
15 * @return The URI or null if not yet set
16 */
17 URI getUri();
18
19 /**
20 * Returns this request's Accept header, if set.
21 *
22 * @return The accept header value
23 */
24 String getAccept();
25
26 /**
27 * Gets an attribute from the request. Attributes are request metadata that are forwarded to the
28 * analytics plugin when enabled.
29 *
30 * @param name The attribute name
31 * @return The attribute value, or null if not set
32 */
33 String getAttribute(String name);
34
35 /**
36 * Gets all attributes for this request. Attributes are request metadata that are forwarded to the
37 * analytics plugin when enabled.
38 *
39 * @return All attributes
40 */
41 Map<String, String> getAttributes();
42
43 boolean isCacheDisabled();
44
45 Method getMethod();
46
47 interface Builder extends Common<Builder>, Buildable<Request> {
48 /**
49 * Sets this request's URI. Must not be null by the time the request is executed.
50 *
51 * @param uri The URI
52 * @return This object, for builder-style chaining
53 */
54 Builder setUri(URI uri);
55
56 /**
57 * Sets the Accept header for the request.
58 *
59 * @param accept An accept header expression containing media types, ranges, and/or quality factors
60 * @return This object, for builder-style chaining
61 */
62 Builder setAccept(String accept);
63
64 /**
65 * Bypasses the cache for this request
66 *
67 * @return This object, for builder-style chaining
68 */
69 Builder setCacheDisabled();
70
71 /**
72 * Sets an attribute on the request. Attributes are request metadata that are forwarded to the
73 * analytics plugin when enabled.
74 *
75 * @param name The attribute name
76 * @param value The attribute value
77 * @return This object, for builder-style chaining
78 */
79 Builder setAttribute(String name, String value);
80
81 /**
82 * Sets attributes on the request. Attributes are request metadata that are forwarded to the
83 * analytics plugin when enabled.
84 *
85 * @param properties A map of attributes
86 * @return This object, for builder-style chaining
87 */
88 Builder setAttributes(Map<String, String> properties);
89
90 /**
91 * Set the content length for the message. Use this to explicitly override the content length determined from
92 * the entity in the message (e.g. if you want to stream the entity without chunking).
93 *
94 * @param contentLength The content length. This must be valid (greater than 0).
95 * @return This object, for builder-style chaining
96 */
97 Builder setContentLength(long contentLength);
98
99 /**
100 * Sets the entity and any associated headers from an entity builder.
101 *
102 * @param entityBuilder An entity builder
103 * @return This object, for builder-style chaining
104 */
105 Builder setEntity(EntityBuilder entityBuilder);
106
107 Builder setHeader(String name, String value);
108
109 /**
110 * Executes this request through the {@link HttpClient} service as a <code>GET</code> operation.
111 * The request SHOULD NOT contain an entity for the <code>GET</code> operation.
112 *
113 * @return A promise object that can be used to receive the response and handle exceptions
114 */
115 ResponsePromise get();
116
117 /**
118 * Executes this request through the {@link HttpClient} service as a <code>POST</code> operation.
119 * The request SHOULD contain an entity for the <code>POST</code> operation.
120 *
121 * @return A promise object that can be used to receive the response and handle exceptions
122 */
123 ResponsePromise post();
124
125 /**
126 * Executes this request through the {@link HttpClient} service as a <code>PUT</code> operation.
127 * The request SHOULD contain an entity for the <code>PUT</code> operation.
128 *
129 * @return A promise object that can be used to receive the response and handle exceptions
130 */
131 ResponsePromise put();
132
133 /**
134 * Executes this request through the {@link HttpClient} service as a <code>DELETE</code> operation.
135 * The request SHOULD NOT contain an entity for the <code>DELETE</code> operation.
136 *
137 * @return A promise object that can be used to receive the response and handle exceptions
138 */
139 ResponsePromise delete();
140
141 /**
142 * Executes this request through the {@link HttpClient} service as a <code>OPTIONS</code> operation.
143 * The request MAY contain an entity for the <code>OPTIONS</code> operation.
144 *
145 * @return A promise object that can be used to receive the response and handle exceptions
146 */
147 ResponsePromise options();
148
149 /**
150 * Executes this request through the {@link HttpClient} service as a <code>HEAD</code> operation.
151 * The request SHOULD NOT contain an entity for the <code>HEAD</code> operation.
152 *
153 * @return A promise object that can be used to receive the response and handle exceptions
154 */
155 ResponsePromise head();
156
157 /**
158 * Executes this request through the {@link HttpClient} service as a <code>TRACE</code> operation.
159 * The request SHOULD contain an entity for the <code>TRACE</code> operation.
160 *
161 * @return A promise object that can be used to receive the response and handle exceptions
162 */
163 ResponsePromise trace();
164
165 /**
166 * Executes this request through the {@link HttpClient} service using the given HTTP method.
167 *
168 * @param method the HTTP method to use.
169 * @return A promise object that can be used to receive the response and handle exceptions
170 */
171 ResponsePromise execute(Method method);
172 }
173
174 }