/*
* Copyright (c) 1997, 2010, Oracle and/or its affiliates. All rights reserved.
* DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
*
* This code is free software; you can redistribute it and/or modify it
* under the terms of the GNU General Public License version 2 only, as
* published by the Free Software Foundation. Oracle designates this
* particular file as subject to the "Classpath" exception as provided
* by Oracle in the LICENSE file that accompanied this code.
*
* This code is distributed in the hope that it will be useful, but WITHOUT
* ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
* FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
* version 2 for more details (a copy is included in the LICENSE file that
* accompanied this code).
*
* You should have received a copy of the GNU General Public License version
* 2 along with this work; if not, write to the Free Software Foundation,
* Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
*
* Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
* or visit www.oracle.com if you need additional information or have any
* questions.
*/
package javax.net;
import java.io.IOException;
import java.net.InetAddress;
import java.net.Socket;
import java.net.SocketException;
import java.net.UnknownHostException;
/**
* This class creates sockets. It may be subclassed by other factories,
* which create particular subclasses of sockets and thus provide a general
* framework for the addition of public socket-level functionality.
*
* <P> Socket factories are a simple way to capture a variety of policies
* related to the sockets being constructed, producing such sockets in
* a way which does not require special configuration of the code which
* asks for the sockets: <UL>
*
* <LI> Due to polymorphism of both factories and sockets, different
* kinds of sockets can be used by the same application code just
* by passing it different kinds of factories.
*
* <LI> Factories can themselves be customized with parameters used
* in socket construction. So for example, factories could be
* customized to return sockets with different networking timeouts
* or security parameters already configured.
*
* <LI> The sockets returned to the application can be subclasses
* of java.net.Socket, so that they can directly expose new APIs
* for features such as compression, security, record marking,
* statistics collection, or firewall tunneling.
*
* </UL>
*
* <P> Factory classes are specified by environment-specific configuration
* mechanisms. For example, the <em>getDefault</em> method could return
* a factory that was appropriate for a particular user or applet, and a
* framework could use a factory customized to its own purposes.
*
* @since 1.4
* @see ServerSocketFactory
*
* @author David Brownell
*/
public abstract class SocketFactory
{
//
// NOTE: JDK 1.1 bug in class GC, this can get collected
// even though it's always accessible via getDefault().
//
private static SocketFactory theFactory;
/**
* Creates a <code>SocketFactory</code>.
*/
protected SocketFactory() { /* NOTHING */ }
/**
* Returns a copy of the environment's default socket factory.
*
* @return the default <code>SocketFactory</code>
*/
public static SocketFactory getDefault()
{
synchronized (SocketFactory.class) {
if (theFactory == null) {
//
// Different implementations of this method SHOULD
// work rather differently. For example, driving
// this from a system property, or using a different
// implementation than JavaSoft's.
//
theFactory = new DefaultSocketFactory();
}
}
return theFactory;
}
/**
* Creates an unconnected socket.
*
* @return the unconnected socket
* @throws IOException if the socket cannot be created
* @see java.net.Socket#connect(java.net.SocketAddress)
* @see java.net.Socket#connect(java.net.SocketAddress, int)
* @see java.net.Socket#Socket()
*/
public Socket createSocket() throws IOException {
//
// bug 6771432:
// The Exception is used by HttpsClient to signal that
// unconnected sockets have not been implemented.
//
UnsupportedOperationException uop = new
UnsupportedOperationException();
SocketException se = new SocketException(
"Unconnected sockets not implemented");
se.initCause(uop);
throw se;
}
/**
* Creates a socket and connects it to the specified remote host
* at the specified remote port. This socket is configured using
* the socket options established for this factory.
* <p>
* If there is a security manager, its <code>checkConnect</code>
* method is called with the host address and <code>port</code>
* as its arguments. This could result in a SecurityException.
*
* @param host the server host name with which to connect, or
* <code>null</code> for the loopback address.
* @param port the server port
* @return the <code>Socket</code>
* @throws IOException if an I/O error occurs when creating the socket
* @throws SecurityException if a security manager exists and its
* <code>checkConnect</code> method doesn't allow the operation.
* @throws UnknownHostException if the host is not known
* @throws IllegalArgumentException if the port parameter is outside the
* specified range of valid port values, which is between 0 and
* 65535, inclusive.
* @see SecurityManager#checkConnect
* @see java.net.Socket#Socket(String, int)
*/
public abstract Socket createSocket(String host, int port)
throws IOException, UnknownHostException;
/**
* Creates a socket and connects it to the specified remote host
* on the specified remote port.
* The socket will also be bound to the local address and port supplied.
* This socket is configured using
* the socket options established for this factory.
* <p>
* If there is a security manager, its <code>checkConnect</code>
* method is called with the host address and <code>port</code>
* as its arguments. This could result in a SecurityException.
*
* @param host the server host name with which to connect, or
* <code>null</code> for the loopback address.
* @param port the server port
* @param localHost the local address the socket is bound to
* @param localPort the local port the socket is bound to
* @return the <code>Socket</code>
* @throws IOException if an I/O error occurs when creating the socket
* @throws SecurityException if a security manager exists and its
* <code>checkConnect</code> method doesn't allow the operation.
* @throws UnknownHostException if the host is not known
* @throws IllegalArgumentException if the port parameter or localPort
* parameter is outside the specified range of valid port values,
* which is between 0 and 65535, inclusive.
* @see SecurityManager#checkConnect
* @see java.net.Socket#Socket(String, int, java.net.InetAddress, int)
*/
public abstract Socket
createSocket(String host, int port, InetAddress localHost, int localPort)
throws IOException, UnknownHostException;
/**
* Creates a socket and connects it to the specified port number
* at the specified address. This socket is configured using
* the socket options established for this factory.
* <p>
* If there is a security manager, its <code>checkConnect</code>
* method is called with the host address and <code>port</code>
* as its arguments. This could result in a SecurityException.
*
* @param host the server host
* @param port the server port
* @return the <code>Socket</code>
* @throws IOException if an I/O error occurs when creating the socket
* @throws SecurityException if a security manager exists and its
* <code>checkConnect</code> method doesn't allow the operation.
* @throws IllegalArgumentException if the port parameter is outside the
* specified range of valid port values, which is between 0 and
* 65535, inclusive.
* @throws NullPointerException if <code>host</code> is null.
* @see SecurityManager#checkConnect
* @see java.net.Socket#Socket(java.net.InetAddress, int)
*/
public abstract Socket createSocket(InetAddress host, int port)
throws IOException;
/**
* Creates a socket and connect it to the specified remote address
* on the specified remote port. The socket will also be bound
* to the local address and port suplied. The socket is configured using
* the socket options established for this factory.
* <p>
* If there is a security manager, its <code>checkConnect</code>
* method is called with the host address and <code>port</code>
* as its arguments. This could result in a SecurityException.
*
* @param address the server network address
* @param port the server port
* @param localAddress the client network address
* @param localPort the client port
* @return the <code>Socket</code>
* @throws IOException if an I/O error occurs when creating the socket
* @throws SecurityException if a security manager exists and its
* <code>checkConnect</code> method doesn't allow the operation.
* @throws IllegalArgumentException if the port parameter or localPort
* parameter is outside the specified range of valid port values,
* which is between 0 and 65535, inclusive.
* @throws NullPointerException if <code>address</code> is null.
* @see SecurityManager#checkConnect
* @see java.net.Socket#Socket(java.net.InetAddress, int,
* java.net.InetAddress, int)
*/
public abstract Socket
createSocket(InetAddress address, int port,
InetAddress localAddress, int localPort)
throws IOException;
}
//
// The default factory has NO intelligence about policies like tunneling
// out through firewalls (e.g. SOCKS V4 or V5) or in through them
// (e.g. using SSL), or that some ports are reserved for use with SSL.
//
// Note that at least JDK 1.1 has a low level "plainSocketImpl" that
// knows about SOCKS V4 tunneling, so this isn't a totally bogus default.
//
// ALSO: we may want to expose this class somewhere so other folk
// can reuse it, particularly if we start to add highly useful features
// such as ability to set connect timeouts.
//
class DefaultSocketFactory extends SocketFactory {
public Socket createSocket() {
return new Socket();
}
public Socket createSocket(String host, int port)
throws IOException, UnknownHostException
{
return new Socket(host, port);
}
public Socket createSocket(InetAddress address, int port)
throws IOException
{
return new Socket(address, port);
}
public Socket createSocket(String host, int port,
InetAddress clientAddress, int clientPort)
throws IOException, UnknownHostException
{
return new Socket(host, port, clientAddress, clientPort);
}
public Socket createSocket(InetAddress address, int port,
InetAddress clientAddress, int clientPort)
throws IOException
{
return new Socket(address, port, clientAddress, clientPort);
}
}