ORBSocketFactory


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