1 /* 2 * Copyright (c) 2002, 2010, 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.protocol; 27 28 import org.omg.PortableInterceptor.ObjectReferenceTemplate ; 29 import org.omg.PortableInterceptor.Interceptor ; 30 import org.omg.PortableInterceptor.Current ; 31 import org.omg.PortableInterceptor.PolicyFactory ; 32 import org.omg.PortableInterceptor.ORBInitInfoPackage.DuplicateName ; 33 34 import org.omg.CORBA.NVList ; 35 import org.omg.CORBA.Any ; 36 import org.omg.CORBA.Policy ; 37 import org.omg.CORBA.PolicyError ; 38 39 import org.omg.CORBA.portable.RemarshalException; 40 41 import com.sun.corba.se.spi.oa.ObjectAdapter ; 42 43 import com.sun.corba.se.spi.protocol.CorbaMessageMediator ; 44 45 import com.sun.corba.se.spi.ior.ObjectKeyTemplate ; 46 47 // XXX These need to go away. 48 import com.sun.corba.se.impl.corba.RequestImpl ; 49 import com.sun.corba.se.impl.protocol.giopmsgheaders.ReplyMessage ; 50 51 /** This interface defines the PI interface that is used to interface the rest of the 52 * ORB to the PI implementation. 53 */ 54 public interface PIHandler { 55 /** Complete the initialization of the PIHandler. This will execute the methods 56 * on the ORBInitializers, if any are defined. This must be done here so that 57 * the ORB can obtain the PIHandler BEFORE the ORBInitializers run, since they 58 * will need access to the PIHandler through the ORB. 59 */ 60 public void initialize() ; 61 62 public void destroyInterceptors() ; 63 64 /* 65 **************************** 66 * IOR interceptor PI hooks 67 ****************************/ 68 69 /** 70 * Called when a new object adapter is created. 71 * 72 * @param oa The adapter associated with the interceptors to be 73 * invoked. 74 */ 75 void objectAdapterCreated( ObjectAdapter oa ) ; 76 77 /** 78 * Called whenever a state change occurs in an adapter manager. 79 * 80 * @param managerId managerId The adapter manager id 81 * @param newState newState The new state of the adapter manager, 82 * and by implication of all object adapters managed by this manager. 83 */ 84 void adapterManagerStateChanged( int managerId, 85 short newState ) ; 86 87 /** Called whenever a state change occurs in an object adapter that 88 * was not caused by an adapter manager state change. 89 * 90 * @param templates The templates that are changing state. 91 * @param newState The new state of the adapters identified by the 92 * templates. 93 */ 94 void adapterStateChanged( ObjectReferenceTemplate[] templates, 95 short newState ) ; 96 97 /* 98 ***************** 99 * Client PI hooks 100 *****************/ 101 102 /** 103 * Called for pseudo-ops to temporarily disable portable interceptor 104 * hooks for calls on this thread. Keeps track of the number of 105 * times this is called and increments the disabledCount. 106 */ 107 void disableInterceptorsThisThread() ; 108 109 /** 110 * Called for pseudo-ops to re-enable portable interceptor 111 * hooks for calls on this thread. Decrements the disabledCount. 112 * If disabledCount is 0, interceptors are re-enabled. 113 */ 114 void enableInterceptorsThisThread() ; 115 116 /** 117 * Called when the send_request or send_poll portable interception point 118 * is to be invoked for all appropriate client-side request interceptors. 119 * 120 * @exception RemarhsalException - Thrown when this request needs to 121 * be retried. 122 */ 123 void invokeClientPIStartingPoint() 124 throws RemarshalException ; 125 126 /** 127 * Called when the appropriate client ending interception point is 128 * to be invoked for all apporpriate client-side request interceptors. 129 * 130 * @param replyStatus One of the constants in iiop.messages.ReplyMessage 131 * indicating which reply status to set. 132 * @param exception The exception before ending interception points have 133 * been invoked, or null if no exception at the moment. 134 * @return The exception to be thrown, after having gone through 135 * all ending points, or null if there is no exception to be 136 * thrown. Note that this exception can be either the same or 137 * different from the exception set using setClientPIException. 138 * There are four possible return types: null (no exception), 139 * SystemException, UserException, or RemarshalException. 140 */ 141 Exception invokeClientPIEndingPoint( 142 int replyStatus, Exception exception ) ; 143 144 /** 145 * Called when a retry is needed after initiateClientPIRequest but 146 * before invokeClientPIRequest. In this case, we need to properly 147 * balance initiateClientPIRequest/cleanupClientPIRequest calls, 148 * but WITHOUT extraneous calls to invokeClientPIEndingPoint 149 * (see bug 6763340). 150 * 151 * @param replyStatus One of the constants in iiop.messages.ReplyMessage 152 * indicating which reply status to set. 153 * @param exception The exception before ending interception points have 154 * been invoked, or null if no exception at the moment. 155 * @return The exception to be thrown, after having gone through 156 * all ending points, or null if there is no exception to be 157 * thrown. Note that this exception can be either the same or 158 * different from the exception set using setClientPIException. 159 * There are four possible return types: null (no exception), 160 * SystemException, UserException, or RemarshalException. 161 */ 162 Exception makeCompletedClientRequest( 163 int replyStatus, Exception exception ) ; 164 165 /** 166 * Invoked when a request is about to be created. Must be called before 167 * any of the setClientPI* methods so that a new info object can be 168 * prepared for information collection. 169 * 170 * @param diiRequest True if this is to be a DII request, or false if it 171 * is a "normal" request. In the DII case, initiateClientPIRequest 172 * is called twice and we need to ignore the second one. 173 */ 174 void initiateClientPIRequest( boolean diiRequest ) ; 175 176 /** 177 * Invoked when a request is about to be cleaned up. Must be called 178 * after ending points are called so that the info object on the stack 179 * can be deinitialized and popped from the stack at the appropriate 180 * time. 181 */ 182 void cleanupClientPIRequest() ; 183 184 /** 185 * Notifies PI of additional information for client-side interceptors. 186 * PI will use this information as a source of information for the 187 * ClientRequestInfo object. 188 */ 189 void setClientPIInfo( RequestImpl requestImpl ) ; 190 191 /** 192 * Notify PI of the MessageMediator for the request. 193 */ 194 void setClientPIInfo(CorbaMessageMediator messageMediator) ; 195 196 /* 197 ***************** 198 * Server PI hooks 199 *****************/ 200 201 /** 202 * Called when the appropriate server starting interception point is 203 * to be invoked for all appropriate server-side request interceptors. 204 * 205 * @throws ForwardException Thrown if an interceptor raises 206 * ForwardRequest. This is an unchecked exception so that we need 207 * not modify the entire execution path to declare throwing 208 * ForwardException. 209 */ 210 void invokeServerPIStartingPoint() ; 211 212 /** 213 * Called when the appropriate server intermediate interception point is 214 * to be invoked for all appropriate server-side request interceptors. 215 * 216 * @throws ForwardException Thrown if an interceptor raises 217 * ForwardRequest. This is an unchecked exception so that we need 218 * not modify the entire execution path to declare throwing 219 * ForwardException. 220 */ 221 void invokeServerPIIntermediatePoint() ; 222 223 /** 224 * Called when the appropriate server ending interception point is 225 * to be invoked for all appropriate server-side request interceptors. 226 * 227 * @param replyMessage The iiop.messages.ReplyMessage containing the 228 * reply status. 229 * @throws ForwardException Thrown if an interceptor raises 230 * ForwardRequest. This is an unchecked exception so that we need 231 * not modify the entire execution path to declare throwing 232 * ForwardException. 233 */ 234 void invokeServerPIEndingPoint( ReplyMessage replyMessage ) ; 235 236 /** 237 * Notifies PI to start a new server request and set initial 238 * information for server-side interceptors. 239 * PI will use this information as a source of information for the 240 * ServerRequestInfo object. poaimpl is declared as an Object so that 241 * we need not introduce a dependency on the POA package. 242 */ 243 void initializeServerPIInfo( CorbaMessageMediator request, 244 ObjectAdapter oa, byte[] objectId, ObjectKeyTemplate oktemp ) ; 245 246 /** 247 * Notifies PI of additional information reqired for ServerRequestInfo. 248 * 249 * @param servant The servant. This is java.lang.Object because in the 250 * POA case, this will be a org.omg.PortableServer.Servant whereas 251 * in the ServerRequestDispatcher case this will be an ObjectImpl. 252 * @param targetMostDerivedInterface. The most derived interface. This 253 * is passed in instead of calculated when needed because it requires 254 * extra information in the POA case that we didn't want to bother 255 * creating extra methods for to pass in. 256 */ 257 void setServerPIInfo( java.lang.Object servant, 258 String targetMostDerivedInterface ) ; 259 260 /** 261 * Notifies PI of additional information required for ServerRequestInfo. 262 */ 263 void setServerPIInfo( Exception exception ) ; 264 265 /** 266 * Notifies PI of additional information for server-side interceptors. 267 * PI will use this information as a source of information for the 268 * ServerRequestInfo object. These are the arguments for a DSI request. 269 */ 270 void setServerPIInfo( NVList arguments ) ; 271 272 /** 273 * Notifies PI of additional information for server-side interceptors. 274 * PI will use this information as a source of information for the 275 * ServerRequestInfo object. This is the exception of a DSI request. 276 */ 277 void setServerPIExceptionInfo( Any exception ) ; 278 279 /** 280 * Notifies PI of additional information for server-side interceptors. 281 * PI will use this information as a source of information for the 282 * ServerRequestInfo object. This is the result of a DSI request. 283 */ 284 void setServerPIInfo( Any result ) ; 285 286 /** 287 * Invoked when a request is about to be cleaned up. Must be called 288 * after ending points are called so that the info object on the stack 289 * can be deinitialized and popped from the stack at the appropriate 290 * time. 291 */ 292 void cleanupServerPIRequest() ; 293 294 Policy create_policy( int type, Any val ) throws PolicyError ; 295 296 void register_interceptor( Interceptor interceptor, int type ) 297 throws DuplicateName ; 298 299 Current getPICurrent() ; 300 301 void registerPolicyFactory( int type, PolicyFactory factory ) ; 302 303 int allocateServerRequestId() ; 304 }