001: /*
002: * SocketFactory.java
003: *
004: * Brazil project web application Framework,
005: * export version: 1.1
006: * Copyright (c) 1999-2000 Sun Microsystems, Inc.
007: *
008: * Sun Public License Notice
009: *
010: * The contents of this file are subject to the Sun Public License Version
011: * 1.0 (the "License"). You may not use this file except in compliance with
012: * the License. A copy of the License is included as the file "license.terms",
013: * and also available at http://www.sun.com/
014: *
015: * The Original Code is from:
016: * Brazil project web application Framework release 1.1.
017: * The Initial Developer of the Original Code is: cstevens.
018: * Portions created by cstevens are Copyright (C) Sun Microsystems, Inc.
019: * All Rights Reserved.
020: *
021: * Contributor(s): cstevens, suhler.
022: *
023: * Version: 1.8
024: * Created by cstevens on 99/09/15
025: * Last modified by cstevens on 00/03/10 17:12:29
026: */
027:
028: package sunlabs.brazil.util;
029:
030: import java.io.IOException;
031: import java.net.Socket;
032:
033: /**
034: * This interface is used as a heap to control the allocation of sockets.
035: * <p>
036: * An instance of this interface can be passed to methods that allocate
037: * sockets. In this way, the actual, underlying type of socket allocated
038: * can be replaced (for instance, with an SSL socket or an firewall-tunnelling
039: * socket), without the user of the socket having to explicitly be aware of
040: * the underlying implementation.
041: * <p>
042: * In some ways, this class is a replacement for the
043: * <code>SocketImplFactory</code> class. This class addresses the following
044: * issues. <ul>
045: * <li>
046: * A <code>SocketImplFactory</code> may be installed only once for the entire
047: * process, so different policies cannot be used concurrently and/or
048: * consectively. For instance, imagine a situation where the user wants one
049: * part of the program talking via SSL to some port on machine A and via
050: * standard sockets to some port on machine B. It is not possible to
051: * install separate <code>SocketImplFactory</code> objects to allow both.
052: * <li>
053: * The standard <code>Socket</code> class presumes a highly-connected network
054: * with the ability to resolve hostnames to IP addresses. The standard
055: * <code>Socket</code> class always converts the hostname to an IP address
056: * before calling <code>SocketImplFactory</code>. If the hostname does not
057: * have an IP address, then the <code>SocketImplFactory</code> never gets a
058: * chance to intercept the host name and perform alternate routing based on
059: * the name. For instance, imagine that the user has implemented a
060: * firewall-tunnelling socket; the raw hostname must be passed to the
061: * firewall machine, which allows the socket to be established once some
062: * out-of-band credentials are supplied. But we could never get this far
063: * because the standard <code>Socket</code> class would have already rejected
064: * the request since the IP address of the target machine was unknown.
065: * </ul>
066: *
067: * @author Colin Stevens (colin.stevens@sun.com)
068: * @version 1.8, 00/03/10
069: */
070: public interface SocketFactory {
071: /**
072: * The default socket factory. It just creates a standard
073: * <code>Socket</code> to the specified host and port, and is exactly
074: * equivalent to calling <code>new Socket(host, port)</code>.
075: */
076: public final SocketFactory defaultFactory = new DefaultSocketFactory();
077:
078: /**
079: * Creates a new <code>Socket</code> that talks to the specified port
080: * on the named host.
081: * <p>
082: * The implementation may choose any way it wants to provide a
083: * socket-like object (essentially any mechanism that supports
084: * bidirectional communication). The returned <code>Socket</code> (or
085: * subclass of <code>Socket</code>) might not be based on TCP/IP, or it
086: * might involve running a TCP/IP stack over some other protocol, or it
087: * might actually redirect all connections via some other proxy machine,
088: * etc.
089: *
090: * @param host
091: * The host name.
092: *
093: * @param port
094: * The port number.
095: *
096: * @return An object that provides socket-like communication.
097: *
098: * @throws IOException
099: * If there is some problem establishing the socket to the
100: * specified port on the named host.
101: */
102: public Socket newSocket(String host, int port) throws IOException;
103: }
104:
105: class DefaultSocketFactory implements SocketFactory {
106: public Socket newSocket(String host, int port) throws IOException {
107: return new Socket(host, port);
108: }
109: }
|