1 /*
2 * Copyright (C) 2013, 2017 Christian Halstrick <christian.halstrick@sap.com> and others
3 *
4 * This program and the accompanying materials are made available under the
5 * terms of the Eclipse Distribution License v. 1.0 which is available at
6 * https://www.eclipse.org/org/documents/edl-v10.php.
7 *
8 * SPDX-License-Identifier: BSD-3-Clause
9 */
10 package org.eclipse.jgit.transport.http;
11
12 import java.io.IOException;
13 import java.io.InputStream;
14 import java.io.OutputStream;
15 import java.net.HttpURLConnection;
16 import java.net.ProtocolException;
17 import java.net.URL;
18 import java.security.KeyManagementException;
19 import java.security.NoSuchAlgorithmException;
20 import java.security.SecureRandom;
21 import java.util.List;
22 import java.util.Map;
23
24 import javax.net.ssl.HostnameVerifier;
25 import javax.net.ssl.KeyManager;
26 import javax.net.ssl.TrustManager;
27
28 import org.eclipse.jgit.annotations.NonNull;
29
30 /**
31 * The interface of connections used during HTTP communication. This interface
32 * is that subset of the interface exposed by {@link java.net.HttpURLConnection}
33 * which is used by JGit
34 *
35 * @since 3.3
36 */
37 public interface HttpConnection {
38 /**
39 * @see HttpURLConnection#HTTP_OK
40 */
41 int HTTP_OK = java.net.HttpURLConnection.HTTP_OK;
42
43 /**
44 * @see HttpURLConnection#HTTP_NOT_AUTHORITATIVE
45 * @since 5.8
46 */
47 int HTTP_NOT_AUTHORITATIVE = java.net.HttpURLConnection.HTTP_NOT_AUTHORITATIVE;
48
49 /**
50 * @see HttpURLConnection#HTTP_MOVED_PERM
51 * @since 4.7
52 */
53 int HTTP_MOVED_PERM = java.net.HttpURLConnection.HTTP_MOVED_PERM;
54
55 /**
56 * @see HttpURLConnection#HTTP_MOVED_TEMP
57 * @since 4.9
58 */
59 int HTTP_MOVED_TEMP = java.net.HttpURLConnection.HTTP_MOVED_TEMP;
60
61 /**
62 * @see HttpURLConnection#HTTP_SEE_OTHER
63 * @since 4.9
64 */
65 int HTTP_SEE_OTHER = java.net.HttpURLConnection.HTTP_SEE_OTHER;
66
67 /**
68 * HTTP 1.1 additional "temporary redirect" status code; value = 307.
69 *
70 * @see #HTTP_MOVED_TEMP
71 * @see <a href="https://tools.ietf.org/html/rfc7231#section-6.4.7">RFC
72 * 7231, section 6.4.7: 307 Temporary Redirect</a>
73 * @since 4.9
74 */
75 int HTTP_11_MOVED_TEMP = 307;
76
77 /**
78 * HTTP 1.1 additional "permanent redirect" status code; value = 308.
79 *
80 * @see #HTTP_MOVED_TEMP
81 * @see <a href="https://tools.ietf.org/html/rfc7538#section-3">RFC 7538,
82 * section 3: 308 Permanent Redirect</a>
83 * @since 5.8
84 */
85 int HTTP_11_MOVED_PERM = 308;
86
87 /**
88 * @see HttpURLConnection#HTTP_NOT_FOUND
89 */
90 int HTTP_NOT_FOUND = java.net.HttpURLConnection.HTTP_NOT_FOUND;
91
92 /**
93 * @see HttpURLConnection#HTTP_UNAUTHORIZED
94 */
95 int HTTP_UNAUTHORIZED = java.net.HttpURLConnection.HTTP_UNAUTHORIZED;
96
97 /**
98 * @see HttpURLConnection#HTTP_FORBIDDEN
99 */
100 int HTTP_FORBIDDEN = java.net.HttpURLConnection.HTTP_FORBIDDEN;
101
102 /**
103 * Get response code
104 *
105 * @see HttpURLConnection#getResponseCode()
106 * @return the HTTP Status-Code, or -1
107 * @throws java.io.IOException
108 */
109 int getResponseCode() throws IOException;
110
111 /**
112 * Get URL
113 *
114 * @see HttpURLConnection#getURL()
115 * @return the URL.
116 */
117 URL getURL();
118
119 /**
120 * Get response message
121 *
122 * @see HttpURLConnection#getResponseMessage()
123 * @return the HTTP response message, or <code>null</code>
124 * @throws java.io.IOException
125 */
126 String getResponseMessage() throws IOException;
127
128 /**
129 * Get map of header fields
130 *
131 * @see HttpURLConnection#getHeaderFields()
132 * @return a Map of header fields
133 */
134 Map<String, List<String>> getHeaderFields();
135
136 /**
137 * Set request property
138 *
139 * @see HttpURLConnection#setRequestProperty(String, String)
140 * @param key
141 * the keyword by which the request is known (e.g., "
142 * <code>Accept</code>").
143 * @param value
144 * the value associated with it.
145 */
146 void setRequestProperty(String key, String value);
147
148 /**
149 * Set request method
150 *
151 * @see HttpURLConnection#setRequestMethod(String)
152 * @param method
153 * the HTTP method
154 * @exception ProtocolException
155 * if the method cannot be reset or if the requested method
156 * isn't valid for HTTP.
157 * @throws java.net.ProtocolException
158 * if any.
159 */
160 void setRequestMethod(String method)
161 throws ProtocolException;
162
163 /**
164 * Set if to use caches
165 *
166 * @see HttpURLConnection#setUseCaches(boolean)
167 * @param usecaches
168 * a <code>boolean</code> indicating whether or not to allow
169 * caching
170 */
171 void setUseCaches(boolean usecaches);
172
173 /**
174 * Set connect timeout
175 *
176 * @see HttpURLConnection#setConnectTimeout(int)
177 * @param timeout
178 * an <code>int</code> that specifies the connect timeout value
179 * in milliseconds
180 */
181 void setConnectTimeout(int timeout);
182
183 /**
184 * Set read timeout
185 *
186 * @see HttpURLConnection#setReadTimeout(int)
187 * @param timeout
188 * an <code>int</code> that specifies the timeout value to be
189 * used in milliseconds
190 */
191 void setReadTimeout(int timeout);
192
193 /**
194 * Get content type
195 *
196 * @see HttpURLConnection#getContentType()
197 * @return the content type of the resource that the URL references, or
198 * <code>null</code> if not known.
199 */
200 String getContentType();
201
202 /**
203 * Get input stream
204 *
205 * @see HttpURLConnection#getInputStream()
206 * @return an input stream that reads from this open connection.
207 * @exception IOException
208 * if an I/O error occurs while creating the input stream.
209 * @throws java.io.IOException
210 * if any.
211 */
212 InputStream getInputStream() throws IOException;
213
214 /**
215 * Get header field. According to
216 * {@link <a href="https://tools.ietf.org/html/rfc2616#section-4.2">RFC
217 * 2616</a>} header field names are case insensitive. Header fields defined
218 * as a comma separated list can have multiple header fields with the same
219 * field name. This method only returns one of these header fields. If you
220 * want the union of all values of all multiple header fields with the same
221 * field name then use {@link #getHeaderFields(String)}
222 *
223 * @see HttpURLConnection#getHeaderField(String)
224 * @param name
225 * the name of a header field.
226 * @return the value of the named header field, or <code>null</code> if
227 * there is no such field in the header.
228 */
229 String getHeaderField(@NonNull String name);
230
231 /**
232 * Get all values of given header field. According to
233 * {@link <a href="https://tools.ietf.org/html/rfc2616#section-4.2">RFC
234 * 2616</a>} header field names are case insensitive. Header fields defined
235 * as a comma separated list can have multiple header fields with the same
236 * field name. This method does not validate if the given header field is
237 * defined as a comma separated list.
238 *
239 * @param name
240 * the name of a header field.
241 * @return the list of values of the named header field
242 * @since 5.2
243 */
244 List<String> getHeaderFields(@NonNull String name);
245
246 /**
247 * Get content length
248 *
249 * @see HttpURLConnection#getContentLength()
250 * @return the content length of the resource that this connection's URL
251 * references, {@code -1} if the content length is not known, or if
252 * the content length is greater than Integer.MAX_VALUE.
253 */
254 int getContentLength();
255
256 /**
257 * Set whether or not to follow HTTP redirects.
258 *
259 * @see HttpURLConnection#setInstanceFollowRedirects(boolean)
260 * @param followRedirects
261 * a <code>boolean</code> indicating whether or not to follow
262 * HTTP redirects.
263 */
264 void setInstanceFollowRedirects(boolean followRedirects);
265
266 /**
267 * Set if to do output
268 *
269 * @see HttpURLConnection#setDoOutput(boolean)
270 * @param dooutput
271 * the new value.
272 */
273 void setDoOutput(boolean dooutput);
274
275 /**
276 * Set fixed length streaming mode
277 *
278 * @see HttpURLConnection#setFixedLengthStreamingMode(int)
279 * @param contentLength
280 * The number of bytes which will be written to the OutputStream.
281 */
282 void setFixedLengthStreamingMode(int contentLength);
283
284 /**
285 * Get output stream
286 *
287 * @see HttpURLConnection#getOutputStream()
288 * @return an output stream that writes to this connection.
289 * @throws java.io.IOException
290 */
291 OutputStream getOutputStream() throws IOException;
292
293 /**
294 * Set chunked streaming mode
295 *
296 * @see HttpURLConnection#setChunkedStreamingMode(int)
297 * @param chunklen
298 * The number of bytes to write in each chunk. If chunklen is
299 * less than or equal to zero, a default value will be used.
300 */
301 void setChunkedStreamingMode(int chunklen);
302
303 /**
304 * Get request method
305 *
306 * @see HttpURLConnection#getRequestMethod()
307 * @return the HTTP request method
308 */
309 String getRequestMethod();
310
311 /**
312 * Whether we use a proxy
313 *
314 * @see HttpURLConnection#usingProxy()
315 * @return a boolean indicating if the connection is using a proxy.
316 */
317 boolean usingProxy();
318
319 /**
320 * Connect
321 *
322 * @see HttpURLConnection#connect()
323 * @throws java.io.IOException
324 */
325 void connect() throws IOException;
326
327 /**
328 * Configure the connection so that it can be used for https communication.
329 *
330 * @param km
331 * the keymanager managing the key material used to authenticate
332 * the local SSLSocket to its peer
333 * @param tm
334 * the trustmanager responsible for managing the trust material
335 * that is used when making trust decisions, and for deciding
336 * whether credentials presented by a peer should be accepted.
337 * @param random
338 * the source of randomness for this generator or null. See
339 * {@link javax.net.ssl.SSLContext#init(KeyManager[], TrustManager[], SecureRandom)}
340 * @throws java.security.NoSuchAlgorithmException
341 * @throws java.security.KeyManagementException
342 */
343 void configure(KeyManager[] km, TrustManager[] tm,
344 SecureRandom random) throws NoSuchAlgorithmException,
345 KeyManagementException;
346
347 /**
348 * Set the {@link javax.net.ssl.HostnameVerifier} used during https
349 * communication
350 *
351 * @param hostnameverifier
352 * a {@link javax.net.ssl.HostnameVerifier} object.
353 * @throws java.security.NoSuchAlgorithmException
354 * @throws java.security.KeyManagementException
355 */
356 void setHostnameVerifier(HostnameVerifier hostnameverifier)
357 throws NoSuchAlgorithmException, KeyManagementException;
358 }