1/*
2 * Copyright (c) 1997, 2010, 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
27package javax.net;
28
29import java.io.IOException;
30import java.net.InetAddress;
31import java.net.Socket;
32import java.net.SocketException;
33import 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 */
71public 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//
262class 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}
294