org.eclipse.jgit/org.eclipse.jgit/5.5.0.201909110433-r : org/eclipse/jgit/transport/http/HttpConnection.java

HttpConnection

http://www.eclipse.org/jgit//org.eclipse.jgit: Repository access and algorithms (Eclipse JGit Project)

Eclipse Distribution License (New BSD License)

Andrey Loskutov
Christian Halstrick
Dave Borowitz
David Pursehouse
Gunnar Wagenknecht
Jonathan Nieder
Jonathan Tan
Matthias Sohn
Sasa Zivkov
Terry Parker
Thomas Wolf

/*
 * Copyright (C) 2013, 2017 Christian Halstrick <christian.halstrick@sap.com>
 * and other copyright owners as documented in the project's IP log.
 *
 * This program and the accompanying materials are made available
 * under the terms of the Eclipse Distribution License v1.0 which
 * accompanies this distribution, is reproduced below, and is
 * available at http://www.eclipse.org/org/documents/edl-v10.php
 *
 * All rights reserved.
 *
 * Redistribution and use in source and binary forms, with or
 * without modification, are permitted provided that the following
 * conditions are met:
 *
 * - Redistributions of source code must retain the above copyright
 *   notice, this list of conditions and the following disclaimer.
 *
 * - Redistributions in binary form must reproduce the above
 *   copyright notice, this list of conditions and the following
 *   disclaimer in the documentation and/or other materials provided
 *   with the distribution.
 *
 * - Neither the name of the Eclipse Foundation, Inc. nor the
 *   names of its contributors may be used to endorse or promote
 *   products derived from this software without specific prior
 *   written permission.
 *
 * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND
 * CONTRIBUTORS "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES,
 * INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
 * OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
 * ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR
 * CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
 * SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT
 * NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
 * LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
 * CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT,
 * STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
 * ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF
 * ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
 */
package org.eclipse.jgit.transport.http;

import java.io.IOException;
import java.io.InputStream;
import java.io.OutputStream;
import java.net.HttpURLConnection;
import java.net.ProtocolException;
import java.net.URL;
import java.security.KeyManagementException;
import java.security.NoSuchAlgorithmException;
import java.security.SecureRandom;
import java.util.List;
import java.util.Map;

import javax.net.ssl.HostnameVerifier;
import javax.net.ssl.KeyManager;
import javax.net.ssl.TrustManager;

import org.eclipse.jgit.annotations.NonNull;

The interface of connections used during HTTP communication. This interface is that subset of the interface exposed by HttpURLConnection which is used by JGit 
Since: 3.3/**
 * The interface of connections used during HTTP communication. This interface
 * is that subset of the interface exposed by {@link java.net.HttpURLConnection}
 * which is used by JGit
 *
 * @since 3.3
 */
public interface HttpConnection {
	See Also: HTTP_OK.HTTP_OK/**
	 * @see HttpURLConnection#HTTP_OK
	 */
	int HTTP_OK = java.net.HttpURLConnection.HTTP_OK;

	See Also: HTTP_MOVED_PERM.HTTP_MOVED_PERM
Since: 4.7/**
	 * @see HttpURLConnection#HTTP_MOVED_PERM
	 * @since 4.7
	 */
	int HTTP_MOVED_PERM = java.net.HttpURLConnection.HTTP_MOVED_PERM;

	See Also: HTTP_MOVED_TEMP.HTTP_MOVED_TEMP
Since: 4.9/**
	 * @see HttpURLConnection#HTTP_MOVED_TEMP
	 * @since 4.9
	 */
	int HTTP_MOVED_TEMP = java.net.HttpURLConnection.HTTP_MOVED_TEMP;

	See Also: HTTP_SEE_OTHER.HTTP_SEE_OTHER
Since: 4.9/**
	 * @see HttpURLConnection#HTTP_SEE_OTHER
	 * @since 4.9
	 */
	int HTTP_SEE_OTHER = java.net.HttpURLConnection.HTTP_SEE_OTHER;

