1. package org.omg.PortableInterceptor;
  2. /**
  3. * org/omg/PortableInterceptor/ClientRequestInterceptorOperations.java .
  4. * Generated by the IDL-to-Java compiler (portable), version "3.2"
  5. * from ../../../../src/share/classes/org/omg/PortableInterceptor/Interceptors.idl
  6. * Wednesday, September 15, 2004 10:28:46 AM GMT
  7. */
  8. /**
  9. * Client-side request interceptor.
  10. * <p>
  11. * A request Interceptor is designed to intercept the flow of a
  12. * request/reply sequence through the ORB at specific points so that
  13. * services can query the request information and manipulate the service
  14. * contexts which are propagated between clients and servers. The primary
  15. * use of request Interceptors is to enable ORB services to transfer
  16. * context information between clients and servers. There are two types
  17. * of request Interceptors: client-side and server-side.
  18. * <p>
  19. * To write a client-side Interceptor, implement the
  20. * <code>ClientRequestInterceptor</code> interface.
  21. *
  22. * @see ClientRequestInfo
  23. */
  24. public interface ClientRequestInterceptorOperations extends org.omg.PortableInterceptor.InterceptorOperations
  25. {
  26. /**
  27. * Allows an Interceptor to query request information and modify the
  28. * service context before the request is sent to the server.
  29. * <p>
  30. * This interception point may throw a system exception. If it does,
  31. * no other Interceptors' <code>send_request</code> operations are called.
  32. * Those Interceptors on the Flow Stack are popped and their
  33. * <code>receive_exception</code> interception points are called. This
  34. * interception point may also throw a <code>ForwardRequest</code>
  35. * exception. If an Interceptor throws this exception, no other
  36. * Interceptors' <code>send_request</code> operations are
  37. * called. Those Interceptors on the Flow Stack are popped and their
  38. * <code>receive_other</code> interception points are called.
  39. * <p>
  40. * Compliant Interceptors shall properly follow completion_status
  41. * semantics if they throw a system exception from this interception
  42. * point. The <code>completion_status</code> shall be
  43. * <code>COMPLETED_NO</code>.
  44. *
  45. * @param ri Information about the current request being intercepted.
  46. * @exception ForwardRequest If thrown, indicates to the ORB that a
  47. * retry of the request should occur with the new object given in
  48. * the exception.
  49. */
  50. void send_request (org.omg.PortableInterceptor.ClientRequestInfo ri) throws org.omg.PortableInterceptor.ForwardRequest;
  51. /**
  52. * Allows an Interceptor to query information during a Time-Independent
  53. * Invocation (TII) polling get reply sequence.
  54. * <p>
  55. * With TII, an application may poll for a response to a request sent
  56. * previously by the polling client or some other client. This poll is
  57. * reported to Interceptors through the <code>send_poll</code>
  58. * interception point and the response is returned through the
  59. * <code>receive_reply</code> or <code>receive_exception</code>
  60. * interception points. If the response is not available before the
  61. * poll time-out expires, the system exception <code>TIMEOUT</code> is
  62. * thrown and <code>receive_exception</code> is called with this
  63. * exception.
  64. * <p>
  65. * This interception point may throw a system exception. If it does,
  66. * no other Interceptors' <code>send_poll</code> operations are
  67. * called. Those Interceptors on the Flow Stack are popped and their
  68. * <code>receive_exception</code> interception points are called.
  69. * <p>
  70. * Compliant Interceptors shall properly follow
  71. * <code>completion_status</code> semantics if they throw a system
  72. * exception from this interception point. The completion_status shall be
  73. * <code>COMPLETED_NO</code>.
  74. *
  75. * @param ri Information about the current request being intercepted.
  76. * @exception TIMEOUT thrown if the response is not available before
  77. * the poll time-out expires
  78. */
  79. void send_poll (org.omg.PortableInterceptor.ClientRequestInfo ri);
  80. /**
  81. * Allows an Interceptor to query the information on a reply after it
  82. * is returned from the server and before control is returned to the
  83. * client.
  84. * <p>
  85. * This interception point may throw a system exception. If it does,
  86. * no other Interceptors' <code>receive_reply</code> operations are
  87. * called. The remaining Interceptors in the Flow Stack shall have
  88. * their <code>receive_exception</code> interception point called.
  89. * <p>
  90. * Compliant Interceptors shall properly follow
  91. * <code>completion_status</code> semantics if they throw a system
  92. * exception from this interception point. The
  93. * <code>completion_status</code> shall be <code>COMPLETED_YES</code>.
  94. *
  95. * @param ri Information about the current request being intercepted.
  96. */
  97. void receive_reply (org.omg.PortableInterceptor.ClientRequestInfo ri);
  98. /**
  99. * Indicates to the interceptor that an exception occurred. Allows
  100. * an Interceptor to query the exception's information before it is
  101. * thrown to the client.
  102. * <p>
  103. * This interception point may throw a system exception. This has the
  104. * effect of changing the exception which successive Interceptors
  105. * popped from the Flow Stack receive on their calls to
  106. * <code>receive_exception</code>. The exception thrown to the client
  107. * will be the last exception thrown by an Interceptor, or the original
  108. * exception if no Interceptor changes the exception.
  109. * <p>
  110. * This interception point may also throw a <code>ForwardRequest</code>
  111. * exception. If an Interceptor throws this exception, no other
  112. * Interceptors' <code>receive_exception</code> operations are called.
  113. * The remaining Interceptors in the Flow Stack are popped and have their
  114. * <code>receive_other</code> interception point called.
  115. * <p>
  116. * If the <code>completion_status</code> of the exception is not
  117. * <code>COMPLETED_NO</code>, then it is inappropriate for this
  118. * interception point to throw a <code>ForwardRequest</code> exception.
  119. * The request s at-most-once semantics would be lost.
  120. * <p>
  121. * Compliant Interceptors shall properly follow
  122. * <code>completion_status</code> semantics if they throw a system
  123. * exception from this interception point. If the original exception is
  124. * a system exception, the <code>completion_status</code> of the new
  125. * exception shall be the same as on the original. If the original
  126. * exception is a user exception, then the <code>completion_status</code>
  127. * of the new exception shall be <code>COMPLETED_YES</code>.
  128. * <p>
  129. * Under some conditions, depending on what policies are in effect, an
  130. * exception (such as <code>COMM_FAILURE</code>) may result in a retry
  131. * of the request. While this retry is a new request with respect to
  132. * Interceptors, there is one point of correlation between the original
  133. * request and the retry: because control has not returned to the
  134. * client, the <code>PortableInterceptor.Current</code> for both the
  135. * original request and the retrying request is the same.
  136. *
  137. * @param ri Information about the current request being intercepted.
  138. * @exception ForwardRequest If thrown, indicates to the ORB that a
  139. * retry of the request should occur with the new object given in
  140. * the exception.
  141. */
  142. void receive_exception (org.omg.PortableInterceptor.ClientRequestInfo ri) throws org.omg.PortableInterceptor.ForwardRequest;
  143. /**
  144. * Allows an Interceptor to query the information available when a
  145. * request results in something other than a normal reply or an
  146. * exception. For example, a request could result in a retry
  147. * (e.g., a GIOP Reply with a <code>LOCATION_FORWARD</code> status was
  148. * received); or on asynchronous calls, the reply does not immediately
  149. * follow the request, but control shall return to the client and an
  150. * ending interception point shall be called.
  151. * <p>
  152. * For retries, depending on the policies in effect, a new request may or
  153. * may not follow when a retry has been indicated. If a new request does
  154. * follow, while this request is a new request, with respect to
  155. * Interceptors, there is one point of correlation between the original
  156. * request and the retry: because control has not returned to the client,
  157. * the request scoped <code>PortableInterceptor.Current</code> for both
  158. * the original request and the retrying request is the same.
  159. * <p>
  160. * This interception point may throw a system exception. If it does, no
  161. * other Interceptors' <code>receive_other</code> operations are called.
  162. * The remaining Interceptors in the Flow Stack are popped and have
  163. * their <code>receive_exception</code> interception point called.
  164. * <p>
  165. * This interception point may also throw a <code>ForwardRequest</code>
  166. * exception. If an Interceptor throws this exception, successive
  167. * Interceptors' <code>receive_other</code> operations are called with
  168. * the new information provided by the <code>ForwardRequest</code>
  169. * exception.
  170. * <p>
  171. * Compliant Interceptors shall properly follow
  172. * <code>completion_status</code> semantics if they throw a system
  173. * exception from this interception point. The
  174. * <code>completion_status</code> shall be <code>COMPLETED_NO</code>.
  175. * If the target invocation had completed, this interception point
  176. * would not be called.
  177. *
  178. * @param ri Information about the current request being intercepted.
  179. * @exception ForwardRequest If thrown, indicates to the ORB that a
  180. * retry of the request should occur with the new object given in
  181. * the exception.
  182. */
  183. void receive_other (org.omg.PortableInterceptor.ClientRequestInfo ri) throws org.omg.PortableInterceptor.ForwardRequest;
  184. } // interface ClientRequestInterceptorOperations