/*
 * @(#)ORBSocketFactory.java	1.7 03/01/23
 *
 * Copyright 2003 Sun Microsystems, Inc. All rights reserved.
 * SUN PROPRIETARY/CONFIDENTIAL. Use is subject to license terms.
 */

package com.sun.corba.se.connection;

import java.net.ServerSocket;
import java.net.Socket;
import java.io.IOException;

import com.sun.corba.se.internal.core.IOR;

/**
 * 
 * This interface gives one the ability to plug in their own socket
 * factory class to an ORB. <p>
 *
 * Usage: <p>
 *
 * One specifies a class which implements this interface via the 
 *
 *     <code>ORBConstants.SOCKET_FACTORY_CLASS_PROPERTY</code>
 *
 * property. <p>
 * 
 * Example: <p>

 * <pre>
 *   -Dcom.sun.CORBA.connection.ORBSocketFactoryClass=MySocketFactory
 * </pre> <p>
 *
 * Typically one would use the same socket factory class on both the
 * server side and the client side (but this is not required). <p>
 *
 * A <code>ORBSocketFactory</code> class should have a public default
 * constructor which is called once per instantiating ORB.init call. 
 * That ORB then calls the methods of that <code>ORBSocketFactory</code>
 * to obtain client and server sockets. <p>
 *
 * This interface also supports multiple server end points.  See the
 * documentation on <code>createServerSocket</code> below. 
 *
 */

public interface ORBSocketFactory
{
    /**
     * A server ORB always creates an "IIOP_CLEAR_TEXT" listening port.
     * That port is put into IOP profiles of object references exported
     * by an ORB. <p>
     *
     * If 
     *
     *     <code>createServerSocket(String type, int port)</code> 
     *
     * is passed <code>IIOP_CLEAR_TEXT</code> as a <code>type</code>
     * argument it should then call and return 
     *
     *     <code>new java.net.ServerSocket(int port)</code> <p>
     *
     * If
     *
     *     <code>createSocket(EndPointInfo endPointInfo)</code>
     *
     * is passed <code>IIOP_CLEAR_TEXT</code> in
     * <code>endPointInfo.getType()</code> it should
     * then call and return
     *
     * <pre>
     *     new java.net.Socket(endPointInfo.getHost(),
     *                         endPointInfo.getPort())
     * </pre>
     *
     */
    public static final String IIOP_CLEAR_TEXT = "IIOP_CLEAR_TEXT";


