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