001 /*
002 * Copyright 1997-2007 Sun Microsystems, Inc. All Rights Reserved.
003 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
004 *
005 * This code is free software; you can redistribute it and/or modify it
006 * under the terms of the GNU General Public License version 2 only, as
007 * published by the Free Software Foundation. Sun designates this
008 * particular file as subject to the "Classpath" exception as provided
009 * by Sun in the LICENSE file that accompanied this code.
010 *
011 * This code is distributed in the hope that it will be useful, but WITHOUT
012 * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
013 * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
014 * version 2 for more details (a copy is included in the LICENSE file that
015 * accompanied this code).
016 *
017 * You should have received a copy of the GNU General Public License version
018 * 2 along with this work; if not, write to the Free Software Foundation,
019 * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
020 *
021 * Please contact Sun Microsystems, Inc., 4150 Network Circle, Santa Clara,
022 * CA 95054 USA or visit www.sun.com if you need additional information or
023 * have any questions.
024 */
025
026 package javax.net;
027
028 import java.io.IOException;
029 import java.net.*;
030
031 /**
032 * This class creates sockets. It may be subclassed by other factories,
033 * which create particular subclasses of sockets and thus provide a general
034 * framework for the addition of public socket-level functionality.
035 *
036 * <P> Socket factories are a simple way to capture a variety of policies
037 * related to the sockets being constructed, producing such sockets in
038 * a way which does not require special configuration of the code which
039 * asks for the sockets: <UL>
040 *
041 * <LI> Due to polymorphism of both factories and sockets, different
042 * kinds of sockets can be used by the same application code just
043 * by passing it different kinds of factories.
044 *
045 * <LI> Factories can themselves be customized with parameters used
046 * in socket construction. So for example, factories could be
047 * customized to return sockets with different networking timeouts
048 * or security parameters already configured.
049 *
050 * <LI> The sockets returned to the application can be subclasses
051 * of java.net.Socket, so that they can directly expose new APIs
052 * for features such as compression, security, record marking,
053 * statistics collection, or firewall tunneling.
054 *
055 * </UL>
056 *
057 * <P> Factory classes are specified by environment-specific configuration
058 * mechanisms. For example, the <em>getDefault</em> method could return
059 * a factory that was appropriate for a particular user or applet, and a
060 * framework could use a factory customized to its own purposes.
061 *
062 * @since 1.4
063 * @see ServerSocketFactory
064 *
065 * @version 1.24
066 * @author David Brownell
067 */
068 public abstract class SocketFactory {
069 //
070 // NOTE: JDK 1.1 bug in class GC, this can get collected
071 // even though it's always accessible via getDefault().
072 //
073 private static SocketFactory theFactory;
074
075 /**
076 * Creates a <code>SocketFactory</code>.
077 */
078 protected SocketFactory() { /* NOTHING */
079 }
080
081 /**
082 * Returns a copy of the environment's default socket factory.
083 *
084 * @return the default <code>SocketFactory</code>
085 */
086 public static SocketFactory getDefault() {
087 synchronized (SocketFactory.class) {
088 if (theFactory == null) {
089 //
090 // Different implementations of this method SHOULD
091 // work rather differently. For example, driving
092 // this from a system property, or using a different
093 // implementation than JavaSoft's.
094 //
095 theFactory = new DefaultSocketFactory();
096 }
097 }
098
099 return theFactory;
100 }
101
102 /**
103 * Creates an unconnected socket.
104 *
105 * @return the unconnected socket
106 * @throws IOException if the socket cannot be created
107 * @see java.net.Socket#connect(java.net.SocketAddress)
108 * @see java.net.Socket#connect(java.net.SocketAddress, int)
109 * @see java.net.Socket#Socket()
110 */
111 public Socket createSocket() throws IOException {
112 throw new SocketException("Unconnected sockets not implemented");
113 }
114
115 /**
116 * Creates a socket and connects it to the specified remote host
117 * at the specified remote port. This socket is configured using
118 * the socket options established for this factory.
119 * <p>
120 * If there is a security manager, its <code>checkConnect</code>
121 * method is called with the host address and <code>port</code>
122 * as its arguments. This could result in a SecurityException.
123 *
124 * @param host the server host name with which to connect, or
125 * <code>null</code> for the loopback address.
126 * @param port the server port
127 * @return the <code>Socket</code>
128 * @throws IOException if an I/O error occurs when creating the socket
129 * @throws SecurityException if a security manager exists and its
130 * <code>checkConnect</code> method doesn't allow the operation.
131 * @throws UnknownHostException if the host is not known
132 * @throws IllegalArgumentException if the port parameter is outside the
133 * specified range of valid port values, which is between 0 and
134 * 65535, inclusive.
135 * @see SecurityManager#checkConnect
136 * @see java.net.Socket#Socket(String, int)
137 */
138 public abstract Socket createSocket(String host, int port)
139 throws IOException, UnknownHostException;
140
141 /**
142 * Creates a socket and connects it to the specified remote host
143 * on the specified remote port.
144 * The socket will also be bound to the local address and port supplied.
145 * This socket is configured using
146 * the socket options established for this factory.
147 * <p>
148 * If there is a security manager, its <code>checkConnect</code>
149 * method is called with the host address and <code>port</code>
150 * as its arguments. This could result in a SecurityException.
151 *
152 * @param host the server host name with which to connect, or
153 * <code>null</code> for the loopback address.
154 * @param port the server port
155 * @param localHost the local address the socket is bound to
156 * @param localPort the local port the socket is bound to
157 * @return the <code>Socket</code>
158 * @throws IOException if an I/O error occurs when creating the socket
159 * @throws SecurityException if a security manager exists and its
160 * <code>checkConnect</code> method doesn't allow the operation.
161 * @throws UnknownHostException if the host is not known
162 * @throws IllegalArgumentException if the port parameter or localPort
163 * parameter is outside the specified range of valid port values,
164 * which is between 0 and 65535, inclusive.
165 * @see SecurityManager#checkConnect
166 * @see java.net.Socket#Socket(String, int, java.net.InetAddress, int)
167 */
168 public abstract Socket createSocket(String host, int port,
169 InetAddress localHost, int localPort) throws IOException,
170 UnknownHostException;
171
172 /**
173 * Creates a socket and connects it to the specified port number
174 * at the specified address. This socket is configured using
175 * the socket options established for this factory.
176 * <p>
177 * If there is a security manager, its <code>checkConnect</code>
178 * method is called with the host address and <code>port</code>
179 * as its arguments. This could result in a SecurityException.
180 *
181 * @param host the server host
182 * @param port the server port
183 * @return the <code>Socket</code>
184 * @throws IOException if an I/O error occurs when creating the socket
185 * @throws SecurityException if a security manager exists and its
186 * <code>checkConnect</code> method doesn't allow the operation.
187 * @throws IllegalArgumentException if the port parameter is outside the
188 * specified range of valid port values, which is between 0 and
189 * 65535, inclusive.
190 * @throws NullPointerException if <code>host</code> is null.
191 * @see SecurityManager#checkConnect
192 * @see java.net.Socket#Socket(java.net.InetAddress, int)
193 */
194 public abstract Socket createSocket(InetAddress host, int port)
195 throws IOException;
196
197 /**
198 * Creates a socket and connect it to the specified remote address
199 * on the specified remote port. The socket will also be bound
200 * to the local address and port suplied. The socket is configured using
201 * the socket options established for this factory.
202 * <p>
203 * If there is a security manager, its <code>checkConnect</code>
204 * method is called with the host address and <code>port</code>
205 * as its arguments. This could result in a SecurityException.
206 *
207 * @param address the server network address
208 * @param port the server port
209 * @param localAddress the client network address
210 * @param localPort the client port
211 * @return the <code>Socket</code>
212 * @throws IOException if an I/O error occurs when creating the socket
213 * @throws SecurityException if a security manager exists and its
214 * <code>checkConnect</code> method doesn't allow the operation.
215 * @throws IllegalArgumentException if the port parameter or localPort
216 * parameter is outside the specified range of valid port values,
217 * which is between 0 and 65535, inclusive.
218 * @throws NullPointerException if <code>address</code> is null.
219 * @see SecurityManager#checkConnect
220 * @see java.net.Socket#Socket(java.net.InetAddress, int,
221 * java.net.InetAddress, int)
222 */
223 public abstract Socket createSocket(InetAddress address, int port,
224 InetAddress localAddress, int localPort) throws IOException;
225 }
226
227 //
228 // The default factory has NO intelligence about policies like tunneling
229 // out through firewalls (e.g. SOCKS V4 or V5) or in through them
230 // (e.g. using SSL), or that some ports are reserved for use with SSL.
231 //
232 // Note that at least JDK 1.1 has a low level "plainSocketImpl" that
233 // knows about SOCKS V4 tunneling, so this isn't a totally bogus default.
234 //
235 // ALSO: we may want to expose this class somewhere so other folk
236 // can reuse it, particularly if we start to add highly useful features
237 // such as ability to set connect timeouts.
238 //
239 class DefaultSocketFactory extends SocketFactory {
240
241 public Socket createSocket() {
242 return new Socket();
243 }
244
245 public Socket createSocket(String host, int port)
246 throws IOException, UnknownHostException {
247 return new Socket(host, port);
248 }
249
250 public Socket createSocket(InetAddress address, int port)
251 throws IOException {
252 return new Socket(address, port);
253 }
254
255 public Socket createSocket(String host, int port,
256 InetAddress clientAddress, int clientPort)
257 throws IOException, UnknownHostException {
258 return new Socket(host, port, clientAddress, clientPort);
259 }
260
261 public Socket createSocket(InetAddress address, int port,
262 InetAddress clientAddress, int clientPort)
263 throws IOException {
264 return new Socket(address, port, clientAddress, clientPort);
265 }
266 }
|