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 
  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 }