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