KickJava   Java API By Example, From Geeks To Geeks.

Java > Open Source Codes > org > omg > PortableInterceptor > ClientRequestInterceptorOperations


1 package org.omg.PortableInterceptor;
2
3
4 /**
5 * org/omg/PortableInterceptor/ClientRequestInterceptorOperations.java .
6 * Generated by the IDL-to-Java compiler (portable), version "3.2"
7 * from ../../../../src/share/classes/org/omg/PortableInterceptor/Interceptors.idl
8 * Saturday, February 9, 2008 9:40:08 AM GMT
9 */

10
11
12 /**
13    * Client-side request interceptor.
14    * <p>
15    * A request Interceptor is designed to intercept the flow of a
16    * request/reply sequence through the ORB at specific points so that
17    * services can query the request information and manipulate the service
18    * contexts which are propagated between clients and servers. The primary
19    * use of request Interceptors is to enable ORB services to transfer
20    * context information between clients and servers. There are two types
21    * of request Interceptors: client-side and server-side.
22    * <p>
23    * To write a client-side Interceptor, implement the
24    * <code>ClientRequestInterceptor</code> interface.
25    *
26    * @see ClientRequestInfo
27    */

28 public interface ClientRequestInterceptorOperations extends org.omg.PortableInterceptor.InterceptorOperations JavaDoc
29 {
30
31   /**
32      * Allows an Interceptor to query request information and modify the
33      * service context before the request is sent to the server.
34      * <p>
35      * This interception point may throw a system exception. If it does,
36      * no other Interceptors' <code>send_request</code> operations are called.
37      * Those Interceptors on the Flow Stack are popped and their
38      * <code>receive_exception</code> interception points are called. This
39      * interception point may also throw a <code>ForwardRequest</code>
40      * exception. If an Interceptor throws this exception, no other
41      * Interceptors' <code>send_request</code> operations are
42      * called. Those Interceptors on the Flow Stack are popped and their
43      * <code>receive_other</code> interception points are called.
44      * <p>
45      * Compliant Interceptors shall properly follow completion_status
46      * semantics if they throw a system exception from this interception
47      * point. The <code>completion_status</code> shall be
48      * <code>COMPLETED_NO</code>.
49      *
50      * @param ri Information about the current request being intercepted.
51      * @exception ForwardRequest If thrown, indicates to the ORB that a
52      * retry of the request should occur with the new object given in
53      * the exception.
54      */

55   void send_request (org.omg.PortableInterceptor.ClientRequestInfo JavaDoc ri) throws org.omg.PortableInterceptor.ForwardRequest JavaDoc;
56
57   /**
58      * Allows an Interceptor to query information during a Time-Independent
59      * Invocation (TII) polling get reply sequence.
60      * <p>
61      * With TII, an application may poll for a response to a request sent
62      * previously by the polling client or some other client. This poll is
63      * reported to Interceptors through the <code>send_poll</code>
64      * interception point and the response is returned through the
65      * <code>receive_reply</code> or <code>receive_exception</code>
66      * interception points. If the response is not available before the
67      * poll time-out expires, the system exception <code>TIMEOUT</code> is
68      * thrown and <code>receive_exception</code> is called with this
69      * exception.
70      * <p>
71      * This interception point may throw a system exception. If it does,
72      * no other Interceptors' <code>send_poll</code> operations are
73      * called. Those Interceptors on the Flow Stack are popped and their
74      * <code>receive_exception</code> interception points are called.
75      * <p>
76      * Compliant Interceptors shall properly follow
77      * <code>completion_status</code> semantics if they throw a system
78      * exception from this interception point. The completion_status shall be
79      * <code>COMPLETED_NO</code>.
80      *
81      * @param ri Information about the current request being intercepted.
82      * @exception TIMEOUT thrown if the response is not available before
83      * the poll time-out expires
84      */

85   void send_poll (org.omg.PortableInterceptor.ClientRequestInfo JavaDoc ri);
86
87   /**
88      * Allows an Interceptor to query the information on a reply after it
89      * is returned from the server and before control is returned to the
90      * client.
91      * <p>
92      * This interception point may throw a system exception. If it does,
93      * no other Interceptors' <code>receive_reply</code> operations are
94      * called. The remaining Interceptors in the Flow Stack shall have
95      * their <code>receive_exception</code> interception point called.
96      * <p>
97      * Compliant Interceptors shall properly follow
98      * <code>completion_status</code> semantics if they throw a system
99      * exception from this interception point. The
100      * <code>completion_status</code> shall be <code>COMPLETED_YES</code>.
101      *
102      * @param ri Information about the current request being intercepted.
103      */

104   void receive_reply (org.omg.PortableInterceptor.ClientRequestInfo JavaDoc ri);
105
106   /**
107      * Indicates to the interceptor that an exception occurred. Allows
108      * an Interceptor to query the exception's information before it is
109      * thrown to the client.
110      * <p>
111      * This interception point may throw a system exception. This has the
112      * effect of changing the exception which successive Interceptors
113      * popped from the Flow Stack receive on their calls to
114      * <code>receive_exception</code>. The exception thrown to the client
115      * will be the last exception thrown by an Interceptor, or the original
116      * exception if no Interceptor changes the exception.
117      * <p>
118      * This interception point may also throw a <code>ForwardRequest</code>
119      * exception. If an Interceptor throws this exception, no other
120      * Interceptors' <code>receive_exception</code> operations are called.
121      * The remaining Interceptors in the Flow Stack are popped and have their
122      * <code>receive_other</code> interception point called.
123      * <p>
124      * If the <code>completion_status</code> of the exception is not
125      * <code>COMPLETED_NO</code>, then it is inappropriate for this
126      * interception point to throw a <code>ForwardRequest</code> exception.
127      * The request s at-most-once semantics would be lost.
128      * <p>
129      * Compliant Interceptors shall properly follow
130      * <code>completion_status</code> semantics if they throw a system
131      * exception from this interception point. If the original exception is
132      * a system exception, the <code>completion_status</code> of the new
133      * exception shall be the same as on the original. If the original
134      * exception is a user exception, then the <code>completion_status</code>
135      * of the new exception shall be <code>COMPLETED_YES</code>.
136      * <p>
137      * Under some conditions, depending on what policies are in effect, an
138      * exception (such as <code>COMM_FAILURE</code>) may result in a retry
139      * of the request. While this retry is a new request with respect to
140      * Interceptors, there is one point of correlation between the original
141      * request and the retry: because control has not returned to the
142      * client, the <code>PortableInterceptor.Current</code> for both the
143      * original request and the retrying request is the same.
144      *
145      * @param ri Information about the current request being intercepted.
146      * @exception ForwardRequest If thrown, indicates to the ORB that a
147      * retry of the request should occur with the new object given in
148      * the exception.
149      */

150   void receive_exception (org.omg.PortableInterceptor.ClientRequestInfo JavaDoc ri) throws org.omg.PortableInterceptor.ForwardRequest JavaDoc;
151
152   /**
153      * Allows an Interceptor to query the information available when a
154      * request results in something other than a normal reply or an
155      * exception. For example, a request could result in a retry
156      * (e.g., a GIOP Reply with a <code>LOCATION_FORWARD</code> status was
157      * received); or on asynchronous calls, the reply does not immediately
158      * follow the request, but control shall return to the client and an
159      * ending interception point shall be called.
160      * <p>
161      * For retries, depending on the policies in effect, a new request may or
162      * may not follow when a retry has been indicated. If a new request does
163      * follow, while this request is a new request, with respect to
164      * Interceptors, there is one point of correlation between the original
165      * request and the retry: because control has not returned to the client,
166      * the request scoped <code>PortableInterceptor.Current</code> for both
167      * the original request and the retrying request is the same.
168      * <p>
169      * This interception point may throw a system exception. If it does, no
170      * other Interceptors' <code>receive_other</code> operations are called.
171      * The remaining Interceptors in the Flow Stack are popped and have
172      * their <code>receive_exception</code> interception point called.
173      * <p>
174      * This interception point may also throw a <code>ForwardRequest</code>
175      * exception. If an Interceptor throws this exception, successive
176      * Interceptors' <code>receive_other</code> operations are called with
177      * the new information provided by the <code>ForwardRequest</code>
178      * exception.
179      * <p>
180      * Compliant Interceptors shall properly follow
181      * <code>completion_status</code> semantics if they throw a system
182      * exception from this interception point. The
183      * <code>completion_status</code> shall be <code>COMPLETED_NO</code>.
184      * If the target invocation had completed, this interception point
185      * would not be called.
186      *
187      * @param ri Information about the current request being intercepted.
188      * @exception ForwardRequest If thrown, indicates to the ORB that a
189      * retry of the request should occur with the new object given in
190      * the exception.
191      */

192   void receive_other (org.omg.PortableInterceptor.ClientRequestInfo JavaDoc ri) throws org.omg.PortableInterceptor.ForwardRequest JavaDoc;
193 } // interface ClientRequestInterceptorOperations
194
Popular Tags