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.