View Javadoc
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: <p>
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:<p>
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 then 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> <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: <p>
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. <p>
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> <p>
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. <p>
350      *
351      */
352     public Socket createSocket(SocketInfo socketInfo)
353         throws
354             IOException,
355             GetEndPointInfoAgainException;
356 }
357 
358 // End of file.