001: /* Licensed to the Apache Software Foundation (ASF) under one or more
002: * contributor license agreements. See the NOTICE file distributed with
003: * this work for additional information regarding copyright ownership.
004: * The ASF licenses this file to You under the Apache License, Version 2.0
005: * (the "License"); you may not use this file except in compliance with
006: * the License. You may obtain a copy of the License at
007: *
008: * http://www.apache.org/licenses/LICENSE-2.0
009: *
010: * Unless required by applicable law or agreed to in writing, software
011: * distributed under the License is distributed on an "AS IS" BASIS,
012: * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
013: * See the License for the specific language governing permissions and
014: * limitations under the License.
015: */
016: package java.net;
017:
018: import java.io.IOException;
019: import java.util.List;
020:
021: /**
022: * <p>
023: * Selects applicable proxies when connecting to network resouce represented by
024: * a <code>URI</code>. An implementation of <code>ProxySelector</code>
025: * should be a concrete subclass of <code>ProxySelector</code>. Method
026: * <code>select</code> returns a list of proxies according to the
027: * <code>uri</code>. If a connection can't be established, the caller should
028: * notify proxy selector by invoking <code>connectFailed</code> method.
029: * </p>
030: * <p>
031: * A proxy selector can be registered/unregistered by calling
032: * <code>setDefault</code> method and retrieved by calling
033: * <code>getDefault</code> method.
034: * </p>
035: *
036: */
037: public abstract class ProxySelector {
038:
039: private static ProxySelector defaultSelector = new ProxySelectorImpl();
040:
041: /*
042: * "getProxySelector" permission. getDefault method requires this
043: * permission.
044: */
045: private final static NetPermission getProxySelectorPermission = new NetPermission(
046: "getProxySelector"); //$NON-NLS-1$
047:
048: /*
049: * "setProxySelector" permission. setDefault method requires this
050: * permission.
051: */
052: private final static NetPermission setProxySelectorPermission = new NetPermission(
053: "setProxySelector"); //$NON-NLS-1$
054:
055: /**
056: * Constructor method.
057: */
058: public ProxySelector() {
059: super ();
060: }
061:
062: /**
063: * Gets system default <code>ProxySelector</code>.
064: *
065: * @return system default <code>ProxySelector</code>.
066: * @throws SecurtiyException
067: * If a security manager is installed and it doesn't have
068: * <code>NetPermission("getProxySelector")</code>.
069: */
070: public static ProxySelector getDefault() {
071: SecurityManager sm = System.getSecurityManager();
072: if (null != sm) {
073: sm.checkPermission(getProxySelectorPermission);
074: }
075: return defaultSelector;
076: }
077:
078: /**
079: * Sets system default <code>ProxySelector</code>. Unsets system default
080: * <code>ProxySelector</code> if <code>selector</code> is null.
081: *
082: * @throws SecurtiyException
083: * If a security manager is installed and it doesn't have
084: * <code>NetPermission("setProxySelector")</code>.
085: */
086: public static void setDefault(ProxySelector selector) {
087: SecurityManager sm = System.getSecurityManager();
088: if (null != sm) {
089: sm.checkPermission(setProxySelectorPermission);
090: }
091: defaultSelector = selector;
092: }
093:
094: /**
095: * Gets applicable proxies based on the accessing protocol of
096: * <code>uri</code>. The format of URI is defined as below:
097: * <li>http URI stands for http connection.</li>
098: * <li>https URI stands for https connection.</li>
099: * <li>ftp URI stands for ftp connection.</li>
100: * <li>socket:://ip:port URI stands for tcp client sockets connection.</li>
101: *
102: * @param uri
103: * the destination <code>URI</code> object.
104: * @return a list contains all applicable proxies. If no proxy is available,
105: * returns a list only contains one element
106: * <code>Proxy.NO_PROXY</code>.
107: * @throws IllegalArgumentException
108: * If any argument is null.
109: */
110: public abstract List<Proxy> select(URI uri);
111:
112: /**
113: * If the connection can not be established to the proxy server, this method
114: * will be called. An implementation may adjust proxy the sequence of
115: * proxies returned by <code>select(String, String)</code>.
116: *
117: * @param uri
118: * the <code>URI</code> that the connection fails to connect
119: * to.
120: * @param sa
121: * <code>SocketAddress</code> of the proxy.
122: * @param ioe
123: * The <code>IOException</code> which is thrown during
124: * connection establishment.
125: * @throws IllegalArgumentException
126: * If any argument is null.
127: */
128: public abstract void connectFailed(URI uri, SocketAddress sa,
129: IOException ioe);
130: }
|