ObjectAdapter


1   /*
2    * @(#)ObjectAdapter.java   1.27 03/12/19
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.oa ;
9   
10  import org.omg.CORBA.Policy   ;
11  
12  import org.omg.PortableInterceptor.ObjectReferenceTemplate   ;
13  import org.omg.PortableInterceptor.ObjectReferenceFactory   ;
14  
15  import com.sun.corba.se.spi.orb.ORB ;
16  
17  import com.sun.corba.se.spi.oa.OADestroyed ;
18  
19  import com.sun.corba.se.spi.ior.IORTemplate ;
20  
21  // REVISIT: What should the order be?  enter/push...pop/exit?
22  
23  /** ObjectAdapter represents the abstract model of an object
24  * adapter that was introduced by ORT.  This means that all
25  * object adapters must:
26  * <UL>
27  * <LI>Have an ORB</LI>
28  * <LI>Have a name</LI>
29  * <LI>Have an adapter manager (represented by an ID)</LI>
30  * <LI>Have an adapter template</LI>
31  * <LI>Support getting and setting their ObjectReferenceFactory</LI>
32  * <LI>Provide access to their current state</LI>
33  * <LI>Support adding components to their profiles expressed in the adapter template</LI>
34  * </UL>
35  * Other requirements:
36  * <UL>
37  * <LI>All object adapters must invoke ORB.AdapterCreated when they are created.
38  * </LI>
39  * <LI>All adapter managers must invoke ORB.AdapterManagerStateChanged when
40  * their state changes, mapping the internal state to an ORT state.</LI>
41  * <LI>AdapterStateChanged must be invoked (from somewhere) whenever
42  * an adapter state changes that is not due to an adapter manager state change.</LI>
43  * </UL>
44  * <P>
45  * Object adapters must also provide mechanisms for:
46  * <UL>
47  * <LI>Managing object reference lifecycle</LI>
48  * <LI>Controlling how servants are associated with object references</LI>
49  * <LI>Manage the state of the adapter, if the adapter desires to implement such mechanisms</LI>
50  * </UL>
51  * Such mechanisms are all object adapter specific, and so we do not attempt to
52  * create general APIs for these functions here.  The object adapter itself
53  * must provide these APIs directly to the user, and they do not affect the rest of the
54  * ORB.  This interface basically makes it possible to plug any object adapter into the
55  * ORB and have the OA work propertly with portable interceptors, and also have requests
56  * dispatched properly to the object adapter.
57  * <P>
58  * The basic function of an ObjectAdapter is to map object IDs to servants and to support
59  * the dispatch operation of the subcontract, which dispatches requests to servants.
60  * This is the purpose of the getInvocationServant method.  In addition, ObjectAdapters must be
61  * able to change state gracefully in the presence of executing methods.  This
62  * requires the use of the enter/exit methods.  Finally, ObjectAdapters often
63  * require access to information about requests.  This is accomodated through the
64  * OAInvocationInfo class and the thread local stack maintained by push/pop/peekInvocationInfo
65  * on the ORB.
66  * <P>
67  * To be useful, this dispatch cycle must be extremely efficient.  There are several
68  * scenarios that matter:
69  * <ol>
70  * <li>A remote invocation, where the dispatch is handled in the server subcontract.</li>
71  * <li>A local invocation, where the dispatch is handled in the client subcontract.</li>
72  * <li>A cached local invocation, where the servant is cached when the IOR is established
73  * for the client subcontract, and the dispatch is handled in the client subcontract
74  * to the cached subcontract.<li>
75  * </ol>
76  * <p>
77  * Each of these 3 cases is handled a bit differently.  On each request, assume as known
78  * ObjectId and ObjectAdapterId, which can be obtained from the object key.  
79  * The ObjectAdaptorFactory is available in the subcontract registry, where it is
80  * registered under the subcontract ID.  The Subcontract ID is also available in the
81  * object key.
82  * <ol>
83  * <li>The remote pattern:
84  *   <ol>
85  *   <li>oa = oaf.find( oaid )</li>
86  *   <li>oa.enter()</li>
87  *   <li>info = oa.makeInvocationInfo( oid )</li> 
88  *   <li>info.setOperation( operation )</li>
89  *   <li>push info</li>
90  *   <li>oa.getInvocationServant( info )</li>
91  *   <li>sreq.setExecuteReturnServantInResponseConstructor( true )</li>
92  *   <li>dispatch to servant</li>
93  *   <li>oa.returnServant()</li>
94  *   <li>oa.exit()</li>
95  *   <li>pop info</li>
96  *   <ol>
97  * </li>
98  * REVISIT: Is this the required order for exit/pop?  Cna they be nested instead?
99  * Note that getInvocationServant and returnServant may throw exceptions.  In such cases,
100 * returnServant, exit, and pop must be called in the correct order.
101 * <li>The local pattern:  
102 *   <ol>
103 *   <li>oa = oaf.find( oaid )</li>
104 *   <li>oa.enter()</li>
105 *   <li>info = oa.makeInvocationInfo( oid )</li> 
106 *   <li>info.setOperation( operation )</li>
107 *   <li>push info</li>
108 *   <li>oa.getInvocationServant( info )</li>
109 *   <li>dispatch to servant</li>
110 *   <li>oa.returnServant()</li>
111 *   <li>oa.exit()</li>
112 *   <li>pop info</li>
113 *   <ol>
114 * </li>
115 * This is the same as the remote case, except that setExecuteReturnServantInResponseConstructor
116 * is not needed (or possible, since there is no server request).
117 * <li>The fast local pattern: When delegate is constructed, 
118 *    first extract ObjectKey from IOR in delegate,
119 *    then get ObjectId, ObjectAdapterId, and ObjectAdapterFactory (oaf). Then:
120 *    <ol>
121 *    <li>oa = oaf.find( oaid )</li>
122 *    <li>info = oa.makeInvocationInfo( oid ) (note: no operation!)</li> 
123 *    <li>push info (needed for the correct functioning of getInvocationServant)</li>
124 *    <li>oa.getInvocationServant( info )</li>
125 *    <li>pop info
126 *    </ol>
127 *    The info instance (which includes the Servant) is cached in the client subcontract.
128 *    <p>Then, on each invocation:</p>
129 *    <ol>
130 *    <li>newinfo = copy of info (clone)</li>
131 *    <li>info.setOperation( operation )</li>
132 *    <li>push newinfo</li>
133 *    <li>oa.enter()</li>
134 *    <li>dispatch to servant</li>
135 *    <li>oa.returnServant()</li>  // XXX This is probably wrong: remove it.
136 *    <li>oa.exit()</li>
137 *    <li>pop info</li>
138 *    </ol>
139 * </li>
140 * </ol>
141 * XXX fast local should not call returnServant: what is correct here?
142 */
143 public interface ObjectAdapter 
144 {
145     ////////////////////////////////////////////////////////////////////////////
146     // Basic methods for supporting interceptors
147     ////////////////////////////////////////////////////////////////////////////
148 
149     /** Returns the ORB associated with this adapter.
150     */
151     ORB getORB() ;
152 
153     Policy   getEffectivePolicy( int type ) ;
154 
155     /** Returns the IOR template of this adapter.  The profiles
156     * in this template may be updated only during the AdapterCreated call.
157     * After that call completes, the IOR template must be made immutable.
158     * Note that the server ID, ORB ID, and adapter name are all available
159     * from the IOR template.
160     */
161     IORTemplate getIORTemplate() ;
162 
163     ////////////////////////////////////////////////////////////////////////////
164     // Methods needed to support ORT.
165     ////////////////////////////////////////////////////////////////////////////
166 
167     /** Return the ID of the AdapterManager for this object adapter.
168     */
169     int getManagerId() ;
170 
171     /** Return the current state of this object adapter (see 
172     * org.omg.PortableInterceptors for states.
173     */
174     short getState() ;
175 
176     ObjectReferenceTemplate   getAdapterTemplate() ;
177 
178     ObjectReferenceFactory   getCurrentFactory() ;
179 
180     /** Change the current factory.  This may only be called during the
181     * AdapterCreated call.
182     */
183     void setCurrentFactory( ObjectReferenceFactory   factory ) ;
184 
185     ////////////////////////////////////////////////////////////////////////////
186     // Methods required for dispatching to servants
187     ////////////////////////////////////////////////////////////////////////////
188 
189     /** Get the servant corresponding to the given objectId, if this is supported.
190      * This method is only used for models where the servant is an ObjectImpl,
191      * which allows the servant to be used directly as the stub.  This allows an object 
192      * reference to be replaced by its servant when it is unmarshalled locally.  
193      * Such objects are not ORB mediated.
194      */
195     org.omg.CORBA.Object   getLocalServant( byte[] objectId ) ;
196 
197     /** Get the servant for the request given by the parameters.
198     * info must contain a valid objectId in this call.
199     * The servant is set in the InvocationInfo argument that is passed into 
200     * this call.  
201     * @param info is the InvocationInfo object for the object reference
202     * @exception ForwardException (a runtime exception) is thrown if the request 
203     * is to be handled by a different object reference.
204     */
205     void getInvocationServant( OAInvocationInfo info ) ;
206 
207     /** enter must be called before each request is invoked on a servant.
208       * @exception OADestroyed is thrown when an OA has been destroyed, which 
209       * requires a retry in the case where an AdapterActivator is present.
210       */
211     void enter( ) throws OADestroyed ;
212 
213     /** exit must be called after each request has been completed.  If enter
214     * is called, there must always be a corresponding exit.
215     */
216     void exit( ) ;
217 
218     /** Must be called every time getInvocationServant is called after
219      * the request has completed.
220      */
221     public void returnServant() ;
222 
223     /** Create an instance of InvocationInfo that is appropriate for this 
224     * Object adapter.
225     */
226     OAInvocationInfo makeInvocationInfo( byte[] objectId ) ;
227 
228     /** Return the most derived interface for the given servant and objectId.
229     */
230     String  [] getInterfaces( Object   servant, byte[] objectId ) ;
231 } 
232
A to Z: JavaDoc & Examples Daily Java News & Articles Open Source Projects Open Source Codes Free Computer Books Remove Frame
Popular Tags