1 /*
2 * Copyright (c) 2002, 2003, 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 }