PIHandler.java revision 608:7e06bf1dcb09
1/* 2 * Copyright (c) 2002, 2012, 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 26package com.sun.corba.se.spi.protocol; 27 28import java.io.Closeable; 29 30import org.omg.PortableInterceptor.ObjectReferenceTemplate ; 31import org.omg.PortableInterceptor.Interceptor ; 32import org.omg.PortableInterceptor.Current ; 33import org.omg.PortableInterceptor.PolicyFactory ; 34import org.omg.PortableInterceptor.ORBInitInfoPackage.DuplicateName ; 35 36import org.omg.CORBA.NVList ; 37import org.omg.CORBA.Any ; 38import org.omg.CORBA.Policy ; 39import org.omg.CORBA.PolicyError ; 40 41import org.omg.CORBA.portable.RemarshalException; 42 43import com.sun.corba.se.spi.oa.ObjectAdapter ; 44 45import com.sun.corba.se.spi.protocol.CorbaMessageMediator ; 46 47import com.sun.corba.se.spi.ior.ObjectKeyTemplate ; 48 49// XXX These need to go away. 50import com.sun.corba.se.impl.corba.RequestImpl ; 51import com.sun.corba.se.impl.protocol.giopmsgheaders.ReplyMessage ; 52 53/** This interface defines the PI interface that is used to interface the rest of the 54 * ORB to the PI implementation. 55 */ 56public interface PIHandler extends Closeable { 57 /** Complete the initialization of the PIHandler. This will execute the methods 58 * on the ORBInitializers, if any are defined. This must be done here so that 59 * the ORB can obtain the PIHandler BEFORE the ORBInitializers run, since they 60 * will need access to the PIHandler through the ORB. 61 */ 62 public void initialize() ; 63 64 public void destroyInterceptors() ; 65 66 /* 67 **************************** 68 * IOR interceptor PI hooks 69 ****************************/ 70 71 /** 72 * Called when a new object adapter is created. 73 * 74 * @param oa The adapter associated with the interceptors to be 75 * invoked. 76 */ 77 void objectAdapterCreated( ObjectAdapter oa ) ; 78 79 /** 80 * Called whenever a state change occurs in an adapter manager. 81 * 82 * @param managerId managerId The adapter manager id 83 * @param newState newState The new state of the adapter manager, 84 * and by implication of all object adapters managed by this manager. 85 */ 86 void adapterManagerStateChanged( int managerId, 87 short newState ) ; 88 89 /** Called whenever a state change occurs in an object adapter that 90 * was not caused by an adapter manager state change. 91 * 92 * @param templates The templates that are changing state. 93 * @param newState The new state of the adapters identified by the 94 * templates. 95 */ 96 void adapterStateChanged( ObjectReferenceTemplate[] templates, 97 short newState ) ; 98 99 /* 100 ***************** 101 * Client PI hooks 102 *****************/ 103 104 /** 105 * Called for pseudo-ops to temporarily disable portable interceptor 106 * hooks for calls on this thread. Keeps track of the number of 107 * times this is called and increments the disabledCount. 108 */ 109 void disableInterceptorsThisThread() ; 110 111 /** 112 * Called for pseudo-ops to re-enable portable interceptor 113 * hooks for calls on this thread. Decrements the disabledCount. 114 * If disabledCount is 0, interceptors are re-enabled. 115 */ 116 void enableInterceptorsThisThread() ; 117 118 /** 119 * Called when the send_request or send_poll portable interception point 120 * is to be invoked for all appropriate client-side request interceptors. 121 * 122 * @exception RemarhsalException - Thrown when this request needs to 123 * be retried. 124 */ 125 void invokeClientPIStartingPoint() 126 throws RemarshalException ; 127 128 /** 129 * Called when the appropriate client ending interception point is 130 * to be invoked for all apporpriate client-side request interceptors. 131 * 132 * @param replyStatus One of the constants in iiop.messages.ReplyMessage 133 * indicating which reply status to set. 134 * @param exception The exception before ending interception points have 135 * been invoked, or null if no exception at the moment. 136 * @return The exception to be thrown, after having gone through 137 * all ending points, or null if there is no exception to be 138 * thrown. Note that this exception can be either the same or 139 * different from the exception set using setClientPIException. 140 * There are four possible return types: null (no exception), 141 * SystemException, UserException, or RemarshalException. 142 */ 143 Exception invokeClientPIEndingPoint( 144 int replyStatus, Exception exception ) ; 145 146 /** 147 * Called when a retry is needed after initiateClientPIRequest but 148 * before invokeClientPIRequest. In this case, we need to properly 149 * balance initiateClientPIRequest/cleanupClientPIRequest calls, 150 * but WITHOUT extraneous calls to invokeClientPIEndingPoint 151 * (see bug 6763340). 152 * 153 * @param replyStatus One of the constants in iiop.messages.ReplyMessage 154 * indicating which reply status to set. 155 * @param exception The exception before ending interception points have 156 * been invoked, or null if no exception at the moment. 157 * @return The exception to be thrown, after having gone through 158 * all ending points, or null if there is no exception to be 159 * thrown. Note that this exception can be either the same or 160 * different from the exception set using setClientPIException. 161 * There are four possible return types: null (no exception), 162 * SystemException, UserException, or RemarshalException. 163 */ 164 Exception makeCompletedClientRequest( 165 int replyStatus, Exception exception ) ; 166 167 /** 168 * Invoked when a request is about to be created. Must be called before 169 * any of the setClientPI* methods so that a new info object can be 170 * prepared for information collection. 171 * 172 * @param diiRequest True if this is to be a DII request, or false if it 173 * is a "normal" request. In the DII case, initiateClientPIRequest 174 * is called twice and we need to ignore the second one. 175 */ 176 void initiateClientPIRequest( boolean diiRequest ) ; 177 178 /** 179 * Invoked when a request is about to be cleaned up. Must be called 180 * after ending points are called so that the info object on the stack 181 * can be deinitialized and popped from the stack at the appropriate 182 * time. 183 */ 184 void cleanupClientPIRequest() ; 185 186 /** 187 * Notifies PI of additional information for client-side interceptors. 188 * PI will use this information as a source of information for the 189 * ClientRequestInfo object. 190 */ 191 void setClientPIInfo( RequestImpl requestImpl ) ; 192 193 /** 194 * Notify PI of the MessageMediator for the request. 195 */ 196 void setClientPIInfo(CorbaMessageMediator messageMediator) ; 197 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