    /**
     * This method is used by a server side ORB. <p>
     *
     * When an ORB needs to create a listen socket on which connection
     * requests are accepted it calls
     *
     *     <code>createServerSocket(String type, int port)</code>. 
     *
     * The type argument says which type of socket should be created. <p>
     *
     * The interpretation of the type argument is the responsibility of
     * an instance of <code>ORBSocketFactory</code>, except in the case
     * of <code>IIOP_CLEAR_TEXT</code>, in which case a standard server
     * socket should be created. <p>
     * 
     *
     * Multiple Server Port API: <p>
     *
     * In addition to the IIOP_CLEAR_TEXT listening port, it is possible
     * to specify that an ORB listen on additional port of specific types. <p>
     *
     * This API allows one to specify that an ORB should create an X,
     * or an X and a Y listen socket. <p>
     *
     * If X, to the user, means SSL, then one just plugs in an SSL
     * socket factory. <p>
     *
     * Or, another example, if X and Y, to the user, means SSL without
     * authentication and SSL with authentication respectively, then they
     * plug in a factory which will either create an X or a Y socket
     * depending on the type given to
     *
     *     <code>createServerSocket(String type, int port)</code>. <p>
     *
     * One specifies multiple listening ports (in addition to the
     * default IIOP_CLEAR_TEXT port) using the
     *
     *     <code>ORBConstants.LISTEN_SOCKET_PROPERTY</code>
     *
     * property. <p>
     *
     * Example usage:<p>
     *
     * <pre>
     *    ... \ 
     *    -Dcom.sun.CORBA.connection.ORBSocketFactory=com.my.MySockFact \
     *    -Dcom.sun.CORBA.connection.ORBListenSocket=SSL:0,foo:1 \
     *    ... 
     * </pre>
     *
     * The meaning of the "type" (SSL and foo above) is controlled 
     * by the user. <p>
     *
     * ORBListenSocket is only meaningful for servers. <p>
     *
     * The property value is interpreted as follows.  For each
     * type/number pair: <p>
     *
     * If number is 0 then use an emphemeral port for the listener of
     * the associated type. <p>
     *
     * If number is greater then 0 use that port number. <p>
     * 
     * An ORB creates a listener socket for each type
     * specified by the user by calling
     *
     *    <code>createServerSocket(String type, int port)</code>
     *
     * with the type specified by the user. <p>
     *
     * After an ORB is initialized and the RootPOA has been resolved,
     * it is then listening on
     * all the end points which were specified.  It may be necessary
     * to add this additional end point information to object references
     * exported by this ORB.  <p>
     * 
     * Each object reference will contain the ORB's default IIOP_CLEAR_TEXT
     * end point in its IOP profile.  To add additional end point information
     * (i.e., an SSL port) to an IOR (i.e., an object reference) one needs
     * to intercept IOR creation.  The are two ways to do that.  Use
     * the deprecated <code>objectReferenceCreated</code> hook or
     * use an <code>PortableInterceptor::IORInterceptor</code>.  Both
     * of these techniques are now discussed. <p>
     *
     * 
     * Deprecated <code>objectReferenceCreated</code> interceptor: <p>
     *
     * Define an ORB which extends
     *
     *    <code>POA.POAORB</code>
     *
     * and overrides the
     *
     *    <code>objectReferenceCreated(IOR ior)</code>
     *
     * method. Inside that method one calls
     *
     *    <code>getServerPort(String type)</code>
     * 
     * (a method on the ORB) giving it
     * a type specified via <code>ORBListenSocket</code>.
     * <code>getServerPort</code> returns the listen port for the given
     * type. <p>
     *
     * Typically one would add this port number and type to
     * some tagged component chosen by the user to represent this
     * information.  This tagged component would then be added to
     * <code>objectReferenceCreated</code>'s <code>IOR</code> argument
     * and the augmented <code>IOR</code> would be returned. <p> <p>
     *
     *
     * Using PortableInterceptors (with a non-standard extension): <p>
     *
     * Register an <code>IORInterceptor</code>.  Inside its
     * <code>establish_components</code> operation:
     *
     * <pre>
     *
     * com.sun.corba.se.interceptor.IORInfoExt ext;
     * ext = (com.sun.corba.se.interceptor.IORInfoExt)info;
     *
     * int port = ext.getServerPort("myType");
     *
     * </pre>
     * 
     * Once you have the port you may add information to references
     * created by the associated adapter by calling
     *
     *    <code>IORInfo::add_ior_component</code><p> <p>
     * 
     *
     * Note: if one is using a POA and the lifespan policy of that
     * POA is persistent then the port number returned 
     * by <code>getServerPort</code> <em>may</em>
     * be the corresponding ORBD port, depending on whether the POA/ORBD
     * protocol is the present port exchange or if, in the future,
     * the protocol is based on object reference template exchange.
     * In either
     * case, the port returned will be correct for the protocol.
     * (In more detail, if the port exchange protocol is used then
     * getServerPort will return the ORBD's port since the port
     * exchange happens before, at ORB initialization.
     * If object reference
     * exchange is used then the server's transient port will be returned
     * since the templates are exchanged after adding components.) <p>
     * 
     *
     * Persistent object reference support: <p>
     *
     * When creating persistent object references with alternate
     * type/port info, ones needs to configure the ORBD to also support
     * this alternate info.  This is done as follows: <p>
     *
     * - Give the ORBD the same socket factory you gave to the client
     * and server. <p>
     *
     * - specify ORBListenSocket ports of the same types that your
     * servers support.  You should probably specify explicit port
     * numbers for ORBD if you embed these numbers inside IORs. <p>
     *
     * Note: when using the port exchange protocol
     * the ORBD and servers will exchange port
     * numbers for each given type so they know about each other. 
     * When using object reference template exchange the server's
     * transient ports are contained in the template. <p>
     *
     *
     * - specify your <code>BadServerIdHandler</code> (discussed below)
     * using the
     *
     *    <code>ORBConstants.BAD_SERVER_ID_HANDLER_CLASS_PROPERTY</code> <p>
     *
     * Example: <p>
     *
     * <pre>
     *
     * -Dcom.sun.CORBA.POA.ORBBadServerIdHandlerClass=corba.socketPersistent.MyBadServerIdHandler
     *
     * </pre>
     * 
     * The <code>BadServerIdHandler</code> ...<p>
     *
     * See <code>com.sun.corba.se.internal.Activation.ServerManagerImpl.handle</code>
     * for example code on writing a bad server id handler.  NOTE:  This
     * is an unsupported internal API.  It will not exist in future releases. 
     * <p>
     *
     *
     * Secure connections to other services: <p>
     *
     * If one wants secure connections to other services such as
     * Naming then one should configure them with the same
     *
     *     <code>SOCKET_FACTORY_CLASS_PROPERTY</code> and
     *     <code>LISTEN_SOCKET_PROPERTY</code>
     *
     * as used by other clients and servers in your distributed system. <p>
     *
     */
    public ServerSocket createServerSocket(String type, int port)
        throws 
	    IOException;



