ObjectAdapter.java revision 673:6b017d166ac2
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 26package com.sun.corba.se.spi.oa ; 27 28import org.omg.CORBA.Policy ; 29 30import org.omg.PortableInterceptor.ObjectReferenceTemplate ; 31import org.omg.PortableInterceptor.ObjectReferenceFactory ; 32 33import com.sun.corba.se.spi.orb.ORB ; 34 35import com.sun.corba.se.spi.oa.OADestroyed ; 36 37import 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: 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*/ 161public 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} 250