java.net.ProxySelector Maven / Gradle / Ivy
/* Licensed to the Apache Software Foundation (ASF) under one or more
* contributor license agreements. See the NOTICE file distributed with
* this work for additional information regarding copyright ownership.
* The ASF licenses this file to You under the Apache License, Version 2.0
* (the "License"); you may not use this file except in compliance with
* the License. You may obtain a copy of the License at
*
* http://www.apache.org/licenses/LICENSE-2.0
*
* Unless required by applicable law or agreed to in writing, software
* distributed under the License is distributed on an "AS IS" BASIS,
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
* See the License for the specific language governing permissions and
* limitations under the License.
*/
package java.net;
import java.io.IOException;
import java.util.List;
/**
* Selects the proxy server to use, if any, when connecting to a given URL.
*
* System Properties
* The default proxy selector is configured by system properties.
*
*
* Hostname patterns URL scheme property name description default ftp ftp.nonProxyHosts Hostname pattern for FTP servers to connect to
* directly (without a proxy). http http.nonProxyHosts Hostname pattern for HTTP servers to connect to
* directly (without a proxy). https https.nonProxyHosts Hostname pattern for HTTPS servers to connect
* to directly (without a proxy).
{@linkplain Proxy.Type#HTTP HTTP Proxies} URL scheme property name description default ftp ftp.proxyHost Hostname of the HTTP proxy server used for
* FTP requests. ftp.proxyPort Port number of the HTTP proxy server used for FTP
* requests. 80 http http.proxyHost Hostname of the HTTP proxy server used
* for HTTP requests. http.proxyPort Port number of the HTTP proxy server used for HTTP
* requests. 80 https https.proxyHost Hostname of the HTTP proxy server used
* for HTTPS requests. https.proxyPort Port number of the HTTP proxy server used for HTTPS
* requests. 443 ftp, http or https proxyHost Hostname of the HTTP proxy
* server used for FTP, HTTP and HTTPS requests. proxyPort Port number of the HTTP proxy server. 80 for FTP and HTTP
*
443 for HTTPS
{@linkplain Proxy.Type#SOCKS SOCKS
* Proxies} URL scheme property name description default ftp, http, https or socket socksProxyHost Hostname of the
* SOCKS proxy server used for FTP, HTTP, HTTPS and raw sockets.
Raw socket URLs are of the
* form socket://host:port socksProxyPort Port number of the SOCKS proxy server. 1080
*
* Hostname patterns specify which hosts should be connected to directly,
* ignoring any other proxy system properties. If the URL's host matches the
* corresponding hostname pattern, {@link Proxy#NO_PROXY} is returned.
*
*
The format of a hostname pattern is a list of hostnames that are
* separated by {@code |} and that use {@code *} as a wildcard. For example,
* setting the {@code http.nonProxyHosts} property to {@code
* *.android.com|*.kernel.org} will cause requests to {@code
* http://developer.android.com} to be made without a proxy.
*
*
The default proxy selector always returns exactly one proxy. If no proxy
* is applicable, {@link Proxy#NO_PROXY} is returned. If multiple proxies are
* applicable, such as when both the {@code proxyHost} and {@code
* socksProxyHost} system properties are set, the result is the property listed
* earliest in the table above.
*
*
Alternatives
* To request a URL without involving the system proxy selector, explicitly
* specify a proxy or {@link Proxy#NO_PROXY} using {@link
* URL#openConnection(Proxy)}.
*
*
Use {@link ProxySelector#setDefault(ProxySelector)} to install a custom
* proxy selector.
*/
public abstract class ProxySelector {
private static ProxySelector defaultSelector = new ProxySelectorImpl();
/**
* Returns the default proxy selector, or null if none exists.
*/
public static ProxySelector getDefault() {
return defaultSelector;
}
/**
* Sets the default proxy selector. If {@code selector} is null, the current
* proxy selector will be removed.
*/
public static void setDefault(ProxySelector selector) {
defaultSelector = selector;
}
/**
* Returns the proxy servers to use on connections to {@code uri}. This list
* will contain {@link Proxy#NO_PROXY} if no proxy server should be used.
*
* @throws IllegalArgumentException if {@code uri} is null.
*/
public abstract List select(URI uri);
/**
* Notifies this {@code ProxySelector} that a connection to the proxy server
* could not be established.
*
* @param uri the URI to which the connection could not be established.
* @param address the address of the proxy.
* @param failure the exception which was thrown during connection
* establishment.
* @throws IllegalArgumentException if any argument is null.
*/
public abstract void connectFailed(URI uri, SocketAddress address, IOException failure);
}