    /**
     * This method is used by a client side ORB. <p>
     *
     * Each time a client invokes on an object reference, the reference's
     * associated ORB will call
     *
     * <pre>
     *    getEndPointInfo(ORB orb, 
     *                    com.sun.corba.se.internal.core.IOR ior,
     *                    EndPointInfo endPointInfo)
     * </pre>
     *
     * NOTE: The type of the <code>ior</code> argument is an internal
     * representation for efficiency.  If the <code>ORBSocketFactory</code>
     * interface ever becomes standardized then the <code>ior</code> will
     * most likely change to a standard type (e.g., a stringified ior,
     * an <code>org.omg.IOP.IOR</code>, or ...). <p>
     *
     * Typically, this method will look at tagged components in the
     * given <code>ior</code> to determine what type of socket to create. <p>
     *
     * Typically, the <code>ior</code> will contain a tagged component
     * specifying an alternate port type and number.  <p>
     *
     * This method should return an <code>EndPointInfo</code> object
     * containing the type/host/port to be used for the connection.
     *
     * If there are no appropriate tagged components then this method
     * should return an <code>EndPointInfo</code> object with the type
     * <code>IIOP_CLEAR_TEXT</code> and host/port from the ior's IOP
     * profile. <p>
     *
     * If the ORB already has an existing connection to the returned
     * type/host/port, then that connection is used.  Otherwise the ORB calls
     *
     *    <code>createSocket(EndPointInfo endPointInfo)</code> <p>
     *
     * The <code>orb</code> argument is useful for handling
     * the <code>ior</code> argument. <p>
     *
     * The <code>EndpointInfo</code> given to <code>getEndPointInfo</code>
     * is either null or an object obtained
     * from <code>GetEndPointInfoAgainException</code> <p>
     *
     */
    public EndPointInfo getEndPointInfo(org.omg.CORBA.ORB orb,
					IOR ior,
					EndPointInfo endPointInfo);


    /**
     * This method is used by a client side ORB. <p>
     *
     * This method should return a client socket of the given
     * type/host/port. <p>
     *
     * Note: the <code>EndPointInfo</code> is the same instance as was
     * returned by <code>getEndPointInfo</code> so extra cookie info may
     * be attached. <p>
     * 
     * If this method throws GetEndPointInfoAgainException then the
     * ORB calls <code>getEndPointInfo</code> again, passing it the
     * <code>EndPointInfo</code> object contained in the exception. <p>
     *
     */
    public Socket createSocket(EndPointInfo endPointInfo)
        throws
	    IOException,
	    GetEndPointInfoAgainException;
}

// End of file.