	HTTP 1.1 additional MOVED_TEMP status code; value = 307.
See Also: HTTP_MOVED_TEMP
Since: 4.9/**
	 * HTTP 1.1 additional MOVED_TEMP status code; value = 307.
	 *
	 * @see #HTTP_MOVED_TEMP
	 * @since 4.9
	 */
	int HTTP_11_MOVED_TEMP = 307;

	See Also: HTTP_NOT_FOUND.HTTP_NOT_FOUND/**
	 * @see HttpURLConnection#HTTP_NOT_FOUND
	 */
	int HTTP_NOT_FOUND = java.net.HttpURLConnection.HTTP_NOT_FOUND;

	See Also: HTTP_UNAUTHORIZED.HTTP_UNAUTHORIZED/**
	 * @see HttpURLConnection#HTTP_UNAUTHORIZED
	 */
	int HTTP_UNAUTHORIZED = java.net.HttpURLConnection.HTTP_UNAUTHORIZED;

	See Also: HTTP_FORBIDDEN.HTTP_FORBIDDEN/**
	 * @see HttpURLConnection#HTTP_FORBIDDEN
	 */
	int HTTP_FORBIDDEN = java.net.HttpURLConnection.HTTP_FORBIDDEN;

	Get response code
Throws: IOException – 
See Also: getResponseCode.getResponseCode()
Returns: the HTTP Status-Code, or -1/**
	 * Get response code
	 *
	 * @see HttpURLConnection#getResponseCode()
	 * @return the HTTP Status-Code, or -1
	 * @throws java.io.IOException
	 */
	int getResponseCode() throws IOException;

	Get URL
See Also: getURL.getURL()
Returns: the URL./**
	 * Get URL
	 *
	 * @see HttpURLConnection#getURL()
	 * @return the URL.
	 */
	URL getURL();

	Get response message
Throws: IOException – 
See Also: getResponseMessage.getResponseMessage()
Returns: the HTTP response message, or null/**
	 * Get response message
	 *
	 * @see HttpURLConnection#getResponseMessage()
	 * @return the HTTP response message, or <code>null</code>
	 * @throws java.io.IOException
	 */
	String getResponseMessage() throws IOException;

	Get map of header fields
See Also: getHeaderFields.getHeaderFields()
Returns: a Map of header fields/**
	 * Get map of header fields
	 *
	 * @see HttpURLConnection#getHeaderFields()
	 * @return a Map of header fields
	 */
	Map<String, List<String>> getHeaderFields();

