1 /*
2 * Copyright 1997-2007 Sun Microsystems, Inc. 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. Sun designates this
8 * particular file as subject to the "Classpath" exception as provided
9 * by Sun 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 Sun Microsystems, Inc., 4150 Network Circle, Santa Clara,
22 * CA 95054 USA or visit www.sun.com if you need additional information or
23 * have any questions.
24 */
25
26
27 package javax.net;
28
29 import java.io.IOException;
30 import java.net;
31
32
33 /**
34 * This class creates sockets. It may be subclassed by other factories,
35 * which create particular subclasses of sockets and thus provide a general
36 * framework for the addition of public socket-level functionality.
37 *
38 * <P> Socket factories are a simple way to capture a variety of policies
39 * related to the sockets being constructed, producing such sockets in
40 * a way which does not require special configuration of the code which
41 * asks for the sockets: <UL>
42 *
43 * <LI> Due to polymorphism of both factories and sockets, different
44 * kinds of sockets can be used by the same application code just
45 * by passing it different kinds of factories.
46 *
47 * <LI> Factories can themselves be customized with parameters used
48 * in socket construction. So for example, factories could be
49 * customized to return sockets with different networking timeouts
50 * or security parameters already configured.
51 *
52 * <LI> The sockets returned to the application can be subclasses
53 * of java.net.Socket, so that they can directly expose new APIs
54 * for features such as compression, security, record marking,
55 * statistics collection, or firewall tunneling.
56 *
57 * </UL>
58 *
59 * <P> Factory classes are specified by environment-specific configuration
60 * mechanisms. For example, the <em>getDefault</em> method could return
61 * a factory that was appropriate for a particular user or applet, and a
62 * framework could use a factory customized to its own purposes.
63 *
64 * @since 1.4
65 * @see ServerSocketFactory
66 *
67 * @author David Brownell
68 */
69 public abstract class SocketFactory
70 {
71 //
72 // NOTE: JDK 1.1 bug in class GC, this can get collected
73 // even though it's always accessible via getDefault().
74 //
75 private static SocketFactory theFactory;
76
77 /**
78 * Creates a <code>SocketFactory</code>.
79 */
80 protected SocketFactory() { /* NOTHING */ }
81
82
83 /**
84 * Returns a copy of the environment's default socket factory.
85 *
86 * @return the default <code>SocketFactory</code>
87 */
88 public static SocketFactory getDefault()
89 {
90 synchronized (SocketFactory.class) {
91 if (theFactory == null) {
92 //
93 // Different implementations of this method SHOULD
94 // work rather differently. For example, driving
95 // this from a system property, or using a different
96 // implementation than JavaSoft's.
97 //
98 theFactory = new DefaultSocketFactory();
99 }
100 }
101
102 return theFactory;
103 }
104
105
106 /**
107 * Creates an unconnected socket.
108 *
109 * @return the unconnected socket
110 * @throws IOException if the socket cannot be created
111 * @see java.net.Socket#connect(java.net.SocketAddress)
112 * @see java.net.Socket#connect(java.net.SocketAddress, int)
113 * @see java.net.Socket#Socket()
114 */
115 public Socket createSocket() throws IOException {
116 throw new SocketException("Unconnected sockets not implemented");
117 }
118
119
120 /**
121 * Creates a socket and connects it to the specified remote host
122 * at the specified remote port. This socket is configured using
123 * the socket options established for this factory.
124 * <p>
125 * If there is a security manager, its <code>checkConnect</code>
126 * method is called with the host address and <code>port</code>
127 * as its arguments. This could result in a SecurityException.
128 *
129 * @param host the server host name with which to connect, or
130 * <code>null</code> for the loopback address.
131 * @param port the server port
132 * @return the <code>Socket</code>
133 * @throws IOException if an I/O error occurs when creating the socket
134 * @throws SecurityException if a security manager exists and its
135 * <code>checkConnect</code> method doesn't allow the operation.
136 * @throws UnknownHostException if the host is not known
137 * @throws IllegalArgumentException if the port parameter is outside the
138 * specified range of valid port values, which is between 0 and
139 * 65535, inclusive.
140 * @see SecurityManager#checkConnect
141 * @see java.net.Socket#Socket(String, int)
142 */
143 public abstract Socket createSocket(String host, int port)
144 throws IOException, UnknownHostException;
145
146
147 /**
148 * Creates a socket and connects it to the specified remote host
149 * on the specified remote port.
150 * The socket will also be bound to the local address and port supplied.
151 * This socket is configured using
152 * the socket options established for this factory.
153 * <p>
154 * If there is a security manager, its <code>checkConnect</code>
155 * method is called with the host address and <code>port</code>
156 * as its arguments. This could result in a SecurityException.
157 *
158 * @param host the server host name with which to connect, or
159 * <code>null</code> for the loopback address.
160 * @param port the server port
161 * @param localHost the local address the socket is bound to
162 * @param localPort the local port the socket is bound to
163 * @return the <code>Socket</code>
164 * @throws IOException if an I/O error occurs when creating the socket
165 * @throws SecurityException if a security manager exists and its
166 * <code>checkConnect</code> method doesn't allow the operation.
167 * @throws UnknownHostException if the host is not known
168 * @throws IllegalArgumentException if the port parameter or localPort
169 * parameter is outside the specified range of valid port values,
170 * which is between 0 and 65535, inclusive.
171 * @see SecurityManager#checkConnect
172 * @see java.net.Socket#Socket(String, int, java.net.InetAddress, int)
173 */
174 public abstract Socket
175 createSocket(String host, int port, InetAddress localHost, int localPort)
176 throws IOException, UnknownHostException;
177
178
179 /**
180 * Creates a socket and connects it to the specified port number
181 * at the specified address. This socket is configured using
182 * the socket options established for this factory.
183 * <p>
184 * If there is a security manager, its <code>checkConnect</code>
185 * method is called with the host address and <code>port</code>
186 * as its arguments. This could result in a SecurityException.
187 *
188 * @param host the server host
189 * @param port the server port
190 * @return the <code>Socket</code>
191 * @throws IOException if an I/O error occurs when creating the socket
192 * @throws SecurityException if a security manager exists and its
193 * <code>checkConnect</code> method doesn't allow the operation.
194 * @throws IllegalArgumentException if the port parameter is outside the
195 * specified range of valid port values, which is between 0 and
196 * 65535, inclusive.
197 * @throws NullPointerException if <code>host</code> is null.
198 * @see SecurityManager#checkConnect
199 * @see java.net.Socket#Socket(java.net.InetAddress, int)
200 */
201 public abstract Socket createSocket(InetAddress host, int port)
202 throws IOException;
203
204
205 /**
206 * Creates a socket and connect it to the specified remote address
207 * on the specified remote port. The socket will also be bound
208 * to the local address and port suplied. The socket is configured using
209 * the socket options established for this factory.
210 * <p>
211 * If there is a security manager, its <code>checkConnect</code>
212 * method is called with the host address and <code>port</code>
213 * as its arguments. This could result in a SecurityException.
214 *
215 * @param address the server network address
216 * @param port the server port
217 * @param localAddress the client network address
218 * @param localPort the client port
219 * @return the <code>Socket</code>
220 * @throws IOException if an I/O error occurs when creating the socket
221 * @throws SecurityException if a security manager exists and its
222 * <code>checkConnect</code> method doesn't allow the operation.
223 * @throws IllegalArgumentException if the port parameter or localPort
224 * parameter is outside the specified range of valid port values,
225 * which is between 0 and 65535, inclusive.
226 * @throws NullPointerException if <code>address</code> is null.
227 * @see SecurityManager#checkConnect
228 * @see java.net.Socket#Socket(java.net.InetAddress, int,
229 * java.net.InetAddress, int)
230 */
231 public abstract Socket
232 createSocket(InetAddress address, int port,
233 InetAddress localAddress, int localPort)
234 throws IOException;
235 }
236
237
238 //
239 // The default factory has NO intelligence about policies like tunneling
240 // out through firewalls (e.g. SOCKS V4 or V5) or in through them
241 // (e.g. using SSL), or that some ports are reserved for use with SSL.
242 //
243 // Note that at least JDK 1.1 has a low level "plainSocketImpl" that
244 // knows about SOCKS V4 tunneling, so this isn't a totally bogus default.
245 //
246 // ALSO: we may want to expose this class somewhere so other folk
247 // can reuse it, particularly if we start to add highly useful features
248 // such as ability to set connect timeouts.
249 //
250 class DefaultSocketFactory extends SocketFactory {
251
252 public Socket createSocket() {
253 return new Socket();
254 }
255
256 public Socket createSocket(String host, int port)
257 throws IOException, UnknownHostException
258 {
259 return new Socket(host, port);
260 }
261
262 public Socket createSocket(InetAddress address, int port)
263 throws IOException
264 {
265 return new Socket(address, port);
266 }
267
268 public Socket createSocket(String host, int port,
269 InetAddress clientAddress, int clientPort)
270 throws IOException, UnknownHostException
271 {
272 return new Socket(host, port, clientAddress, clientPort);
273 }
274
275 public Socket createSocket(InetAddress address, int port,
276 InetAddress clientAddress, int clientPort)
277 throws IOException
278 {
279 return new Socket(address, port, clientAddress, clientPort);
280 }
281 }
Save This Page