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 }