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 |