KickJava   Java API By Example, From Geeks To Geeks.

Java > Open Source Codes > java > net > ProxySelector


1 /*
2  * @(#)ProxySelector.java 1.3 03/08/09
3  *
4  * Copyright 2004 Sun Microsystems, Inc. All rights reserved.
5  * SUN PROPRIETARY/CONFIDENTIAL. Use is subject to license terms.
6  */
7
8 package java.net;
9
10 import java.io.IOException JavaDoc;
11 import java.util.List JavaDoc;
12 import sun.security.util.SecurityConstants;
13
14 /**
15  * Selects the proxy server to use, if any, when connecting to the
16  * network resource referenced by a URL. A proxy selector is a
17  * concrete sub-class of this class and is registered by invoking the
18  * {@link java.net.ProxySelector#setDefault setDefault} method. The
19  * currently registered proxy selector can be retrieved by calling
20  * {@link java.net.ProxySelector#getDefault getDefault} method.
21  *
22  * <p> When a proxy selector is registered, for instance, a subclass
23  * of URLConnection class should call the {@link #select select}
24  * method for each URL request so that the proxy selector can decide
25  * if a direct, or proxied connection should be used. The {@link
26  * #select select} method returns an iterator over a collection with
27  * the preferred connection approach.
28  *
29  * <p> If a connection cannot be established to a proxy (PROXY or
30  * SOCKS) servers then the caller should call the proxy selector's
31  * {@link #connectFailed connectFailed} method to notify the proxy
32  * selector that the proxy server is unavailable. </p>
33  *
34  * @version 1.3, 03/08/09
35  * @author Yingxian Wang
36  * @author Jean-Christophe Collet
37  * @since 1.5
38  */
39 public abstract class ProxySelector {
40     /**
41      * The system wide proxy selector that selects the proxy server to
42      * use, if any, when connecting to a remote object referenced by
43      * an URL.
44      *
45      * @see #setDefault(ProxySelector)
46      */
47     private static ProxySelector JavaDoc theProxySelector;
48
49     static {
50     try {
51         Class JavaDoc c = Class.forName("sun.net.spi.DefaultProxySelector");
52         if (c != null && ProxySelector JavaDoc.class.isAssignableFrom(c)) {
53         theProxySelector = (ProxySelector JavaDoc) c.newInstance();
54         }
55     } catch (Exception JavaDoc e) {
56         theProxySelector = null;
57     }
58     }
59
60     /**
61      * Gets the system-wide proxy selector.
62      *
63      * @throws SecurityException
64      * If a security manager has been installed and it denies
65      * {@link NetPermission}<tt>("getProxySelector")</tt>
66      * @see #setDefault(ProxySelector)
67      * @return the system-wide <code>ProxySelector</code>
68      * @since 1.5
69      */
70     public static ProxySelector JavaDoc getDefault() {
71     SecurityManager JavaDoc sm = System.getSecurityManager();
72     if (sm != null) {
73         sm.checkPermission(SecurityConstants.GET_PROXYSELECTOR_PERMISSION);
74     }
75     return theProxySelector;
76     }
77   
78     /**
79      * Sets (or unsets) the system-wide proxy selector.
80      *
81      * Note: non-standard procotol handlers may ignore this setting.
82      *
83      * @param ps The HTTP proxy selector, or
84      * <code>null</code> to unset the proxy selector.
85      *
86      * @throws SecurityException
87      * If a security manager has been installed and it denies
88      * {@link NetPermission}<tt>("setProxySelector")</tt>
89      *
90      * @see #getDefault()
91      * @since 1.5
92      */
93     public static void setDefault(ProxySelector JavaDoc ps) {
94     SecurityManager JavaDoc sm = System.getSecurityManager();
95     if (sm != null) {
96         sm.checkPermission(SecurityConstants.SET_PROXYSELECTOR_PERMISSION);
97     }
98     theProxySelector = ps;
99     }
100     
101     /**
102      * Selects all the applicable proxies based on the protocol to
103      * access the resource with and a destination address to access
104      * the resource at.
105      * The format of the URI is defined as follow:
106      * <UL>
107      * <LI>http URI for http connections</LI>
108      * <LI>https URI for https connections
109      * <LI>ftp URI for ftp connections</LI>
110      * <LI><code>socket://host:port</code><br>
111      * for tcp client sockets connections</LI>
112      * </UL>
113      *
114      * @param uri
115      * The URI that a connection is required to
116      *
117      * @return a List of Proxies. Each element in the
118      * the List is of type
119      * {@link java.net.Proxy Proxy};
120      * when no proxy is available, the list will
121      * contain one element of type
122      * {@link java.net.Proxy Proxy}
123      * that represents a direct connection.
124      * @throws IllegalArgumentException if either argument is null
125      */
126     public abstract List JavaDoc<Proxy JavaDoc> select(URI JavaDoc uri);
127
128     /**
129      * Called to indicate that a connection could not be established
130      * to a proxy/socks server. An implementation of this method can
131      * temporarily remove the proxies or reorder the sequence of
132      * proxies returned by select(String, String), using the address
133      * and they kind of IOException given.
134      *
135      * @param uri
136      * The URI that the proxy at sa failed to serve.
137      * @param sa
138      * The socket address of the proxy/SOCKS server
139      *
140      * @param ioe
141      * The I/O exception thrown when the connect failed.
142      * @throws IllegalArgumentException if either argument is null
143      */
144     public abstract void connectFailed(URI JavaDoc uri, SocketAddress JavaDoc sa, IOException JavaDoc ioe);
145 }
146
147
Popular Tags