ORBSocketFactory.java revision 608:7e06bf1dcb09 
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
26package com.sun.corba.se.spi.legacy.connection;
27
28import java.net.ServerSocket;
29import java.net.Socket;
30import java.io.IOException;
31
32import com.sun.corba.se.spi.ior.IOR;
33import 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
70public 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.
359