1 /* 2 * Copyright (c) 2003, 2013, 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 * <P>The default proxy selector does enforce a 53 * <a href="doc-files/net-properties.html#Proxies">set of System Properties</a> 54 * related to proxy settings.</P> 55 * 56 * @author Yingxian Wang 57 * @author Jean-Christophe Collet 58 * @since 1.5 59 */ 60 public abstract class ProxySelector { 61 /** 62 * The system wide proxy selector that selects the proxy server to 63 * use, if any, when connecting to a remote object referenced by 64 * an URL. 65 * 66 * @see #setDefault(ProxySelector) 67 */ 68 private static ProxySelector theProxySelector; 69 70 static { 71 try { 72 Class<?> c = Class.forName("sun.net.spi.DefaultProxySelector"); 73 if (c != null && ProxySelector.class.isAssignableFrom(c)) { 74 theProxySelector = (ProxySelector) c.newInstance(); 75 } 76 } catch (Exception e) { 77 theProxySelector = null; 78 } 79 } 80 81 /** 82 * Gets the system-wide proxy selector. 83 * 84 * @throws SecurityException 85 * If a security manager has been installed and it denies 86 * {@link NetPermission}{@code ("getProxySelector")} 87 * @see #setDefault(ProxySelector) 88 * @return the system-wide {@code ProxySelector} 89 * @since 1.5 90 */ 91 public static ProxySelector getDefault() { 92 SecurityManager sm = System.getSecurityManager(); 93 if (sm != null) { 94 sm.checkPermission(SecurityConstants.GET_PROXYSELECTOR_PERMISSION); 95 } 96 return theProxySelector; 97 } 98 99 /** 100 * Sets (or unsets) the system-wide proxy selector. 101 * 102 * Note: non-standard protocol handlers may ignore this setting. 103 * 104 * @param ps The HTTP proxy selector, or 105 * {@code null} to unset the proxy selector. 106 * 107 * @throws SecurityException 108 * If a security manager has been installed and it denies 109 * {@link NetPermission}{@code ("setProxySelector")} 110 * 111 * @see #getDefault() 112 * @since 1.5 113 */ 114 public static void setDefault(ProxySelector ps) { 115 SecurityManager sm = System.getSecurityManager(); 116 if (sm != null) { 117 sm.checkPermission(SecurityConstants.SET_PROXYSELECTOR_PERMISSION); 118 } 119 theProxySelector = ps; 120 } 121 122 /** 123 * Selects all the applicable proxies based on the protocol to 124 * access the resource with and a destination address to access 125 * the resource at. 126 * The format of the URI is defined as follow: 127 * <UL> 128 * <LI>http URI for http connections</LI> 129 * <LI>https URI for https connections 130 * <LI>{@code socket://host:port}<br> 131 * for tcp client sockets connections</LI> 132 * </UL> 133 * 134 * @param uri 135 * The URI that a connection is required to 136 * 137 * @return a List of Proxies. Each element in the 138 * the List is of type 139 * {@link java.net.Proxy Proxy}; 140 * when no proxy is available, the list will 141 * contain one element of type 142 * {@link java.net.Proxy Proxy} 143 * that represents a direct connection. 144 * @throws IllegalArgumentException if the argument is null 145 */ 146 public abstract List<Proxy> select(URI uri); 147 148 /** 149 * Called to indicate that a connection could not be established 150 * to a proxy/socks server. An implementation of this method can 151 * temporarily remove the proxies or reorder the sequence of 152 * proxies returned by {@link #select(URI)}, using the address 153 * and the IOException caught when trying to connect. 154 * 155 * @param uri 156 * The URI that the proxy at sa failed to serve. 157 * @param sa 158 * The socket address of the proxy/SOCKS server 159 * 160 * @param ioe 161 * The I/O exception thrown when the connect failed. 162 * @throws IllegalArgumentException if either argument is null 163 */ 164 public abstract void connectFailed(URI uri, SocketAddress sa, IOException ioe); 165 } 166
