PIHandler


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