1 package com.atlassian.sal.api.net;
2
3 import java.util.List;
4 import java.util.Map;
5
6 /**
7 * Interface Request represents a request to retrieve data. To execute a request call {@link Request#execute(ResponseHandler)}.
8 *
9 * @param <T> the type of request used for method chaining
10 * @since 2.0
11 */
12 public interface Request<T extends Request<?, ?>, RESP extends Response> {
13 /**
14 * Represents type of network request
15 */
16 enum MethodType {
17 GET, POST, PUT, DELETE, HEAD, TRACE, OPTIONS
18 }
19
20 /**
21 * Setting connection timeout in milliseconds.
22 *
23 * @param connectionTimeout The timeout in milliseconds
24 * @return a reference to this object.
25 */
26 T setConnectionTimeout(int connectionTimeout);
27
28 /**
29 * Setting socket timeout in milliseconds.
30 *
31 * @param soTimeout the timeout in milliseconds
32 * @return a reference to this object.
33 */
34 T setSoTimeout(int soTimeout);
35
36 /**
37 * @param url the url to request
38 * @return a reference to this object.
39 */
40 T setUrl(String url);
41
42 /**
43 * Sets the body of the request. In default implementation only requests of type {@link MethodType#POST} and {@link MethodType#PUT} can have a request body.
44 *
45 * @param requestBody the body of the request
46 * @return a reference to this object.
47 */
48 T setRequestBody(String requestBody);
49
50 /**
51 * Sets the body of the request. In default implementation only requests of type {@link MethodType#POST} and {@link MethodType#PUT} can have a request body.
52 *
53 * @param requestBody the body of the request
54 * @param contentType the contentType of the request
55 * @return a reference to this object.
56 */
57 T setRequestBody(String requestBody, String contentType);
58
59 /**
60 * Sets file parts of the request. File parts can only be added if the request body is empty.
61 * Only requests of type {@link MethodType#POST} and {@link MethodType#PUT} can have file parts.
62 *
63 * @param files the file parts, cannot be null.
64 * @return a reference to this object.
65 * @throws IllegalArgumentException if the method of this request is not a POST or PUT or files is NULL.
66 * @throws IllegalStateException if the request body for this request has already been set.
67 * @since 2.6
68 */
69 T setFiles(List<RequestFilePart> files);
70
71 /**
72 * Set an entity as the request body
73 *
74 * @param entity the request entity to be marshalled, not null
75 * @return this Request object
76 */
77 T setEntity(Object entity);
78
79 /**
80 * Sets parameters of the request. In default implementation only requests of type {@link MethodType#POST} can have parameters.
81 * For other requests include parameters in url. This method accepts an even number of arguments, in form of name, value, name, value, name, value, etc
82 *
83 * @param params parameters of the request in as name, value pairs
84 * @return a reference to this object.
85 */
86 T addRequestParameters(String... params);
87
88 /**
89 * Adds basic authentication to the request.
90 *
91 * @param username The user name
92 * @param password The password
93 * @return a reference to this object.
94 */
95 T addBasicAuthentication(String hostname, String username, String password);
96
97 /**
98 * Adds the specified header to the request, not overwriting any previous value.
99 * Support for this operation is optional.
100 *
101 * @param headerName the header's name
102 * @param headerValue the header's value
103 * @return a reference to this object
104 * @see RequestFactory#supportsHeader()
105 */
106 T addHeader(String headerName, String headerValue);
107
108 /**
109 * Sets the specified header to the request, overwriting any previous value.
110 * Support for this operation is optional.
111 *
112 * @param headerName the header's name
113 * @param headerValue the header's value
114 * @return a reference to this object
115 * @see RequestFactory#supportsHeader()
116 */
117 T setHeader(String headerName, String headerValue);
118
119 /**
120 * Sets whether the request should transparently follow a redirect from the server. The
121 * default behavior is that when a response is received with a status code in the 300s, a new request
122 * is made using the location header of the response without notifying the client. Set this to false to
123 * turn this behavior off.
124 *
125 * @param follow set this to false to have the request not transparently follow redirects.
126 * @return a reference to this object.
127 */
128 T setFollowRedirects(boolean follow);
129
130 /**
131 * @return an immutable Map of headers added to the request so far
132 * @since 2.1
133 */
134 Map<String, List<String>> getHeaders();
135
136 /**
137 * Executes the request.
138 *
139 * @param responseHandler Callback handler of the response.
140 * @throws ResponseProtocolException If the server returned a malformed response
141 * @throws ResponseTimeoutException If a connection timeout or read timeout occurred
142 * @throws ResponseTransportException If an I/O error occurred in request transport
143 * @throws ResponseException For all errors not otherwise specified
144 */
145 void execute(ResponseHandler<? super RESP> responseHandler) throws ResponseException;
146
147 /**
148 * Executes a request and if response is successful, returns response as a string. @see {@link Response#getResponseBodyAsString()}
149 *
150 * @return response as String
151 * @throws ResponseStatusException If the server returned a response that contained an error code
152 * @throws ResponseProtocolException If the server returned a malformed response
153 * @throws ResponseTimeoutException If a connection timeout or read timeout occurred
154 * @throws ResponseTransportException If an I/O error occurred in request transport
155 * @throws ResponseException For all errors not otherwise specified
156 */
157 String execute() throws ResponseException;
158
159 /**
160 * Executes the request and returns a result value.
161 *
162 * @param responseHandler Callback handler of the response.
163 * @throws ResponseProtocolException If the server returned a malformed response
164 * @throws ResponseTimeoutException If a connection timeout or read timeout occurred
165 * @throws ResponseTransportException If an I/O error occurred in request transport
166 * @throws ResponseException For all errors not otherwise specified
167 * @since v2.2.0
168 */
169 <RET> RET executeAndReturn(ReturningResponseHandler<? super RESP, RET> responseHandler) throws ResponseException;
170 }