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