1 package com.atlassian.httpclient.api;
2
3 import java.net.URI;
4 import java.util.regex.Pattern;
5
6 /**
7 * A service providing asynchronous HTTP request creation and execution.
8 * <p>
9 * To use this service, first create a {@link Request} instance with one of the <code>newRequest()</code>
10 * methods. Then, populate the request with any additional options, and finally call one of its HTTP verb
11 * methods to execute the request. See the {@link Request} class for finer control over the construction
12 * of the HTTP requests to be executed.
13 */
14 public interface HttpClient {
15 /**
16 * Constructs a new request. Sets the accept property to a default of "*/*".
17 *
18 * @return The new request object
19 */
20 Request.Builder newRequest();
21
22 /**
23 * Constructs a new Request with the specified URI. Sets the accept property to a
24 * default of "*/*".
25 *
26 * @param uri The endpoint URI for this request
27 * @return The new request object
28 */
29 Request.Builder newRequest(URI uri);
30
31 /**
32 * Constructs a new Request with the specified URI. Sets the accept property to a
33 * default of "*/*".
34 *
35 * @param uri The endpoint URI for this request
36 * @return The new request object
37 */
38 Request.Builder newRequest(String uri);
39
40 /**
41 * Constructs a new Request with the specified URI, contentType, and entity. Sets the
42 * accept property to a default of "*/*", and the content charset property to
43 * "UTF-8". This should only be used for sending textual content types, typically via
44 * the POST or PUT HTTP methods.
45 *
46 * @param uri The endpoint URI for this request
47 * @param contentType A textual IANA media type
48 * @param entity A string entity to send as this request's message body
49 * @return The new request object
50 */
51 Request.Builder newRequest(URI uri, String contentType, String entity);
52
53 /**
54 * Constructs a new Request with the specified URI, contentType, and entity. Sets the
55 * accept property to a default of "*/*", and the content charset property to
56 * "UTF-8". This should only be used for sending textual content types, typically via
57 * the POST or PUT HTTP methods.
58 *
59 * @param uri The endpoint URI for this request
60 * @param contentType A textual IANA media type
61 * @param entity A string entity to send as this request's message body
62 * @return The new request object
63 */
64 Request.Builder newRequest(String uri, String contentType, String entity);
65
66 /**
67 * Flush the cache entries by matching the URI using a regular expression
68 *
69 * @param uriPattern The regular expression to match
70 */
71 void flushCacheByUriPattern(Pattern uriPattern);
72
73 <A> ResponseTransformation.Builder<A> transformation();
74
75 abstract ResponsePromise execute(Request request);
76
77 }