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