PIHandler.java revision 608:7e06bf1dcb09
1306196Sjkim/* 296593Smarkm * Copyright (c) 2002, 2012, Oracle and/or its affiliates. All rights reserved. 396593Smarkm * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. 4142429Snectar * 596593Smarkm * This code is free software; you can redistribute it and/or modify it 696593Smarkm * under the terms of the GNU General Public License version 2 only, as 796593Smarkm * published by the Free Software Foundation. Oracle designates this 896593Smarkm * particular file as subject to the "Classpath" exception as provided 996593Smarkm * by Oracle in the LICENSE file that accompanied this code. 1096593Smarkm * 1196593Smarkm * This code is distributed in the hope that it will be useful, but WITHOUT 1296593Smarkm * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or 1396593Smarkm * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License 1496593Smarkm * version 2 for more details (a copy is included in the LICENSE file that 1596593Smarkm * accompanied this code). 1696593Smarkm * 1796593Smarkm * You should have received a copy of the GNU General Public License version 1896593Smarkm * 2 along with this work; if not, write to the Free Software Foundation, 1996593Smarkm * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA. 20215698Ssimon * 21215698Ssimon * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA 22215698Ssimon * or visit www.oracle.com if you need additional information or have any 23215698Ssimon * questions. 24215698Ssimon */ 2596593Smarkm 2696593Smarkmpackage com.sun.corba.se.spi.protocol; 2796593Smarkm 2896593Smarkmimport java.io.Closeable; 2996593Smarkm 3096593Smarkmimport org.omg.PortableInterceptor.ObjectReferenceTemplate ; 3196593Smarkmimport org.omg.PortableInterceptor.Interceptor ; 3296593Smarkmimport org.omg.PortableInterceptor.Current ; 3396593Smarkmimport org.omg.PortableInterceptor.PolicyFactory ; 3496593Smarkmimport org.omg.PortableInterceptor.ORBInitInfoPackage.DuplicateName ; 3596593Smarkm 3696593Smarkmimport org.omg.CORBA.NVList ; 3796593Smarkmimport org.omg.CORBA.Any ; 3896593Smarkmimport org.omg.CORBA.Policy ; 3996593Smarkmimport org.omg.CORBA.PolicyError ; 4096593Smarkm 41276864Sjkimimport org.omg.CORBA.portable.RemarshalException; 42276864Sjkim 4396593Smarkmimport com.sun.corba.se.spi.oa.ObjectAdapter ; 4496593Smarkm 45215698Ssimonimport com.sun.corba.se.spi.protocol.CorbaMessageMediator ; 46215698Ssimon 47215698Ssimonimport com.sun.corba.se.spi.ior.ObjectKeyTemplate ; 48215698Ssimon 49142429Snectar// XXX These need to go away. 50215698Ssimonimport com.sun.corba.se.impl.corba.RequestImpl ; 51142429Snectarimport com.sun.corba.se.impl.protocol.giopmsgheaders.ReplyMessage ; 52142429Snectar 53276864Sjkim/** This interface defines the PI interface that is used to interface the rest of the 54276864Sjkim * ORB to the PI implementation. 55276864Sjkim */ 5696593Smarkmpublic interface PIHandler extends Closeable { 57276864Sjkim /** Complete the initialization of the PIHandler. This will execute the methods 58276864Sjkim * on the ORBInitializers, if any are defined. This must be done here so that 59276864Sjkim * the ORB can obtain the PIHandler BEFORE the ORBInitializers run, since they 60276864Sjkim * will need access to the PIHandler through the ORB. 61276864Sjkim */ 62276864Sjkim public void initialize() ; 63215698Ssimon 64276864Sjkim public void destroyInterceptors() ; 65276864Sjkim 66276864Sjkim /* 67276864Sjkim **************************** 68276864Sjkim * IOR interceptor PI hooks 69215698Ssimon ****************************/ 70276864Sjkim 7196593Smarkm /** 7296593Smarkm * Called when a new object adapter is created. 7396593Smarkm * 7496593Smarkm * @param oa The adapter associated with the interceptors to be 7596593Smarkm * invoked. 7696593Smarkm */ 7796593Smarkm void objectAdapterCreated( ObjectAdapter oa ) ; 7896593Smarkm 7996593Smarkm /** 8096593Smarkm * Called whenever a state change occurs in an adapter manager. 8196593Smarkm * 8296593Smarkm * @param managerId managerId The adapter manager id 8396593Smarkm * @param newState newState The new state of the adapter manager, 8496593Smarkm * and by implication of all object adapters managed by this manager. 8596593Smarkm */ 8696593Smarkm void adapterManagerStateChanged( int managerId, 8796593Smarkm short newState ) ; 8896593Smarkm 8996593Smarkm /** Called whenever a state change occurs in an object adapter that 9096593Smarkm * was not caused by an adapter manager state change. 9196593Smarkm * 9296593Smarkm * @param templates The templates that are changing state. 9396593Smarkm * @param newState The new state of the adapters identified by the 9496593Smarkm * templates. 9596593Smarkm */ 9696593Smarkm void adapterStateChanged( ObjectReferenceTemplate[] templates, 9796593Smarkm short newState ) ; 9896593Smarkm 9996593Smarkm /* 10096593Smarkm ***************** 10196593Smarkm * Client PI hooks 10296593Smarkm *****************/ 10396593Smarkm 10496593Smarkm /** 10596593Smarkm * Called for pseudo-ops to temporarily disable portable interceptor 10696593Smarkm * hooks for calls on this thread. Keeps track of the number of 10796593Smarkm * times this is called and increments the disabledCount. 10896593Smarkm */ 10996593Smarkm void disableInterceptorsThisThread() ; 11096593Smarkm 11196593Smarkm /** 11296593Smarkm * Called for pseudo-ops to re-enable portable interceptor 11396593Smarkm * hooks for calls on this thread. Decrements the disabledCount. 11496593Smarkm * If disabledCount is 0, interceptors are re-enabled. 11596593Smarkm */ 11696593Smarkm void enableInterceptorsThisThread() ; 11796593Smarkm 11896593Smarkm /** 11996593Smarkm * Called when the send_request or send_poll portable interception point 12096593Smarkm * is to be invoked for all appropriate client-side request interceptors. 12196593Smarkm * 12296593Smarkm * @exception RemarhsalException - Thrown when this request needs to 12396593Smarkm * be retried. 12496593Smarkm */ 12596593Smarkm void invokeClientPIStartingPoint() 12696593Smarkm throws RemarshalException ; 12796593Smarkm 12896593Smarkm /** 12996593Smarkm * Called when the appropriate client ending interception point is 13096593Smarkm * to be invoked for all apporpriate client-side request interceptors. 13196593Smarkm * 13296593Smarkm * @param replyStatus One of the constants in iiop.messages.ReplyMessage 133142429Snectar * indicating which reply status to set. 13496593Smarkm * @param exception The exception before ending interception points have 135100946Snectar * been invoked, or null if no exception at the moment. 136306196Sjkim * @return The exception to be thrown, after having gone through 137215698Ssimon * all ending points, or null if there is no exception to be 138215698Ssimon * thrown. Note that this exception can be either the same or 139215698Ssimon * different from the exception set using setClientPIException. 140215698Ssimon * There are four possible return types: null (no exception), 14196593Smarkm * SystemException, UserException, or RemarshalException. 142142429Snectar */ 14396593Smarkm Exception invokeClientPIEndingPoint( 14496593Smarkm int replyStatus, Exception exception ) ; 14596593Smarkm 14696593Smarkm /** 147215698Ssimon * Called when a retry is needed after initiateClientPIRequest but 148110010Smarkm * before invokeClientPIRequest. In this case, we need to properly 149215698Ssimon * balance initiateClientPIRequest/cleanupClientPIRequest calls, 150110010Smarkm * but WITHOUT extraneous calls to invokeClientPIEndingPoint 151110010Smarkm * (see bug 6763340). 152215698Ssimon * 15396593Smarkm * @param replyStatus One of the constants in iiop.messages.ReplyMessage 15496593Smarkm * indicating which reply status to set. 15596593Smarkm * @param exception The exception before ending interception points have 15696593Smarkm * been invoked, or null if no exception at the moment. 15796593Smarkm * @return The exception to be thrown, after having gone through 15896593Smarkm * all ending points, or null if there is no exception to be 15996593Smarkm * thrown. Note that this exception can be either the same or 16096593Smarkm * different from the exception set using setClientPIException. 16196593Smarkm * There are four possible return types: null (no exception), 16296593Smarkm * SystemException, UserException, or RemarshalException. 16396593Smarkm */ 16496593Smarkm Exception makeCompletedClientRequest( 16596593Smarkm int replyStatus, Exception exception ) ; 166276864Sjkim 167110010Smarkm /** 16896593Smarkm * Invoked when a request is about to be created. Must be called before 169276864Sjkim * any of the setClientPI* methods so that a new info object can be 170110010Smarkm * prepared for information collection. 17196593Smarkm * 17296593Smarkm * @param diiRequest True if this is to be a DII request, or false if it 17396593Smarkm * is a "normal" request. In the DII case, initiateClientPIRequest 17496593Smarkm * is called twice and we need to ignore the second one. 17596593Smarkm */ 17696593Smarkm void initiateClientPIRequest( boolean diiRequest ) ; 17796593Smarkm 17896593Smarkm /** 17996593Smarkm * Invoked when a request is about to be cleaned up. Must be called 18096593Smarkm * after ending points are called so that the info object on the stack 18196593Smarkm * can be deinitialized and popped from the stack at the appropriate 182110010Smarkm * time. 183110010Smarkm */ 18496593Smarkm void cleanupClientPIRequest() ; 18596593Smarkm 18696593Smarkm /** 18796593Smarkm * Notifies PI of additional information for client-side interceptors. 18896593Smarkm * PI will use this information as a source of information for the 18996593Smarkm * ClientRequestInfo object. 19096593Smarkm */ 19196593Smarkm void setClientPIInfo( RequestImpl requestImpl ) ; 19296593Smarkm 19396593Smarkm /** 19496593Smarkm * Notify PI of the MessageMediator for the request. 19596593Smarkm */ 19696593Smarkm void setClientPIInfo(CorbaMessageMediator messageMediator) ; 19796593Smarkm 198 /* 199 ***************** 200 * Server PI hooks 201 *****************/ 202 203 /** 204 * Called when the appropriate server starting interception point is 205 * to be invoked for all appropriate server-side request interceptors. 206 * 207 * @throws ForwardException Thrown if an interceptor raises 208 * ForwardRequest. This is an unchecked exception so that we need 209 * not modify the entire execution path to declare throwing 210 * ForwardException. 211 */ 212 void invokeServerPIStartingPoint() ; 213 214 /** 215 * Called when the appropriate server intermediate interception point is 216 * to be invoked for all appropriate server-side request interceptors. 217 * 218 * @throws ForwardException Thrown if an interceptor raises 219 * ForwardRequest. This is an unchecked exception so that we need 220 * not modify the entire execution path to declare throwing 221 * ForwardException. 222 */ 223 void invokeServerPIIntermediatePoint() ; 224 225 /** 226 * Called when the appropriate server ending interception point is 227 * to be invoked for all appropriate server-side request interceptors. 228 * 229 * @param replyMessage The iiop.messages.ReplyMessage containing the 230 * reply status. 231 * @throws ForwardException Thrown if an interceptor raises 232 * ForwardRequest. This is an unchecked exception so that we need 233 * not modify the entire execution path to declare throwing 234 * ForwardException. 235 */ 236 void invokeServerPIEndingPoint( ReplyMessage replyMessage ) ; 237 238 /** 239 * Notifies PI to start a new server request and set initial 240 * information for server-side interceptors. 241 * PI will use this information as a source of information for the 242 * ServerRequestInfo object. poaimpl is declared as an Object so that 243 * we need not introduce a dependency on the POA package. 244 */ 245 void initializeServerPIInfo( CorbaMessageMediator request, 246 ObjectAdapter oa, byte[] objectId, ObjectKeyTemplate oktemp ) ; 247 248 /** 249 * Notifies PI of additional information reqired for ServerRequestInfo. 250 * 251 * @param servant The servant. This is java.lang.Object because in the 252 * POA case, this will be a org.omg.PortableServer.Servant whereas 253 * in the ServerRequestDispatcher case this will be an ObjectImpl. 254 * @param targetMostDerivedInterface. The most derived interface. This 255 * is passed in instead of calculated when needed because it requires 256 * extra information in the POA case that we didn't want to bother 257 * creating extra methods for to pass in. 258 */ 259 void setServerPIInfo( java.lang.Object servant, 260 String targetMostDerivedInterface ) ; 261 262 /** 263 * Notifies PI of additional information required for ServerRequestInfo. 264 */ 265 void setServerPIInfo( Exception exception ) ; 266 267 /** 268 * Notifies PI of additional information for server-side interceptors. 269 * PI will use this information as a source of information for the 270 * ServerRequestInfo object. These are the arguments for a DSI request. 271 */ 272 void setServerPIInfo( NVList arguments ) ; 273 274 /** 275 * Notifies PI of additional information for server-side interceptors. 276 * PI will use this information as a source of information for the 277 * ServerRequestInfo object. This is the exception of a DSI request. 278 */ 279 void setServerPIExceptionInfo( Any exception ) ; 280 281 /** 282 * Notifies PI of additional information for server-side interceptors. 283 * PI will use this information as a source of information for the 284 * ServerRequestInfo object. This is the result of a DSI request. 285 */ 286 void setServerPIInfo( Any result ) ; 287 288 /** 289 * Invoked when a request is about to be cleaned up. Must be called 290 * after ending points are called so that the info object on the stack 291 * can be deinitialized and popped from the stack at the appropriate 292 * time. 293 */ 294 void cleanupServerPIRequest() ; 295 296 Policy create_policy( int type, Any val ) throws PolicyError ; 297 298 void register_interceptor( Interceptor interceptor, int type ) 299 throws DuplicateName ; 300 301 Current getPICurrent() ; 302 303 void registerPolicyFactory( int type, PolicyFactory factory ) ; 304 305 int allocateServerRequestId() ; 306} 307