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