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
17package java.net;
18
19import java.io.IOException;
20import 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 */
92public 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     */
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     */
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     */
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     */
129    public abstract void connectFailed(URI uri, SocketAddress address, IOException failure);
130}
131