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