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 /**
62 * The interface of connections used during HTTP communication. This interface
63 * is that subset of the interface exposed by {@link java.net.HttpURLConnection}
64 * which is used by JGit
65 *
66 * @since 3.3
67 */
68 public interface HttpConnection {
69 /**
70 * @see HttpURLConnection#HTTP_OK
71 */
72 public static final int HTTP_OK = java.net.HttpURLConnection.HTTP_OK;
73
74 /**
75 * @see HttpURLConnection#HTTP_MOVED_PERM
76 * @since 4.7
77 */
78 public static final int HTTP_MOVED_PERM = java.net.HttpURLConnection.HTTP_MOVED_PERM;
79
80 /**
81 * @see HttpURLConnection#HTTP_MOVED_TEMP
82 * @since 4.9
83 */
84 public static final int HTTP_MOVED_TEMP = java.net.HttpURLConnection.HTTP_MOVED_TEMP;
85
86 /**
87 * @see HttpURLConnection#HTTP_SEE_OTHER
88 * @since 4.9
89 */
90 public static final int HTTP_SEE_OTHER = java.net.HttpURLConnection.HTTP_SEE_OTHER;
91
92 /**
93 * HTTP 1.1 additional MOVED_TEMP status code; value = 307.
94 *
95 * @see #HTTP_MOVED_TEMP
96 * @since 4.9
97 */
98 public static final int HTTP_11_MOVED_TEMP = 307;
99
100 /**
101 * @see HttpURLConnection#HTTP_NOT_FOUND
102 */
103 public static final int HTTP_NOT_FOUND = java.net.HttpURLConnection.HTTP_NOT_FOUND;
104
105 /**
106 * @see HttpURLConnection#HTTP_UNAUTHORIZED
107 */
108 public static final int HTTP_UNAUTHORIZED = java.net.HttpURLConnection.HTTP_UNAUTHORIZED;
109
110 /**
111 * @see HttpURLConnection#HTTP_FORBIDDEN
112 */
113 public static final int HTTP_FORBIDDEN = java.net.HttpURLConnection.HTTP_FORBIDDEN;
114
115 /**
116 * Get response code
117 *
118 * @see HttpURLConnection#getResponseCode()
119 * @return the HTTP Status-Code, or -1
120 * @throws java.io.IOException
121 */
122 public int getResponseCode() throws IOException;
123
124 /**
125 * Get URL
126 *
127 * @see HttpURLConnection#getURL()
128 * @return the URL.
129 */
130 public URL getURL();
131
132 /**
133 * Get response message
134 *
135 * @see HttpURLConnection#getResponseMessage()
136 * @return the HTTP response message, or <code>null</code>
137 * @throws java.io.IOException
138 */
139 public String getResponseMessage() throws IOException;
140
141 /**
142 * Get list of header fields
143 *
144 * @see HttpURLConnection#getHeaderFields()
145 * @return a Map of header fields
146 */
147 public Map<String, List<String>> getHeaderFields();
148
149 /**
150 * Set request property
151 *
152 * @see HttpURLConnection#setRequestProperty(String, String)
153 * @param key
154 * the keyword by which the request is known (e.g., "
155 * <code>Accept</code>").
156 * @param value
157 * the value associated with it.
158 */
159 public void setRequestProperty(String key, String value);
160
161 /**
162 * Set request method
163 *
164 * @see HttpURLConnection#setRequestMethod(String)
165 * @param method
166 * the HTTP method
167 * @exception ProtocolException
168 * if the method cannot be reset or if the requested method
169 * isn't valid for HTTP.
170 * @throws java.net.ProtocolException
171 * if any.
172 */
173 public void setRequestMethod(String method)
174 throws ProtocolException;
175
176 /**
177 * Set if to use caches
178 *
179 * @see HttpURLConnection#setUseCaches(boolean)
180 * @param usecaches
181 * a <code>boolean</code> indicating whether or not to allow
182 * caching
183 */
184 public void setUseCaches(boolean usecaches);
185
186 /**
187 * Set connect timeout
188 *
189 * @see HttpURLConnection#setConnectTimeout(int)
190 * @param timeout
191 * an <code>int</code> that specifies the connect timeout value
192 * in milliseconds
193 */
194 public void setConnectTimeout(int timeout);
195
196 /**
197 * Set read timeout
198 *
199 * @see HttpURLConnection#setReadTimeout(int)
200 * @param timeout
201 * an <code>int</code> that specifies the timeout value to be
202 * used in milliseconds
203 */
204 public void setReadTimeout(int timeout);
205
206 /**
207 * Get content type
208 *
209 * @see HttpURLConnection#getContentType()
210 * @return the content type of the resource that the URL references, or
211 * <code>null</code> if not known.
212 */
213 public String getContentType();
214
215 /**
216 * Get input stream
217 *
218 * @see HttpURLConnection#getInputStream()
219 * @return an input stream that reads from this open connection.
220 * @exception IOException
221 * if an I/O error occurs while creating the input stream.
222 * @throws java.io.IOException
223 * if any.
224 */
225 public InputStream getInputStream() throws IOException;
226
227 /**
228 * Get header field
229 *
230 * @see HttpURLConnection#getHeaderField(String)
231 * @param name
232 * the name of a header field.
233 * @return the value of the named header field, or <code>null</code> if
234 * there is no such field in the header.
235 */
236 public String getHeaderField(String name);
237
238 /**
239 * Get content length
240 *
241 * @see HttpURLConnection#getContentLength()
242 * @return the content length of the resource that this connection's URL
243 * references, {@code -1} if the content length is not known, or if
244 * the content length is greater than Integer.MAX_VALUE.
245 */
246 public int getContentLength();
247
248 /**
249 * Set whether or not to follow HTTP redirects.
250 *
251 * @see HttpURLConnection#setInstanceFollowRedirects(boolean)
252 * @param followRedirects
253 * a <code>boolean</code> indicating whether or not to follow
254 * HTTP redirects.
255 */
256 public void setInstanceFollowRedirects(boolean followRedirects);
257
258 /**
259 * Set if to do output
260 *
261 * @see HttpURLConnection#setDoOutput(boolean)
262 * @param dooutput
263 * the new value.
264 */
265 public void setDoOutput(boolean dooutput);
266
267 /**
268 * Set fixed length streaming mode
269 *
270 * @see HttpURLConnection#setFixedLengthStreamingMode(int)
271 * @param contentLength
272 * The number of bytes which will be written to the OutputStream.
273 */
274 public void setFixedLengthStreamingMode(int contentLength);
275
276 /**
277 * Get output stream
278 *
279 * @see HttpURLConnection#getOutputStream()
280 * @return an output stream that writes to this connection.
281 * @throws java.io.IOException
282 */
283 public OutputStream getOutputStream() throws IOException;
284
285 /**
286 * Set chunked streaming mode
287 *
288 * @see HttpURLConnection#setChunkedStreamingMode(int)
289 * @param chunklen
290 * The number of bytes to write in each chunk. If chunklen is
291 * less than or equal to zero, a default value will be used.
292 */
293 public void setChunkedStreamingMode(int chunklen);
294
295 /**
296 * Get request method
297 *
298 * @see HttpURLConnection#getRequestMethod()
299 * @return the HTTP request method
300 */
301 public String getRequestMethod();
302
303 /**
304 * Whether we use a proxy
305 *
306 * @see HttpURLConnection#usingProxy()
307 * @return a boolean indicating if the connection is using a proxy.
308 */
309 public boolean usingProxy();
310
311 /**
312 * Connect
313 *
314 * @see HttpURLConnection#connect()
315 * @throws java.io.IOException
316 */
317 public void connect() throws IOException;
318
319 /**
320 * Configure the connection so that it can be used for https communication.
321 *
322 * @param km
323 * the keymanager managing the key material used to authenticate
324 * the local SSLSocket to its peer
325 * @param tm
326 * the trustmanager responsible for managing the trust material
327 * that is used when making trust decisions, and for deciding
328 * whether credentials presented by a peer should be accepted.
329 * @param random
330 * the source of randomness for this generator or null. See
331 * {@link javax.net.ssl.SSLContext#init(KeyManager[], TrustManager[], SecureRandom)}
332 * @throws java.security.NoSuchAlgorithmException
333 * @throws java.security.KeyManagementException
334 */
335 public void configure(KeyManager[] km, TrustManager[] tm,
336 SecureRandom random) throws NoSuchAlgorithmException,
337 KeyManagementException;
338
339 /**
340 * Set the {@link javax.net.ssl.HostnameVerifier} used during https
341 * communication
342 *
343 * @param hostnameverifier
344 * a {@link javax.net.ssl.HostnameVerifier} object.
345 * @throws java.security.NoSuchAlgorithmException
346 * @throws java.security.KeyManagementException
347 */
348 public void setHostnameVerifier(HostnameVerifier hostnameverifier)
349 throws NoSuchAlgorithmException, KeyManagementException;
350 }