1 /*
2 * Copyright (c) 2003, 2011, Oracle and/or its affiliates. All rights reserved.
3 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
4 *
5 * This code is free software; you can redistribute it and/or modify it
6 * under the terms of the GNU General Public License version 2 only, as
7 * published by the Free Software Foundation. Oracle designates this
8 * particular file as subject to the "Classpath" exception as provided
9 * by Oracle in the LICENSE file that accompanied this code.
10 *
11 * This code is distributed in the hope that it will be useful, but WITHOUT
12 * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
13 * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
14 * version 2 for more details (a copy is included in the LICENSE file that
15 * accompanied this code).
16 *
17 * You should have received a copy of the GNU General Public License version
18 * 2 along with this work; if not, write to the Free Software Foundation,
19 * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
20 *
21 * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
22 * or visit www.oracle.com if you need additional information or have any
23 * questions.
24 */
25
26 package java.net;
27
28 import java.io.IOException;
29 import java.util.List;
30 import sun.security.util.SecurityConstants;
31
32 /**
33 * Selects the proxy server to use, if any, when connecting to the
34 * network resource referenced by a URL. A proxy selector is a
35 * concrete sub-class of this class and is registered by invoking the
36 * {@link java.net.ProxySelector#setDefault setDefault} method. The
37 * currently registered proxy selector can be retrieved by calling
38 * {@link java.net.ProxySelector#getDefault getDefault} method.
39 *
40 * <p> When a proxy selector is registered, for instance, a subclass
41 * of URLConnection class should call the {@link #select select}
42 * method for each URL request so that the proxy selector can decide
43 * if a direct, or proxied connection should be used. The {@link
44 * #select select} method returns an iterator over a collection with
45 * the preferred connection approach.
46 *
47 * <p> If a connection cannot be established to a proxy (PROXY or
48 * SOCKS) servers then the caller should call the proxy selector's
49 * {@link #connectFailed connectFailed} method to notify the proxy
50 * selector that the proxy server is unavailable. </p>
51 *
52 * @author Yingxian Wang
53 * @author Jean-Christophe Collet
54 * @since 1.5
55 */
56 public abstract class ProxySelector {
57 /**
58 * The system wide proxy selector that selects the proxy server to
59 * use, if any, when connecting to a remote object referenced by
60 * an URL.
61 *
62 * @see #setDefault(ProxySelector)
63 */
64 private static ProxySelector theProxySelector;
65
66 static {
67 try {
68 Class<?> c = Class.forName("sun.net.spi.DefaultProxySelector");
69 if (c != null && ProxySelector.class.isAssignableFrom(c)) {
70 theProxySelector = (ProxySelector) c.newInstance();
71 }
72 } catch (Exception e) {
73 theProxySelector = null;
74 }
75 }
76
77 /**
78 * Gets the system-wide proxy selector.
79 *
80 * @throws SecurityException
81 * If a security manager has been installed and it denies
82 * {@link NetPermission}<tt>("getProxySelector")</tt>
83 * @see #setDefault(ProxySelector)
84 * @return the system-wide <code>ProxySelector</code>
85 * @since 1.5
86 */
87 public static ProxySelector getDefault() {
88 SecurityManager sm = System.getSecurityManager();
89 if (sm != null) {
90 sm.checkPermission(SecurityConstants.GET_PROXYSELECTOR_PERMISSION);
91 }
92 return theProxySelector;
93 }
94
95 /**
96 * Sets (or unsets) the system-wide proxy selector.
97 *
98 * Note: non-standard protocol handlers may ignore this setting.
99 *
100 * @param ps The HTTP proxy selector, or
101 * <code>null</code> to unset the proxy selector.
102 *
103 * @throws SecurityException
104 * If a security manager has been installed and it denies
105 * {@link NetPermission}<tt>("setProxySelector")</tt>
106 *
107 * @see #getDefault()
108 * @since 1.5
109 */
110 public static void setDefault(ProxySelector ps) {
111 SecurityManager sm = System.getSecurityManager();
112 if (sm != null) {
113 sm.checkPermission(SecurityConstants.SET_PROXYSELECTOR_PERMISSION);
114 }
115 theProxySelector = ps;
116 }
117
118 /**
119 * Selects all the applicable proxies based on the protocol to
120 * access the resource with and a destination address to access
121 * the resource at.
122 * The format of the URI is defined as follow:
123 * <UL>
124 * <LI>http URI for http connections</LI>
125 * <LI>https URI for https connections
126 * <LI>ftp URI for ftp connections</LI>
127 * <LI><code>socket://host:port</code><br>
128 * for tcp client sockets connections</LI>
129 * </UL>
130 *
131 * @param uri
132 * The URI that a connection is required to
133 *
134 * @return a List of Proxies. Each element in the
135 * the List is of type
136 * {@link java.net.Proxy Proxy};
137 * when no proxy is available, the list will
138 * contain one element of type
139 * {@link java.net.Proxy Proxy}
140 * that represents a direct connection.
141 * @throws IllegalArgumentException if the argument is null
142 */
143 public abstract List<Proxy> select(URI uri);
144
145 /**
146 * Called to indicate that a connection could not be established
147 * to a proxy/socks server. An implementation of this method can
148 * temporarily remove the proxies or reorder the sequence of
149 * proxies returned by {@link #select(URI)}, using the address
150 * and the IOException caught when trying to connect.
151 *
152 * @param uri
153 * The URI that the proxy at sa failed to serve.
154 * @param sa
155 * The socket address of the proxy/SOCKS server
156 *
157 * @param ioe
158 * The I/O exception thrown when the connect failed.
159 * @throws IllegalArgumentException if either argument is null
160 */
161 public abstract void connectFailed(URI uri, SocketAddress sa, IOException ioe);
162 }