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