	Set request property
Params: key – 
           the keyword by which the request is known (e.g., "
           Accept").
value – 
           the value associated with it.
See Also: setRequestProperty.setRequestProperty(String, String)/**
	 * Set request property
	 *
	 * @see HttpURLConnection#setRequestProperty(String, String)
	 * @param key
	 *            the keyword by which the request is known (e.g., "
	 *            <code>Accept</code>").
	 * @param value
	 *            the value associated with it.
	 */
	void setRequestProperty(String key, String value);

	Set request method
Params: method – 
           the HTTP method
Throws: ProtocolException – 
               if the method cannot be reset or if the requested method
               isn't valid for HTTP.
ProtocolException – 
            if any.
See Also: setRequestMethod.setRequestMethod(String)/**
	 * Set request method
	 *
	 * @see HttpURLConnection#setRequestMethod(String)
	 * @param method
	 *            the HTTP method
	 * @exception ProtocolException
	 *                if the method cannot be reset or if the requested method
	 *                isn't valid for HTTP.
	 * @throws java.net.ProtocolException
	 *             if any.
	 */
	void setRequestMethod(String method)
			throws ProtocolException;

	Set if to use caches
Params: usecaches – 
           a boolean indicating whether or not to allow
           caching
See Also: setUseCaches.setUseCaches(boolean)/**
	 * Set if to use caches
	 *
	 * @see HttpURLConnection#setUseCaches(boolean)
	 * @param usecaches
	 *            a <code>boolean</code> indicating whether or not to allow
	 *            caching
	 */
	void setUseCaches(boolean usecaches);

	Set connect timeout
Params: timeout – 
           an int that specifies the connect timeout value
           in milliseconds
See Also: setConnectTimeout.setConnectTimeout(int)/**
	 * Set connect timeout
	 *
	 * @see HttpURLConnection#setConnectTimeout(int)
	 * @param timeout
	 *            an <code>int</code> that specifies the connect timeout value
	 *            in milliseconds
	 */
	void setConnectTimeout(int timeout);

	Set read timeout
Params: timeout – 
           an int that specifies the timeout value to be
           used in milliseconds
See Also: setReadTimeout.setReadTimeout(int)/**
	 * Set read timeout
	 *
	 * @see HttpURLConnection#setReadTimeout(int)
	 * @param timeout
	 *            an <code>int</code> that specifies the timeout value to be
	 *            used in milliseconds
	 */
	void setReadTimeout(int timeout);

	Get content type
See Also: getContentType.getContentType()
Returns: the content type of the resource that the URL references, or
        null if not known./**
	 * Get content type
	 *
	 * @see HttpURLConnection#getContentType()
	 * @return the content type of the resource that the URL references, or
	 *         <code>null</code> if not known.
	 */
	String getContentType();

	Get input stream
Throws: IOException – 
               if an I/O error occurs while creating the input stream.
IOException – 
            if any.
See Also: getInputStream.getInputStream()
Returns: an input stream that reads from this open connection./**
	 * Get input stream
	 *
	 * @see HttpURLConnection#getInputStream()
	 * @return an input stream that reads from this open connection.
	 * @exception IOException
	 *                if an I/O error occurs while creating the input stream.
	 * @throws java.io.IOException
	 *             if any.
	 */
	InputStream getInputStream() throws IOException;

	Get header field. According to <a href="https://tools.ietf.org/html/rfc2616#section-4.2">RFC
	 * 2616</a> header field names are case insensitive. Header fields defined as a comma separated list can have multiple header fields with the same field name. This method only returns one of these header fields. If you want the union of all values of all multiple header fields with the same field name then use getHeaderFields(String) 
Params: name – 
           the name of a header field.
See Also: URLConnection.getHeaderField(String)
Returns: the value of the named header field, or null if
        there is no such field in the header./**
	 * Get header field. According to
	 * {@link <a href="https://tools.ietf.org/html/rfc2616#section-4.2">RFC
	 * 2616</a>} header field names are case insensitive. Header fields defined
	 * as a comma separated list can have multiple header fields with the same
	 * field name. This method only returns one of these header fields. If you
	 * want the union of all values of all multiple header fields with the same
	 * field name then use {@link #getHeaderFields(String)}
	 *
	 * @see HttpURLConnection#getHeaderField(String)
	 * @param name
	 *            the name of a header field.
	 * @return the value of the named header field, or <code>null</code> if
	 *         there is no such field in the header.
	 */
	String getHeaderField(@NonNull String name);

	Get all values of given header field. According to <a href="https://tools.ietf.org/html/rfc2616#section-4.2">RFC
	 * 2616</a> header field names are case insensitive. Header fields defined as a comma separated list can have multiple header fields with the same field name. This method does not validate if the given header field is defined as a comma separated list. 
Params: name – 
           the name of a header field.
Returns: the list of values of the named header field
Since: 5.2/**
	 * Get all values of given header field. According to
	 * {@link <a href="https://tools.ietf.org/html/rfc2616#section-4.2">RFC
	 * 2616</a>} header field names are case insensitive. Header fields defined
	 * as a comma separated list can have multiple header fields with the same
	 * field name. This method does not validate if the given header field is
	 * defined as a comma separated list.
	 *
	 * @param name
	 *            the name of a header field.
	 * @return the list of values of the named header field
	 * @since 5.2
	 */
	List<String> getHeaderFields(@NonNull String name);

	Get content length
See Also: getContentLength.getContentLength()
Returns: the content length of the resource that this connection's URL references, -1 if the content length is not known, or if the content length is greater than Integer.MAX_VALUE./**
	 * Get content length
	 *
	 * @see HttpURLConnection#getContentLength()
	 * @return the content length of the resource that this connection's URL
	 *         references, {@code -1} if the content length is not known, or if
	 *         the content length is greater than Integer.MAX_VALUE.
	 */
	int getContentLength();

	Set whether or not to follow HTTP redirects.
Params: followRedirects – 
           a boolean indicating whether or not to follow
           HTTP redirects.
See Also: setInstanceFollowRedirects.setInstanceFollowRedirects(boolean)/**
	 * Set whether or not to follow HTTP redirects.
	 *
	 * @see HttpURLConnection#setInstanceFollowRedirects(boolean)
	 * @param followRedirects
	 *            a <code>boolean</code> indicating whether or not to follow
	 *            HTTP redirects.
	 */
	void setInstanceFollowRedirects(boolean followRedirects);

	Set if to do output
Params: dooutput – 
           the new value.
See Also: setDoOutput.setDoOutput(boolean)/**
	 * Set if to do output
	 *
	 * @see HttpURLConnection#setDoOutput(boolean)
	 * @param dooutput
	 *            the new value.
	 */
	void setDoOutput(boolean dooutput);

	Set fixed length streaming mode
Params: contentLength – 
           The number of bytes which will be written to the OutputStream.
See Also: setFixedLengthStreamingMode.setFixedLengthStreamingMode(int)/**
	 * Set fixed length streaming mode
	 *
	 * @see HttpURLConnection#setFixedLengthStreamingMode(int)
	 * @param contentLength
	 *            The number of bytes which will be written to the OutputStream.
	 */
	void setFixedLengthStreamingMode(int contentLength);

	Get output stream
Throws: IOException – 
See Also: getOutputStream.getOutputStream()
Returns: an output stream that writes to this connection./**
	 * Get output stream
	 *
	 * @see HttpURLConnection#getOutputStream()
	 * @return an output stream that writes to this connection.
	 * @throws java.io.IOException
	 */
	OutputStream getOutputStream() throws IOException;

	Set chunked streaming mode
Params: chunklen – 
           The number of bytes to write in each chunk. If chunklen is
           less than or equal to zero, a default value will be used.
See Also: setChunkedStreamingMode.setChunkedStreamingMode(int)/**
	 * Set chunked streaming mode
	 *
	 * @see HttpURLConnection#setChunkedStreamingMode(int)
	 * @param chunklen
	 *            The number of bytes to write in each chunk. If chunklen is
	 *            less than or equal to zero, a default value will be used.
	 */
	void setChunkedStreamingMode(int chunklen);

	Get request method
See Also: getRequestMethod.getRequestMethod()
Returns: the HTTP request method/**
	 * Get request method
	 *
	 * @see HttpURLConnection#getRequestMethod()
	 * @return the HTTP request method
	 */
	String getRequestMethod();

	Whether we use a proxy
See Also: usingProxy.usingProxy()
Returns: a boolean indicating if the connection is using a proxy./**
	 * Whether we use a proxy
	 *
	 * @see HttpURLConnection#usingProxy()
	 * @return a boolean indicating if the connection is using a proxy.
	 */
	boolean usingProxy();

	Connect
Throws: IOException – 
See Also: connect.connect()/**
	 * Connect
	 *
	 * @see HttpURLConnection#connect()
	 * @throws java.io.IOException
	 */
	void connect() throws IOException;

	Configure the connection so that it can be used for https communication.
Params: km – 
           the keymanager managing the key material used to authenticate
           the local SSLSocket to its peer
tm – 
           the trustmanager responsible for managing the trust material
           that is used when making trust decisions, and for deciding
           whether credentials presented by a peer should be accepted.
random –  the source of randomness for this generator or null. See SSLContext.init(KeyManager[], TrustManager[], SecureRandom)
Throws: NoSuchAlgorithmException – 
KeyManagementException – /**
	 * Configure the connection so that it can be used for https communication.
	 *
	 * @param km
	 *            the keymanager managing the key material used to authenticate
	 *            the local SSLSocket to its peer
	 * @param tm
	 *            the trustmanager responsible for managing the trust material
	 *            that is used when making trust decisions, and for deciding
	 *            whether credentials presented by a peer should be accepted.
	 * @param random
	 *            the source of randomness for this generator or null. See
	 *            {@link javax.net.ssl.SSLContext#init(KeyManager[], TrustManager[], SecureRandom)}
	 * @throws java.security.NoSuchAlgorithmException
	 * @throws java.security.KeyManagementException
	 */
	void configure(KeyManager[] km, TrustManager[] tm,
			SecureRandom random) throws NoSuchAlgorithmException,
			KeyManagementException;

	Set the HostnameVerifier used during https communication 
Params: hostnameverifier –  a HostnameVerifier object.
Throws: NoSuchAlgorithmException – 
KeyManagementException – /**
	 * Set the {@link javax.net.ssl.HostnameVerifier} used during https
	 * communication
	 *
	 * @param hostnameverifier
	 *            a {@link javax.net.ssl.HostnameVerifier} object.
	 * @throws java.security.NoSuchAlgorithmException
	 * @throws java.security.KeyManagementException
	 */
	void setHostnameVerifier(HostnameVerifier hostnameverifier)
			throws NoSuchAlgorithmException, KeyManagementException;
}

Throws:	IOException –
See Also:	getResponseCode.getResponseCode()
Returns:	the HTTP Status-Code, or -1

See Also:	getHeaderFields.getHeaderFields()
Returns:	a Map of header fields

Params:	key – the keyword by which the request is known (e.g., " `Accept`"). value – the value associated with it.
See Also:	setRequestProperty.setRequestProperty(String, String)

Params:	method – the HTTP method
Throws:	ProtocolException – if the method cannot be reset or if the requested method isn't valid for HTTP. ProtocolException – if any.
See Also:	setRequestMethod.setRequestMethod(String)

Params:	usecaches – a `boolean` indicating whether or not to allow caching
See Also:	setUseCaches.setUseCaches(boolean)

Params:	timeout – an `int` that specifies the connect timeout value in milliseconds
See Also:	setConnectTimeout.setConnectTimeout(int)

Params:	timeout – an `int` that specifies the timeout value to be used in milliseconds
See Also:	setReadTimeout.setReadTimeout(int)

See Also:	getContentType.getContentType()
Returns:	the content type of the resource that the URL references, or `null` if not known.

Throws:	IOException – if an I/O error occurs while creating the input stream. IOException – if any.
See Also:	getInputStream.getInputStream()
Returns:	an input stream that reads from this open connection.

Params:	name – the name of a header field.
See Also:	URLConnection.getHeaderField(String)
Returns:	the value of the named header field, or `null` if there is no such field in the header.

See Also:	getContentLength.getContentLength()
Returns:	the content length of the resource that this connection's URL references, `-1` if the content length is not known, or if the content length is greater than Integer.MAX_VALUE.

Params:	followRedirects – a `boolean` indicating whether or not to follow HTTP redirects.
See Also:	setInstanceFollowRedirects.setInstanceFollowRedirects(boolean)

Params:	dooutput – the new value.
See Also:	setDoOutput.setDoOutput(boolean)

Params:	contentLength – The number of bytes which will be written to the OutputStream.
See Also:	setFixedLengthStreamingMode.setFixedLengthStreamingMode(int)

Params:	chunklen – The number of bytes to write in each chunk. If chunklen is less than or equal to zero, a default value will be used.
See Also:	setChunkedStreamingMode.setChunkedStreamingMode(int)

See Also:	getRequestMethod.getRequestMethod()
Returns:	the HTTP request method

See Also:	usingProxy.usingProxy()
Returns:	a boolean indicating if the connection is using a proxy.

Params:	hostnameverifier – a `HostnameVerifier` object.
Throws:	NoSuchAlgorithmException – KeyManagementException –

/

org.eclipse.jgit/ org.eclipse.jgit/ 5.5.0.201909110433-r/ org/eclipse/jgit/transport/http/HttpConnection.java