1 /* Licensed to the Apache Software Foundation (ASF) under one or more 2 * contributor license agreements. See the NOTICE file distributed with 3 * this work for additional information regarding copyright ownership. 4 * The ASF licenses this file to You under the Apache License, Version 2.0 5 * (the "License"); you may not use this file except in compliance with 6 * the License. You may obtain a copy of the License at 7 * 8 * http://www.apache.org/licenses/LICENSE-2.0 9 * 10 * Unless required by applicable law or agreed to in writing, software 11 * distributed under the License is distributed on an "AS IS" BASIS, 12 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 13 * See the License for the specific language governing permissions and 14 * limitations under the License. 15 */ 16 17 package java.net; 18 19 import java.io.IOException; 20 import java.util.List; 21 22 /** 23 * Selects the proxy server to use, if any, when connecting to a given URL. 24 * 25 * <h3>System Properties</h3> 26 * <p>The default proxy selector is configured by system properties. 27 * 28 * <table border="1" cellpadding="3" cellspacing="0"> 29 * <tr class="TableHeadingColor"><th colspan="4">Hostname patterns</th></tr> 30 * <tr><th>URL scheme</th><th>property name</th><th>description</th><th>default</th></tr> 31 * <tr><td>ftp</td><td>ftp.nonProxyHosts</td><td>Hostname pattern for FTP servers to connect to 32 * directly (without a proxy).</td><td></td></tr> 33 * <tr><td>http</td><td>http.nonProxyHosts</td><td>Hostname pattern for HTTP servers to connect to 34 * directly (without a proxy).</td><td></td></tr> 35 * <tr><td>https</td><td>https.nonProxyHosts</td><td>Hostname pattern for HTTPS servers to connect 36 * to directly (without a proxy).</td><td></td></tr> 37 * <tr><td colspan="4"><br></td></tr> 38 * 39 * <tr class="TableHeadingColor"><th colspan="4">{@linkplain Proxy.Type#HTTP HTTP Proxies}</th></tr> 40 * <tr><th>URL scheme</th><th>property name</th><th>description</th><th>default</th></tr> 41 * <tr><td rowspan="2">ftp</td><td>ftp.proxyHost</td><td>Hostname of the HTTP proxy server used for 42 * FTP requests.</td><td></td></tr> 43 * <tr><td>ftp.proxyPort</td><td>Port number of the HTTP proxy server used for FTP 44 * requests.</td><td>80</td></tr> 45 * <tr><td rowspan="2">http</td><td>http.proxyHost</td><td>Hostname of the HTTP proxy server used 46 * for HTTP requests.</td><td></td></tr> 47 * <tr><td>http.proxyPort</td><td>Port number of the HTTP proxy server used for HTTP 48 * requests.</td><td>80</td></tr> 49 * <tr><td rowspan="2">https</td><td>https.proxyHost</td><td>Hostname of the HTTP proxy server used 50 * for HTTPS requests.</td><td></td></tr> 51 * <tr><td>https.proxyPort</td><td>Port number of the HTTP proxy server used for HTTPS 52 * requests.</td><td>443</td></tr> 53 * <tr><td rowspan="2">ftp, http or https</td><td>proxyHost</td><td>Hostname of the HTTP proxy 54 * server used for FTP, HTTP and HTTPS requests.</td><td></td></tr> 55 * <tr><td>proxyPort</td><td>Port number of the HTTP proxy server.</td><td>80 for FTP and HTTP 56 * <br>443 for HTTPS</td></tr> 57 * <tr><td colspan="4"><br></td></tr> 58 * 59 * <tr class="TableHeadingColor"><th colspan="4">{@linkplain Proxy.Type#SOCKS SOCKS 60 * Proxies}</th></tr> 61 * <tr><th>URL scheme</th><th>property name</th><th>description</th><th>default</th></tr> 62 * <tr><td rowspan="2">ftp, http, https or socket</td><td>socksProxyHost</td><td>Hostname of the 63 * SOCKS proxy server used for FTP, HTTP, HTTPS and raw sockets.<br>Raw socket URLs are of the 64 * form <code>socket://<i>host</i>:<i>port</i></code></td><td></td></tr> 65 * <tr><td>socksProxyPort</td><td>Port number of the SOCKS proxy server.</td><td>1080</td></tr> 66 * </table> 67 * 68 * <p>Hostname patterns specify which hosts should be connected to directly, 69 * ignoring any other proxy system properties. If the URL's host matches the 70 * corresponding hostname pattern, {@link Proxy#NO_PROXY} is returned. 71 * 72 * <p>The format of a hostname pattern is a list of hostnames that are 73 * separated by {@code |} and that use {@code *} as a wildcard. For example, 74 * setting the {@code http.nonProxyHosts} property to {@code 75 * *.android.com|*.kernel.org} will cause requests to {@code 76 * http://developer.android.com} to be made without a proxy. 77 * 78 * <p>The default proxy selector always returns exactly one proxy. If no proxy 79 * is applicable, {@link Proxy#NO_PROXY} is returned. If multiple proxies are 80 * applicable, such as when both the {@code proxyHost} and {@code 81 * socksProxyHost} system properties are set, the result is the property listed 82 * earliest in the table above. 83 * 84 * <h3>Alternatives</h3> 85 * <p>To request a URL without involving the system proxy selector, explicitly 86 * specify a proxy or {@link Proxy#NO_PROXY} using {@link 87 * URL#openConnection(Proxy)}. 88 * 89 * <p>Use {@link ProxySelector#setDefault(ProxySelector)} to install a custom 90 * proxy selector. 91 */ 92 public abstract class ProxySelector { 93 94 private static ProxySelector defaultSelector = new ProxySelectorImpl(); 95 96 /** 97 * Returns the default proxy selector, or null if none exists. 98 */ getDefault()99 public static ProxySelector getDefault() { 100 return defaultSelector; 101 } 102 103 /** 104 * Sets the default proxy selector. If {@code selector} is null, the current 105 * proxy selector will be removed. 106 */ setDefault(ProxySelector selector)107 public static void setDefault(ProxySelector selector) { 108 defaultSelector = selector; 109 } 110 111 /** 112 * Returns the proxy servers to use on connections to {@code uri}. This list 113 * will contain {@link Proxy#NO_PROXY} if no proxy server should be used. 114 * 115 * @throws IllegalArgumentException if {@code uri} is null. 116 */ select(URI uri)117 public abstract List<Proxy> select(URI uri); 118 119 /** 120 * Notifies this {@code ProxySelector} that a connection to the proxy server 121 * could not be established. 122 * 123 * @param uri the URI to which the connection could not be established. 124 * @param address the address of the proxy. 125 * @param failure the exception which was thrown during connection 126 * establishment. 127 * @throws IllegalArgumentException if any argument is null. 128 */ connectFailed(URI uri, SocketAddress address, IOException failure)129 public abstract void connectFailed(URI uri, SocketAddress address, IOException failure); 130 } 131