hunt.http.client.Call source code

1 module hunt.http.client.Call;
2 
3 import hunt.Exceptions;
4 
5 import hunt.http.client.HttpClientResponse;
6 import hunt.http.client.HttpClientRequest;
7 
8 
9 
10 /**
11  * A call is a request that has been prepared for execution. A call can be canceled. As this object
12  * represents a single request/response pair (stream), it cannot be executed twice.
13  */
14 interface Call {
15     /** Returns the original request that initiated this call. */
16     Request request();
17 
18     /**
19      * Invokes the request immediately, and blocks until the response can be processed or is in
20      * error.
21      *
22      * <p>To avoid leaking resources callers should close the {@link Response} which in turn will
23      * close the underlying {@link ResponseBody}.
24      *
25      * <pre>{@code
26      *
27      *   // ensure the response (and underlying response body) is closed
28      *   try (Response response = client.newCall(request).execute()) {
29      *     ...
30      *   }
31      *
32      * }</pre>
33      *
34      * <p>The caller may read the response body with the response's {@link Response#body} method. To
35      * avoid leaking resources callers must {@linkplain ResponseBody close the response body} or the
36      * Response.
37      *
38      * <p>Note that transport-layer success (receiving a HTTP response code, headers and body) does
39      * not necessarily indicate application-layer success: {@code response} may still indicate an
40      * unhappy HTTP response code like 404 or 500.
41      *
42      * @throws IOException if the request could not be executed due to cancellation, a connectivity
43      * problem or timeout. Because networks can fail during an exchange, it is possible that the
44      * remote server accepted the request before the failure.
45      * @throws IllegalStateException when the call has already been executed.
46      */
47     Response execute();
48 
49     /**
50      * Schedules the request to be executed at some point in the future.
51      *
52      * <p>The {@link OkHttpClient#dispatcher dispatcher} defines when the request will run: usually
53      * immediately unless there are several other requests currently being executed.
54      *
55      * <p>This client will later call back {@code responseCallback} with either an HTTP response or a
56      * failure exception.
57      *
58      * @throws IllegalStateException when the call has already been executed.
59      */
60     void enqueue(Callback responseCallback);
61 
62     /** Cancels the request, if possible. Requests that are already complete cannot be canceled. */
63     void cancel();
64 
65     /**
66      * Returns true if this call has been either {@linkplain #execute() executed} or {@linkplain
67      * #enqueue(Callback) enqueued}. It is an error to execute a call more than once.
68      */
69     bool isExecuted();
70 
71     bool isCanceled();
72 
73     /**
74      * Returns a timeout that spans the entire call: resolving DNS, connecting, writing the request
75      * body, server processing, and reading the response body. If the call requires redirects or
76      * retries all must complete within one timeout period.
77      *
78      * <p>Configure the client's default timeout with {@link OkHttpClient.Builder#callTimeout}.
79      */
80 //   Timeout timeout();
81 
82     /**
83      * Create a new, identical call to this one which can be enqueued or executed even if this call
84      * has already been.
85      */
86 //   Call clone();
87 
88 
89 }
90 
91 interface CallFactory {
92         Call newCall(Request request);
93 }
94 
95 
96 interface Callback {
97     /**
98      * Called when the request could not be executed due to cancellation, a connectivity problem or
99      * timeout. Because networks can fail during an exchange, it is possible that the remote server
100      * accepted the request before the failure.
101      */
102     void onFailure(Call call, IOException e);
103 
104     /**
105      * Called when the HTTP response was successfully returned by the remote server. The callback may
106      * proceed to read the response body with {@link Response#body}. The response is still live until
107      * its response body is {@linkplain ResponseBody closed}. The recipient of the callback may
108      * consume the response body on another thread.
109      *
110      * <p>Note that transport-layer success (receiving a HTTP response code, headers and body) does
111      * not necessarily indicate application-layer success: {@code response} may still indicate an
112      * unhappy HTTP response code like 404 or 500.
113      */
114     void onResponse(Call call, Response response);
115 }