1 package com.atlassian.httpclient.api;
2
3 import com.atlassian.util.concurrent.Promise;
4 import com.google.common.base.Function;
5
6 /**
7 * Transforms the {@link ResponsePromise} into a target object, allowing for transforming functions based on different
8 * HTTP codes or exceptions. Under the covers, all functions are used in a fold() call.
9 *
10 * @param <T> The target object for the transformation.
11 */
12 public interface ResponseTransformation<T> {
13 Function<Throwable, ? extends T> getFailFunction();
14
15 Function<Response, T> getSuccessFunctions();
16
17 /**
18 * Converts the transformation into a promise for further mapping
19 *
20 * @return A promise that will return the object
21 */
22 Promise<T> apply(ResponsePromise responsePromise);
23
24 interface Builder<T> extends Buildable<ResponseTransformation<T>> {
25
26 /**
27 * Register a function to transform HTTP responses with a specific status.
28 * Use this as a fallback if the status code you're interested in does not have
29 * a more explicit registration method for it.
30 *
31 * @param status The HTTP status to select on
32 * @param f The transformation function
33 * @return This instance for chaining
34 * @see #on(int, com.google.common.base.Function)
35 */
36 Builder<T> on(HttpStatus status, Function<Response, ? extends T> f);
37
38 /**
39 * <p>Register a function to transform HTTP responses with a specific status code.
40 * Use this as a fallback if the status code you're interested in does not have
41 * a more explicit registration method for it.
42 * <p>Prefer the {@link #on(HttpStatus, com.google.common.base.Function)} method if you're using <em>standard</em>
43 * HTTP status.
44 *
45 * @param statusCode The code to select on
46 * @param f The transformation function
47 * @return This instance for chaining
48 * @see #on(HttpStatus, com.google.common.base.Function)
49 */
50 Builder<T> on(int statusCode, Function<Response, ? extends T> f);
51
52 // Informational (1xx) Selectors
53
54 /**
55 * Register a function to transform 'informational' (1xx) HTTP responses.
56 *
57 * @param f The transformation function
58 * @return This instance for chaining
59 */
60 Builder<T> informational(Function<Response, ? extends T> f);
61
62 // Successful (2xx) Selectors
63
64 /**
65 * Register a function to transform 'successful' (2xx) HTTP responses.
66 *
67 * @param f The transformation function
68 * @return This instance for chaining
69 */
70 Builder<T> successful(Function<Response, ? extends T> f);
71
72 /**
73 * Register a function to transform 'ok' (200) HTTP responses.
74 *
75 * @param f The transformation function
76 * @return This instance for chaining
77 */
78 Builder<T> ok(Function<Response, ? extends T> f);
79
80 /**
81 * Register a function to transform 'created' (201) HTTP responses.
82 *
83 * @param f The transformation function
84 * @return This instance for chaining
85 */
86 Builder<T> created(Function<Response, ? extends T> f);
87
88 /**
89 * Register a function to transform 'no content' (204) HTTP responses.
90 *
91 * @param f The transformation function
92 * @return This instance for chaining
93 */
94 Builder<T> noContent(Function<Response, ? extends T> f);
95
96 // Redirection (3xx) Selectors
97
98 /**
99 * Register a function to transform 'redirection' (3xx) HTTP responses.
100 *
101 * @param f The transformation function
102 * @return This instance for chaining
103 */
104 Builder<T> redirection(Function<Response, ? extends T> f);
105
106 /**
107 * Register a function to transform 'see other' (303) HTTP responses.
108 *
109 * @param f The transformation function
110 * @return This instance for chaining
111 */
112 Builder<T> seeOther(Function<Response, ? extends T> f);
113
114 /**
115 * Register a function to transform 'not modified' (304) HTTP responses.
116 *
117 * @param f The transformation function
118 * @return This instance for chaining
119 */
120 Builder<T> notModified(Function<Response, ? extends T> f);
121
122 // Client Error (4xx) Selectors
123
124 /**
125 * Register a function to transform 'client error' (4xx) HTTP responses.
126 *
127 * @param f The transformation function
128 * @return This instance for chaining
129 */
130 Builder<T> clientError(Function<Response, ? extends T> f);
131
132 /**
133 * Register a function to transform 'bad request' (400) HTTP responses.
134 *
135 * @param f The transformation function
136 * @return This instance for chaining
137 */
138 Builder<T> badRequest(Function<Response, ? extends T> f);
139
140 /**
141 * Register a function to transform 'unauthorized' (401) HTTP responses.
142 *
143 * @param f The transformation function
144 * @return This instance for chaining
145 */
146 Builder<T> unauthorized(Function<Response, ? extends T> f);
147
148 /**
149 * Register a function to transform 'forbidden' (403) HTTP responses.
150 *
151 * @param f The transformation function
152 * @return This instance for chaining
153 */
154 Builder<T> forbidden(Function<Response, ? extends T> f);
155
156 /**
157 * Register a function to transform 'not found' (404) HTTP responses.
158 *
159 * @param f The transformation function
160 * @return This instance for chaining
161 */
162 Builder<T> notFound(Function<Response, ? extends T> f);
163
164 /**
165 * Register a function to transform 'conflict' (409) HTTP responses.
166 *
167 * @param f The transformation function
168 * @return This instance for chaining
169 */
170 Builder<T> conflict(Function<Response, ? extends T> f);
171
172 // Server Error (5xx) Selectors
173
174 /**
175 * Register a function to transform 'server error' (5xx) HTTP responses.
176 *
177 * @param f The transformation function
178 * @return This instance for chaining
179 */
180 Builder<T> serverError(Function<Response, ? extends T> f);
181
182 /**
183 * Register a function to transform 'internal server error' (500) HTTP responses.
184 *
185 * @param f The transformation function
186 * @return This instance for chaining
187 */
188 Builder<T> internalServerError(Function<Response, ? extends T> f);
189
190 /**
191 * Register a function to transform 'service unavailable' (503) HTTP responses.
192 *
193 * @param f The transformation function
194 * @return This instance for chaining
195 */
196 Builder<T> serviceUnavailable(Function<Response, ? extends T> f);
197
198 // Aggregate Selectors
199
200 /**
201 * Register a function to transform all error (4xx and 5xx) HTTP responses.
202 *
203 * @param f The transformation function
204 * @return This instance for chaining
205 */
206 Builder<T> error(Function<Response, ? extends T> f);
207
208 /**
209 * Register a function to transform all non-'successful' (1xx, 3xx, 4xx, 5xx) HTTP responses.
210 *
211 * @param f The transformation function
212 * @return This instance for chaining
213 */
214 Builder<T> notSuccessful(Function<Response, ? extends T> f);
215
216 /**
217 * Register a function to transform all other HTTP responses (i.e. those not explicitly registered for).
218 *
219 * @param f The transformation function
220 * @return This instance for chaining
221 */
222 Builder<T> others(Function<Response, ? extends T> f);
223
224 /**
225 * Register a function to transform both of the following events:
226 * <ul>
227 * <li>Any value passed to <code>fail()</code></li>
228 * <li>Any value passed to others(), converted into an exception</li>
229 * </ul>
230 *
231 * @param f The transformation function
232 * @return This instance for chaining
233 */
234 Builder<T> otherwise(Function<Throwable, T> f);
235
236 /**
237 * Register a function to transform all completed (1xx, 2xx, 3xx, 4xx, and 5xx) HTTP responses.
238 *
239 * @param f The transformation function
240 * @return This instance for chaining
241 */
242 Builder<T> done(Function<Response, T> f);
243
244 // Exception Selectors
245
246 /**
247 * Register a function to transform exceptions thrown while executing the HTTP request.
248 *
249 * @param f The transformation function
250 * @return This instance for chaining
251 */
252 Builder<T> fail(Function<Throwable, ? extends T> f);
253 }
254 }