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 * Set an entity as the request body
56 *
57 * @param entity the request entity to be marshalled, not null
58 * @return this Request object
59 */
60 T setEntity(Object entity);
61
62 /**
63 * 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.
64 *
65 * @param contentType the contentType of the request
66 * @return a reference to this object.
67 */
68 T setRequestContentType(String contentType);
69
70 /**
71 * Sets parameters of the request. In default implementation only requests of type {@link MethodType#POST} can have parameters.
72 * 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
73 *
74 * @param params parameters of the request in as name, value pairs
75 * @return a reference to this object.
76 */
77 T addRequestParameters(String... params);
78
79 /**
80 * Adds generic Authenticator to the request.
81 *
82 * @param authenticator the authenticator to use for authentication
83 * @return a reference to this object.
84 */
85 T addAuthentication(Authenticator authenticator);
86
87 /**
88 * Adds TrustedTokenAuthentication to the request. Trusted token authenticator uses current user to make a trusted application call.
89 *
90 * @return a reference to this object.
91 */
92 T addTrustedTokenAuthentication();
93
94 /**
95 * Adds TrustedTokenAuthentication to the request. Trusted token authenticator uses the passed user to make a trusted application call.
96 *
97 * @param username The user to make the request with
98 * @return this
99 */
100 T addTrustedTokenAuthentication(String username);
101
102 /**
103 * Adds basic authentication to the request.
104 *
105 * @param username The user name
106 * @param password The password
107 * @return a reference to this object.
108 */
109 T addBasicAuthentication(String username, String password);
110
111 /**
112 * Adds seraph authentication to the request.
113 *
114 * @param username The user name
115 * @param password The password
116 * @return a reference to this object.
117 */
118 T addSeraphAuthentication(String username, String password);
119
120 /**
121 * Adds the specified header to the request, not overwriting any previous value.
122 * Support for this operation is optional.
123 *
124 * @param headerName the header's name
125 * @param headerValue the header's value
126 * @return a reference to this object
127 * @see RequestFactory#supportsHeader()
128 */
129 T addHeader(String headerName, String headerValue);
130
131 /**
132 * Sets the specified header to the request, overwriting any previous value.
133 * Support for this operation is optional.
134 *
135 * @param headerName the header's name
136 * @param headerValue the header's value
137 * @return a reference to this object
138 * @see RequestFactory#supportsHeader()
139 */
140 T setHeader(String headerName, String headerValue);
141
142 /**
143 * Sets whether the request should transparently follow a redirect from the server. The
144 * default behavior is that when a response is received with a status code in the 300s, a new request
145 * is made using the location header of the response without notifying the client. Set this to false to
146 * turn this behavior off.
147 *
148 * @param follow set this to false to have the request not transparently follow redirects.
149 * @return a reference to this object.
150 */
151 T setFollowRedirects(boolean follow);
152
153 /**
154 * @return an immutable Map of headers added to the request so far
155 * @since 2.1
156 */
157 Map<String, List<String>> getHeaders();
158
159 /**
160 * Executes the request.
161 *
162 * @param responseHandler Callback handler of the response.
163 * @throws ResponseException If the response cannot be retrieved
164 */
165 void execute(ResponseHandler<RESP> responseHandler) throws ResponseException;
166
167 /**
168 * Executes a request and if response is successful, returns response as a string. @see {@link Response#getResponseBodyAsString()}
169 *
170 * @return response as String
171 * @throws ResponseException If the response cannot be retrieved
172 */
173 String execute() throws ResponseException;
174
175 /**
176 * Executes the request and returns a result value.
177 *
178 * @param responseHandler Callback handler of the response.
179 * @throws ResponseException If the response cannot be retrieved
180 * @since v2.2.0
181 */
182 <RET> RET executeAndReturn(ReturningResponseHandler<RESP, RET> responseHandler) throws ResponseException;
183 }