1adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project/* Licensed to the Apache Software Foundation (ASF) under one or more 2adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * contributor license agreements. See the NOTICE file distributed with 3adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * this work for additional information regarding copyright ownership. 4adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * The ASF licenses this file to You under the Apache License, Version 2.0 5adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * (the "License"); you may not use this file except in compliance with 6adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * the License. You may obtain a copy of the License at 7f33eae7e84eb6d3b0f4e86b59605bb3de73009f3Elliott Hughes * 8adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * http://www.apache.org/licenses/LICENSE-2.0 9f33eae7e84eb6d3b0f4e86b59605bb3de73009f3Elliott Hughes * 10adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * Unless required by applicable law or agreed to in writing, software 11adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * distributed under the License is distributed on an "AS IS" BASIS, 12adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 13adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * See the License for the specific language governing permissions and 14adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * limitations under the License. 15adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project */ 163b0348d1081a4645aa38da97ee299fadc040c1b4Jesse Wilson 17adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Projectpackage java.net; 18adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project 19adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Projectimport java.io.IOException; 20adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Projectimport java.util.List; 21adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project 22adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project/** 233b0348d1081a4645aa38da97ee299fadc040c1b4Jesse Wilson * Selects the proxy server to use, if any, when connecting to a given URL. 243b0348d1081a4645aa38da97ee299fadc040c1b4Jesse Wilson * 253b0348d1081a4645aa38da97ee299fadc040c1b4Jesse Wilson * <h3>System Properties</h3> 263b0348d1081a4645aa38da97ee299fadc040c1b4Jesse Wilson * <p>The default proxy selector is configured by system properties. 273b0348d1081a4645aa38da97ee299fadc040c1b4Jesse Wilson * 283b0348d1081a4645aa38da97ee299fadc040c1b4Jesse Wilson * <table border="1" cellpadding="3" cellspacing="0"> 293b0348d1081a4645aa38da97ee299fadc040c1b4Jesse Wilson * <tr class="TableHeadingColor"><th colspan="4">Hostname patterns</th></tr> 303b0348d1081a4645aa38da97ee299fadc040c1b4Jesse Wilson * <tr><th>URL scheme</th><th>property name</th><th>description</th><th>default</th></tr> 313b0348d1081a4645aa38da97ee299fadc040c1b4Jesse Wilson * <tr><td>ftp</td><td>ftp.nonProxyHosts</td><td>Hostname pattern for FTP servers to connect to 3202a01a6ce390976b7c5cea95fe87c3020c797dffJesse Wilson * directly (without a proxy).</td><td></td></tr> 333b0348d1081a4645aa38da97ee299fadc040c1b4Jesse Wilson * <tr><td>http</td><td>http.nonProxyHosts</td><td>Hostname pattern for HTTP servers to connect to 3402a01a6ce390976b7c5cea95fe87c3020c797dffJesse Wilson * directly (without a proxy).</td><td></td></tr> 353b0348d1081a4645aa38da97ee299fadc040c1b4Jesse Wilson * <tr><td>https</td><td>https.nonProxyHosts</td><td>Hostname pattern for HTTPS servers to connect 3602a01a6ce390976b7c5cea95fe87c3020c797dffJesse Wilson * to directly (without a proxy).</td><td></td></tr> 373b0348d1081a4645aa38da97ee299fadc040c1b4Jesse Wilson * <tr><td colspan="4"><br></td></tr> 383b0348d1081a4645aa38da97ee299fadc040c1b4Jesse Wilson * 393b0348d1081a4645aa38da97ee299fadc040c1b4Jesse Wilson * <tr class="TableHeadingColor"><th colspan="4">{@linkplain Proxy.Type#HTTP HTTP Proxies}</th></tr> 403b0348d1081a4645aa38da97ee299fadc040c1b4Jesse Wilson * <tr><th>URL scheme</th><th>property name</th><th>description</th><th>default</th></tr> 413b0348d1081a4645aa38da97ee299fadc040c1b4Jesse Wilson * <tr><td rowspan="2">ftp</td><td>ftp.proxyHost</td><td>Hostname of the HTTP proxy server used for 423b0348d1081a4645aa38da97ee299fadc040c1b4Jesse Wilson * FTP requests.</td><td></td></tr> 433b0348d1081a4645aa38da97ee299fadc040c1b4Jesse Wilson * <tr><td>ftp.proxyPort</td><td>Port number of the HTTP proxy server used for FTP 443b0348d1081a4645aa38da97ee299fadc040c1b4Jesse Wilson * requests.</td><td>80</td></tr> 453b0348d1081a4645aa38da97ee299fadc040c1b4Jesse Wilson * <tr><td rowspan="2">http</td><td>http.proxyHost</td><td>Hostname of the HTTP proxy server used 463b0348d1081a4645aa38da97ee299fadc040c1b4Jesse Wilson * for HTTP requests.</td><td></td></tr> 473b0348d1081a4645aa38da97ee299fadc040c1b4Jesse Wilson * <tr><td>http.proxyPort</td><td>Port number of the HTTP proxy server used for HTTP 483b0348d1081a4645aa38da97ee299fadc040c1b4Jesse Wilson * requests.</td><td>80</td></tr> 493b0348d1081a4645aa38da97ee299fadc040c1b4Jesse Wilson * <tr><td rowspan="2">https</td><td>https.proxyHost</td><td>Hostname of the HTTP proxy server used 503b0348d1081a4645aa38da97ee299fadc040c1b4Jesse Wilson * for HTTPS requests.</td><td></td></tr> 513b0348d1081a4645aa38da97ee299fadc040c1b4Jesse Wilson * <tr><td>https.proxyPort</td><td>Port number of the HTTP proxy server used for HTTPS 523b0348d1081a4645aa38da97ee299fadc040c1b4Jesse Wilson * requests.</td><td>443</td></tr> 533b0348d1081a4645aa38da97ee299fadc040c1b4Jesse Wilson * <tr><td rowspan="2">ftp, http or https</td><td>proxyHost</td><td>Hostname of the HTTP proxy 543b0348d1081a4645aa38da97ee299fadc040c1b4Jesse Wilson * server used for FTP, HTTP and HTTPS requests.</td><td></td></tr> 553b0348d1081a4645aa38da97ee299fadc040c1b4Jesse Wilson * <tr><td>proxyPort</td><td>Port number of the HTTP proxy server.</td><td>80 for FTP and HTTP 563b0348d1081a4645aa38da97ee299fadc040c1b4Jesse Wilson * <br>443 for HTTPS</td></tr> 573b0348d1081a4645aa38da97ee299fadc040c1b4Jesse Wilson * <tr><td colspan="4"><br></td></tr> 583b0348d1081a4645aa38da97ee299fadc040c1b4Jesse Wilson * 593b0348d1081a4645aa38da97ee299fadc040c1b4Jesse Wilson * <tr class="TableHeadingColor"><th colspan="4">{@linkplain Proxy.Type#SOCKS SOCKS 603b0348d1081a4645aa38da97ee299fadc040c1b4Jesse Wilson * Proxies}</th></tr> 613b0348d1081a4645aa38da97ee299fadc040c1b4Jesse Wilson * <tr><th>URL scheme</th><th>property name</th><th>description</th><th>default</th></tr> 623b0348d1081a4645aa38da97ee299fadc040c1b4Jesse Wilson * <tr><td rowspan="2">ftp, http, https or socket</td><td>socksProxyHost</td><td>Hostname of the 633b0348d1081a4645aa38da97ee299fadc040c1b4Jesse Wilson * SOCKS proxy server used for FTP, HTTP, HTTPS and raw sockets.<br>Raw socket URLs are of the 643b0348d1081a4645aa38da97ee299fadc040c1b4Jesse Wilson * form <code>socket://<i>host</i>:<i>port</i></code></td><td></td></tr> 653b0348d1081a4645aa38da97ee299fadc040c1b4Jesse Wilson * <tr><td>socksProxyPort</td><td>Port number of the SOCKS proxy server.</td><td>1080</td></tr> 663b0348d1081a4645aa38da97ee299fadc040c1b4Jesse Wilson * </table> 673b0348d1081a4645aa38da97ee299fadc040c1b4Jesse Wilson * 68ac29aad40bb1ffc25e5e66c9705cea8468021093Jesse Wilson * <p>Hostname patterns specify which hosts should be connected to directly, 69ac29aad40bb1ffc25e5e66c9705cea8468021093Jesse Wilson * ignoring any other proxy system properties. If the URL's host matches the 70ac29aad40bb1ffc25e5e66c9705cea8468021093Jesse Wilson * corresponding hostname pattern, {@link Proxy#NO_PROXY} is returned. 71ac29aad40bb1ffc25e5e66c9705cea8468021093Jesse Wilson * 72ac29aad40bb1ffc25e5e66c9705cea8468021093Jesse Wilson * <p>The format of a hostname pattern is a list of hostnames that are 73ac29aad40bb1ffc25e5e66c9705cea8468021093Jesse Wilson * separated by {@code |} and that use {@code *} as a wildcard. For example, 74ac29aad40bb1ffc25e5e66c9705cea8468021093Jesse Wilson * setting the {@code http.nonProxyHosts} property to {@code 75ac29aad40bb1ffc25e5e66c9705cea8468021093Jesse Wilson * *.android.com|*.kernel.org} will cause requests to {@code 76ac29aad40bb1ffc25e5e66c9705cea8468021093Jesse Wilson * http://developer.android.com} to be made without a proxy. 77ac29aad40bb1ffc25e5e66c9705cea8468021093Jesse Wilson * 783b0348d1081a4645aa38da97ee299fadc040c1b4Jesse Wilson * <p>The default proxy selector always returns exactly one proxy. If no proxy 793b0348d1081a4645aa38da97ee299fadc040c1b4Jesse Wilson * is applicable, {@link Proxy#NO_PROXY} is returned. If multiple proxies are 803b0348d1081a4645aa38da97ee299fadc040c1b4Jesse Wilson * applicable, such as when both the {@code proxyHost} and {@code 813b0348d1081a4645aa38da97ee299fadc040c1b4Jesse Wilson * socksProxyHost} system properties are set, the result is the property listed 823b0348d1081a4645aa38da97ee299fadc040c1b4Jesse Wilson * earliest in the table above. 833b0348d1081a4645aa38da97ee299fadc040c1b4Jesse Wilson * 843b0348d1081a4645aa38da97ee299fadc040c1b4Jesse Wilson * <h3>Alternatives</h3> 853b0348d1081a4645aa38da97ee299fadc040c1b4Jesse Wilson * <p>To request a URL without involving the system proxy selector, explicitly 863b0348d1081a4645aa38da97ee299fadc040c1b4Jesse Wilson * specify a proxy or {@link Proxy#NO_PROXY} using {@link 873b0348d1081a4645aa38da97ee299fadc040c1b4Jesse Wilson * URL#openConnection(Proxy)}. 883b0348d1081a4645aa38da97ee299fadc040c1b4Jesse Wilson * 893b0348d1081a4645aa38da97ee299fadc040c1b4Jesse Wilson * <p>Use {@link ProxySelector#setDefault(ProxySelector)} to install a custom 903b0348d1081a4645aa38da97ee299fadc040c1b4Jesse Wilson * proxy selector. 91adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project */ 92adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Projectpublic abstract class ProxySelector { 93adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project 94adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project private static ProxySelector defaultSelector = new ProxySelectorImpl(); 95adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project 96adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project /** 973b0348d1081a4645aa38da97ee299fadc040c1b4Jesse Wilson * Returns the default proxy selector, or null if none exists. 98adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project */ 99adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project public static ProxySelector getDefault() { 100adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project return defaultSelector; 101adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project } 102adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project 103adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project /** 1043b0348d1081a4645aa38da97ee299fadc040c1b4Jesse Wilson * Sets the default proxy selector. If {@code selector} is null, the current 1053b0348d1081a4645aa38da97ee299fadc040c1b4Jesse Wilson * proxy selector will be removed. 106adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project */ 107adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project public static void setDefault(ProxySelector selector) { 108adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project defaultSelector = selector; 109adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project } 110adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project 111adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project /** 1123b0348d1081a4645aa38da97ee299fadc040c1b4Jesse Wilson * Returns the proxy servers to use on connections to {@code uri}. This list 1133b0348d1081a4645aa38da97ee299fadc040c1b4Jesse Wilson * will contain {@link Proxy#NO_PROXY} if no proxy server should be used. 114f5597e626ecf7949d249dea08c1a2964d890ec11Jesse Wilson * 1153b0348d1081a4645aa38da97ee299fadc040c1b4Jesse Wilson * @throws IllegalArgumentException if {@code uri} is null. 116adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project */ 117adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project public abstract List<Proxy> select(URI uri); 118adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project 119adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project /** 1203b0348d1081a4645aa38da97ee299fadc040c1b4Jesse Wilson * Notifies this {@code ProxySelector} that a connection to the proxy server 1213b0348d1081a4645aa38da97ee299fadc040c1b4Jesse Wilson * could not be established. 122f33eae7e84eb6d3b0f4e86b59605bb3de73009f3Elliott Hughes * 1233b0348d1081a4645aa38da97ee299fadc040c1b4Jesse Wilson * @param uri the URI to which the connection could not be established. 1243b0348d1081a4645aa38da97ee299fadc040c1b4Jesse Wilson * @param address the address of the proxy. 1253b0348d1081a4645aa38da97ee299fadc040c1b4Jesse Wilson * @param failure the exception which was thrown during connection 1263b0348d1081a4645aa38da97ee299fadc040c1b4Jesse Wilson * establishment. 1273b0348d1081a4645aa38da97ee299fadc040c1b4Jesse Wilson * @throws IllegalArgumentException if any argument is null. 128adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project */ 1293b0348d1081a4645aa38da97ee299fadc040c1b4Jesse Wilson public abstract void connectFailed(URI uri, SocketAddress address, IOException failure); 130adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project} 131