< prev index next >

src/java.corba/share/classes/com/sun/corba/se/spi/oa/ObjectAdapter.java

Print this page




  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




  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 */
 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


< prev index next >