1 /*
   2  * Copyright (c) 2000, 2004, 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 package com.sun.corba.se.spi.legacy.connection;
  27 
  28 import java.net.ServerSocket;
  29 import java.net.Socket;
  30 import java.io.IOException;
  31 
  32 import com.sun.corba.se.spi.ior.IOR;
  33 import com.sun.corba.se.spi.transport.SocketInfo;
  34 
  35 /**
  36  *
  37  * DEPRECATED.  DEPRECATED. DEPRECATED. DEPRECATED. <p>
  38  * DEPRECATED.  DEPRECATED. DEPRECATED. DEPRECATED. <p>
  39  *
  40  * This interface gives one the ability to plug in their own socket
  41  * factory class to an ORB. <p>
  42  *
  43  * Usage: <p>
  44  *
  45  * One specifies a class which implements this interface via the
  46  *
  47  *     <code>ORBConstants.SOCKET_FACTORY_CLASS_PROPERTY</code>
  48  *
  49  * property. <p>
  50  *
  51  * Example:
  52 
  53  * <pre>
  54  *   -Dcom.sun.CORBA.connection.ORBSocketFactoryClass=MySocketFactory
  55  * </pre> <p>
  56  *
  57  * Typically one would use the same socket factory class on both the
  58  * server side and the client side (but this is not required). <p>
  59  *
  60  * A <code>ORBSocketFactory</code> class should have a public default
  61  * constructor which is called once per instantiating ORB.init call.
  62  * That ORB then calls the methods of that <code>ORBSocketFactory</code>
  63  * to obtain client and server sockets. <p>
  64  *
  65  * This interface also supports multiple server end points.  See the
  66  * documentation on <code>createServerSocket</code> below.
  67  *
  68  */
  69 
  70 public interface ORBSocketFactory
  71 {
  72     /**
  73      * DEPRECATED.  DEPRECATED. DEPRECATED. DEPRECATED. <p>
  74      *
  75      * A server ORB always creates an "IIOP_CLEAR_TEXT" listening port.
  76      * That port is put into IOP profiles of object references exported
  77      * by an ORB. <p>
  78      *
  79      * If
  80      *
  81      *     <code>createServerSocket(String type, int port)</code>
  82      *
  83      * is passed <code>IIOP_CLEAR_TEXT</code> as a <code>type</code>
  84      * argument it should then call and return
  85      *
  86      *     <code>new java.net.ServerSocket(int port)</code> <p>
  87      *
  88      * If
  89      *
  90      *     <code>createSocket(SocketInfo socketInfo)</code>
  91      *
  92      * is passed <code>IIOP_CLEAR_TEXT</code> in
  93      * <code>socketInfo.getType()</code> it should
  94      * then call and return
  95      *
  96      * <pre>
  97      *     new java.net.Socket(socketInfo.getHost(),
  98      *                         socketInfo.getPort())
  99      * </pre>
 100      *
 101      */
 102     public static final String IIOP_CLEAR_TEXT = "IIOP_CLEAR_TEXT";
 103 
 104 
 105     /**
 106      * DEPRECATED.  DEPRECATED. DEPRECATED. DEPRECATED. <p>
 107      *
 108      * This method is used by a server side ORB. <p>
 109      *
 110      * When an ORB needs to create a listen socket on which connection
 111      * requests are accepted it calls
 112      *
 113      *     <code>createServerSocket(String type, int port)</code>.
 114      *
 115      * The type argument says which type of socket should be created. <p>
 116      *
 117      * The interpretation of the type argument is the responsibility of
 118      * an instance of <code>ORBSocketFactory</code>, except in the case
 119      * of <code>IIOP_CLEAR_TEXT</code>, in which case a standard server
 120      * socket should be created. <p>
 121      *
 122      *
 123      * Multiple Server Port API: <p>
 124      *
 125      * In addition to the IIOP_CLEAR_TEXT listening port, it is possible
 126      * to specify that an ORB listen on additional port of specific types. <p>
 127      *
 128      * This API allows one to specify that an ORB should create an X,
 129      * or an X and a Y listen socket. <p>
 130      *
 131      * If X, to the user, means SSL, then one just plugs in an SSL
 132      * socket factory. <p>
 133      *
 134      * Or, another example, if X and Y, to the user, means SSL without
 135      * authentication and SSL with authentication respectively, then they
 136      * plug in a factory which will either create an X or a Y socket
 137      * depending on the type given to
 138      *
 139      *     <code>createServerSocket(String type, int port)</code>. <p>
 140      *
 141      * One specifies multiple listening ports (in addition to the
 142      * default IIOP_CLEAR_TEXT port) using the
 143      *
 144      *     <code>ORBConstants.LISTEN_SOCKET_PROPERTY</code>
 145      *
 146      * property. <p>
 147      *
 148      * Example usage:
 149      *
 150      * <pre>
 151      *    ... \
 152      *    -Dcom.sun.CORBA.connection.ORBSocketFactoryClass=com.my.MySockFact \
 153      *    -Dcom.sun.CORBA.connection.ORBListenSocket=SSL:0,foo:1 \
 154      *    ...
 155      * </pre>
 156      *
 157      * The meaning of the "type" (SSL and foo above) is controlled
 158      * by the user. <p>
 159      *
 160      * ORBListenSocket is only meaningful for servers. <p>
 161      *
 162      * The property value is interpreted as follows.  For each
 163      * type/number pair: <p>
 164      *
 165      * If number is 0 then use an emphemeral port for the listener of
 166      * the associated type. <p>
 167      *
 168      * If number is greater than 0 use that port number. <p>
 169      *
 170      * An ORB creates a listener socket for each type
 171      * specified by the user by calling
 172      *
 173      *    <code>createServerSocket(String type, int port)</code>
 174      *
 175      * with the type specified by the user. <p>
 176      *
 177      * After an ORB is initialized and the RootPOA has been resolved,
 178      * it is then listening on
 179      * all the end points which were specified.  It may be necessary
 180      * to add this additional end point information to object references
 181      * exported by this ORB.  <p>
 182      *
 183      * Each object reference will contain the ORB's default IIOP_CLEAR_TEXT
 184      * end point in its IOP profile.  To add additional end point information
 185      * (i.e., an SSL port) to an IOR (i.e., an object reference) one needs
 186      * to intercept IOR creation using
 187      * an <code>PortableInterceptor::IORInterceptor</code>. <p>
 188      *
 189      * Using PortableInterceptors (with a non-standard extension): <p>
 190      *
 191      * Register an <code>IORInterceptor</code>.  Inside its
 192      * <code>establish_components</code> operation:
 193      *
 194      * <pre>
 195      *
 196      * com.sun.corba.se.spi.legacy.interceptor.IORInfoExt ext;
 197      * ext = (com.sun.corba.se.spi.legacy.interceptor.IORInfoExt)info;
 198      *
 199      * int port = ext.getServerPort("myType");
 200      *
 201      * </pre>
 202      *
 203      * Once you have the port you may add information to references
 204      * created by the associated adapter by calling
 205      *
 206      *    <code>IORInfo::add_ior_component</code><p>
 207      *
 208      *
 209      * Note: if one is using a POA and the lifespan policy of that
 210      * POA is persistent then the port number returned
 211      * by <code>getServerPort</code> <em>may</em>
 212      * be the corresponding ORBD port, depending on whether the POA/ORBD
 213      * protocol is the present port exchange or if, in the future,
 214      * the protocol is based on object reference template exchange.
 215      * In either
 216      * case, the port returned will be correct for the protocol.
 217      * (In more detail, if the port exchange protocol is used then
 218      * getServerPort will return the ORBD's port since the port
 219      * exchange happens before, at ORB initialization.
 220      * If object reference
 221      * exchange is used then the server's transient port will be returned
 222      * since the templates are exchanged after adding components.) <p>
 223      *
 224      *
 225      * Persistent object reference support: <p>
 226      *
 227      * When creating persistent object references with alternate
 228      * type/port info, ones needs to configure the ORBD to also support
 229      * this alternate info.  This is done as follows: <p>
 230      *
 231      * - Give the ORBD the same socket factory you gave to the client
 232      * and server. <p>
 233      *
 234      * - specify ORBListenSocket ports of the same types that your
 235      * servers support.  You should probably specify explicit port
 236      * numbers for ORBD if you embed these numbers inside IORs. <p>
 237      *
 238      * Note: when using the port exchange protocol
 239      * the ORBD and servers will exchange port
 240      * numbers for each given type so they know about each other.
 241      * When using object reference template exchange the server's
 242      * transient ports are contained in the template. <p>
 243      *
 244      *
 245      * - specify your <code>BadServerIdHandler</code> (discussed below)
 246      * using the
 247      *
 248      *    <code>ORBConstants.BAD_SERVER_ID_HANDLER_CLASS_PROPERTY</code> <p>
 249      *
 250      * Example:
 251      *
 252      * <pre>
 253      *
 254      * -Dcom.sun.CORBA.POA.ORBBadServerIdHandlerClass=corba.socketPersistent.MyBadServerIdHandler
 255      *
 256      * </pre>
 257      *
 258      * The <code>BadServerIdHandler</code> ...<p>
 259      *
 260      * See <code>com.sun.corba.se.impl.activation.ServerManagerImpl.handle</code>
 261      * for example code on writing a bad server id handler.  NOTE:  This
 262      * is an unsupported internal API.  It will not exist in future releases.
 263      * <p>
 264      *
 265      *
 266      * Secure connections to other services: <p>
 267      *
 268      * If one wants secure connections to other services such as
 269      * Naming then one should configure them with the same
 270      *
 271      *     <code>SOCKET_FACTORY_CLASS_PROPERTY</code> and
 272      *     <code>LISTEN_SOCKET_PROPERTY</code>
 273      *
 274      * as used by other clients and servers in your distributed system.
 275      *
 276      */
 277     public ServerSocket createServerSocket(String type, int port)
 278         throws
 279             IOException;
 280 
 281 
 282 
 283     /**
 284      * DEPRECATED.  DEPRECATED. DEPRECATED. DEPRECATED. <p>
 285      *
 286      * This method is used by a client side ORB. <p>
 287      *
 288      * Each time a client invokes on an object reference, the reference's
 289      * associated ORB will call
 290      *
 291      * <pre>
 292      *    getEndPointInfo(ORB orb,
 293      *                    IOR ior,
 294      *                    SocketInfo socketInfo)
 295      * </pre>
 296      *
 297      * NOTE: The type of the <code>ior</code> argument is an internal
 298      * representation for efficiency.  If the <code>ORBSocketFactory</code>
 299      * interface ever becomes standardized then the <code>ior</code> will
 300      * most likely change to a standard type (e.g., a stringified ior,
 301      * an <code>org.omg.IOP.IOR</code>, or ...). <p>
 302      *
 303      * Typically, this method will look at tagged components in the
 304      * given <code>ior</code> to determine what type of socket to create. <p>
 305      *
 306      * Typically, the <code>ior</code> will contain a tagged component
 307      * specifying an alternate port type and number.  <p>
 308      *
 309      * This method should return an <code>SocketInfo</code> object
 310      * containing the type/host/port to be used for the connection.
 311      *
 312      * If there are no appropriate tagged components then this method
 313      * should return an <code>SocketInfo</code> object with the type
 314      * <code>IIOP_CLEAR_TEXT</code> and host/port from the ior's IOP
 315      * profile. <p>
 316      *
 317      * If the ORB already has an existing connection to the returned
 318      * type/host/port, then that connection is used.  Otherwise the ORB calls
 319      *
 320      *    <code>createSocket(SocketInfo socketInfo)</code> <p>
 321      *
 322      * The <code>orb</code> argument is useful for handling
 323      * the <code>ior</code> argument. <p>
 324      *
 325      * The <code>SocketInfo</code> given to <code>getEndPointInfo</code>
 326      * is either null or an object obtained
 327      * from <code>GetEndPointInfoAgainException</code>
 328      *
 329      */
 330     public SocketInfo getEndPointInfo(org.omg.CORBA.ORB orb,
 331                                         IOR ior,
 332                                         SocketInfo socketInfo);
 333 
 334 
 335     /**
 336      * DEPRECATED.  DEPRECATED. DEPRECATED. DEPRECATED. <p>
 337      *
 338      * This method is used by a client side ORB. <p>
 339      *
 340      * This method should return a client socket of the given
 341      * type/host/port. <p>
 342      *
 343      * Note: the <code>SocketInfo</code> is the same instance as was
 344      * returned by <code>getSocketInfo</code> so extra cookie info may
 345      * be attached. <p>
 346      *
 347      * If this method throws GetEndPointInfoAgainException then the
 348      * ORB calls <code>getEndPointInfo</code> again, passing it the
 349      * <code>SocketInfo</code> object contained in the exception.
 350      *
 351      */
 352     public Socket createSocket(SocketInfo socketInfo)
 353         throws
 354             IOException,
 355             GetEndPointInfoAgainException;
 356 }
 357 
 358 // End of file.