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