ChangeLogTag:Thu Nov 18 20:51:06 1999 Nanbor Wang <nanbor@cs.wustl.edu>

1 files changed, 117 insertions, 40 deletions

diff --git a/TAO/docs/interceptors.html b/TAO/docs/interceptors.html
index 7a4b80ba706..129c6a95db6 100644
--- a/TAO/docs/interceptors.html
+++ b/TAO/docs/interceptors.html
@@ -8,13 +8,22 @@ link="#000fff"
 vlink="#ff0f0f"
 bgcolor="#ffffff">
 
+<p>We are in the process of revising TAO's Portable Interceptor
+implementation according to the latest <a
+href="ftp://ftp.omg.org/pub/docs/orbos/99-10-01.pdf">working draft</a>
+of the spec to bring it closer to the spec.  The purpose of this
+document is to provide a trasition guide for those who have used our
+old interceptors.  The old interceptors will no longer be supported
+once we have the new mechanism in place.</p>
+
+<p>The revised interceptor implementation will be available shortly.</p>
+
 <h3><a name="toc">Table of Contents</a></h3>
 <ul>
   <li><a href="#context">Context</a>
   <li><a href="#implement">TAO's Implementation</a>
-  <li><a href="#api">APIs</a>
+  <li><a href="#api">Transition</a>
   <li><a href="#status">Current Status</a>
-  <li><a href="#future">Future Works</a>
   <li><a href="#ref">References</a>
 </ul>
 
@@ -22,32 +31,40 @@ bgcolor="#ffffff">
 
 <p>Interceptors allow you to interpose other CORBA services to the ORB
 and extend the ORB's functionalities.  They are most commonly used in,
-but not limited to, Security Service, Transaction Service.</p>
+but not limited to, Security Service, Transaction Service.  They are
+also for doing accounting and debugging distributed application.</p>
 
 <p>Although both CORBA 2.2 and 2.3 define an interceptor interface,
 the definitions are pretty much useless because it does not define how
 the interceptor should interact with an ORB.  Therefore, OMG is
 currently trying to define a "<a
-href="http://www.omg.org/techprocess/meetings/schedule/Portable_Interceptors_RFP.html">Portable
-Interceptor</a>" which will remedy the problems and allow application
-users to use interceptos from different venders with their ORBs.  </p>
+href="http://www.omg.org/techprocess/meetings/schedule/Portable_Interceptors_RFP.html">
+Portable Interceptor</a>" specification which will remedy the problems
+and allow application users to use interceptos from different venders
+with their ORBs. </p>
 
 <h2><a name="implement">TAO's Implementation of "Portable
 Interceptors"</a></h2>
 
-<p>Because the "<a href="#ref">Portable Interceptor Spec</a>" is still
-in the initial submission stage, and there are several proposed
-standards which define very different interfaces and capabilities, our
-goal is to provide an minimum subset of functionalities proposed in
-the initial submissions.  This approach should allow TAO users to
-explore various use cases of interceptors while avoid adding something
-that will eventually be removed from the standard.</p>
+<p>TAO's portable interceptor implementation was developped before
+even a joint submission was available.  There were several proposed
+standards which defined very different interfaces and capabilities.
+The old interceptor implementation provides a minimum subset of
+functionalities proposed in the initial submissions.  This approach
+has allowed TAO users to explore various use cases of interceptors and
+prevented users from adding code that depended on the interceptor
+features which would not be supported when the spec gets
+finalized.</p>
+
+<p>As we are modifying TAO's interceptor interface to conform with the
+proposed spec., this document provide some guidelines on how you can
+revise your portable interceptors to work with the "standard." </p>
 
-<p>As we will eventually modify TAO's interceptor interface in the
-future when it become available, you will have to revise your
-implementation also when that occurs. </p>
+<h2><a name="api">Guide for Transitting from TAO's Old "Portable"
+Interceptor APIs to the Standard Portable Interceptor APIs</a></h2>
 
-<h2><a name="api">Interceptor APIs</a></h2>
+<p>Please refer to the working draft for details on the proposed
+Portable Interceptor interfaces.</p>
 
 <pre>
 // -*- IDL -*- $Id$
@@ -60,9 +77,20 @@ implementation also when that occurs. </p>
 //   is still under discussion in OMG and both the IDL
 //   and the implementation details in TAO will eventually
 //   change to conform with the PI spec in the future.
+//
+//   @@ Now that a working draft of the Portable Interceptors
+//      is available, we will provide a compliant implementation
+//      shortly.
+//
+//      Please see the annotation marked with "@@" in this file
+//      for hints on transitting from the temporary
+//      implementation to new APIs.
+//
+//      See $TAO_ROOT/docs/interceptors.html for more info.
 // **********************************************************
 
 // Author (currently): Nanbor Wang <nanbor@cs.wustl.edu>
+// @@ I will no longer be the author of this IDL file. ;-)
 
 #include <corba.pidl>
 #include <IOP.pidl>
@@ -70,6 +98,7 @@ implementation also when that occurs. </p>
 #pragma prefix "TAO"
 // The prefix should be changed to "omg.org" once the spec. gets
 // finallized.
+// @@ The prefix will be changed to "omg.org".
 
 module PortableInterceptor
 {
@@ -77,21 +106,29 @@ module PortableInterceptor
     {
       // Cookie's are used to pass information among interceptors
       // within a invocation or an upcall.
+      //
+      // @@ Cookie will no longer be available.
       string myname ();
     };
 
   typedef sequence<Cookie>  Cookies;
   // Collections of Cookie's become Cookies'es.
+  //
+  // @@ Cookies will no longer be available.
 
   interface Interceptor
     {
       // Base interface for Interceptors.
+      //
+      // @@ This interface will not change.
       readonly attribute string name;
     };
 
   interface ServerRequestInterceptor : Interceptor
     {
       // Server side request interceptor definition.
+      //
+      // @@ The name of the interface will not change.
 
       void preinvoke (in unsigned long request_id,
                       in boolean response_expected,
@@ -105,6 +142,17 @@ module PortableInterceptor
       // I haven't figured out how to best optimize this stuff.
       // In the future, NVList will contain all in and inout arguments
       // of the operation.
+      //
+      // @@ This operation will map to either
+      // <receive_request_service_contexts> or <receive_request> of
+      // the standard APIs.  If you are not sure, use
+      // <receive_request>.
+      //
+      // void receive_request_service_contexts (in ServerRequestInfo ri) raises (ForwardRequest);
+      // void receive_request (in ServerRequestInfo ri) raises (ForwardRequest);
+      //
+      // @@ Note that all arguments will be accessed thru
+      // <PortableInterceptor::ServerRequestInfo> interface.
 
       void postinvoke (in unsigned long request_id,
                        in boolean response_expected,
@@ -118,6 +166,16 @@ module PortableInterceptor
       // I haven't figured out how to best optimize this stuff.
       // In the future, NVList will contain all out, inout arguments
       // and the return value of the operation.
+      //
+      // @@ This operation will map to <send_reply>.
+      // It is not clear whether oneway call will invoke <send_other>
+      // operation or not.
+      //
+      // void send_reply (in ServerRequestInfo ri);
+      // void send_other (in ServerRequestInfo ri) raises (ForwardRequest);
+      //
+      // @@ Note that all arguments will be accessed thru
+      // <PortableInterceptor::ServerRequestInfo> interface.
 
       void exception_occurred (in unsigned long request_id,
                                in boolean response_expected,
@@ -125,11 +183,20 @@ module PortableInterceptor
                                in string operation_name,
                                inout Cookies ck);
       // Exception interception point.
+      //
+      // @@ This method will map to <send_exception> method.
+      //
+      // void send_exception (in ServerRequestInfo ri) raises (ForwardRequest);
+      //
+      // @@ Note that all arguments will be accessed thru
+      // <PortableInterceptor::ServerRequestInfo> interface.
     };
 
   interface ClientRequestInterceptor : Interceptor
     {
       // Client side interceptor.
+      //
+      // @@ The name of the interface will not change.
 
       void preinvoke (in unsigned long request_id,
                       in boolean response_expected,
@@ -143,6 +210,14 @@ module PortableInterceptor
       // I haven't figured out how to best optimize this stuff.
       // In the future, NVList will contain all in and inout arguments
       // of the operation.
+      //
+      // @@ This operation will map to <send_request> of the standard
+      // APIs.
+      //
+      // void send_request (in ClientRequestInfo) raises (ForwardRequest);
+      //
+      // @@ Note that all arguments will be accessed thru
+      // <PortableInterceptor::ClientRequestInfo> interface.
 
       void postinvoke (in unsigned long request_id,
                        in boolean response_expected,
@@ -156,6 +231,16 @@ module PortableInterceptor
       // I haven't figured out how to best optimize this stuff.
       // In the future, NVList will contain all out, inout arguments
       // and the return value of the operation.
+      //
+      // @@ This operation will map to either <receive_reply> or
+      // <receive_other> in the standard APIs depending on whether the
+      // operation is oneway or not.
+      //
+      // void receive_reply (in ClientRequestInfo ri);
+      // void receive_other (in ClientRequestInfo ri);
+      //
+      // @@ Note that all arguments will be accessed thru
+      // <PortableInterceptor::ClientRequestInfo> interface.
 
       void exception_occurred (in unsigned long request_id,
                                in boolean response_expected,
@@ -163,6 +248,13 @@ module PortableInterceptor
                                in string operation_name,
                                inout Cookies ck);
       // Exception occurred.
+      //
+      // @@ This method will map to <receive_exception> method as:
+      //
+      //    void receive_exception (in ClientRequestInfo ri) raises (ForwardRequest);
+      //
+      // @@ Note that all arguments will be accessed thru
+      // <PortableInterceptor::ClientRequestInfo> interface.
     };
 };
 
@@ -171,41 +263,26 @@ module PortableInterceptor
 
 <h2><a name="status">Current Status</a></h2>
 <ul>
-  <li><p>Currently, TAO only support request-level
-      interceptor. </p></li>
   <li>Users are allowed to register one interceptor with ORB Core thru
       <tt>CORBA::ORB::_register_server_interceptor</tt> and
       <tt>CORBA::ORB::_register_client_interceptor</tt>.  Both methods
       returns the previous registered interceptor if one
       exist. </p></li>
-  <li><p>The NVList argument that passes the argument list of
-      the operation is current empty, i.e., currently, you can not
-      access/modify the arguments of a method invocation.</p></li>
 </ul>
 
 <h2><a name="future">Future Works</a></h2>
 <ol>
-  <li><p>Obviously, added support for accessing the invocation
-      arguments.</p></li>
-  <li><p>Implement a better interceptor management interface in
-      ORB. </p></li>
-  <li><p>Review ways to support interceptors with <a
-      href="releasenotes/index.html#ami">AMI</a>.</p></li>
+  <li><p>There will only be request-level interceptors.</p></li>
+
+  <li><p>Add support for <em>local</em> keyword.</p></li>
+
+  <li><p>Add support for "standard" portable interceptors.</p></li>
 </ol>
 
 <H3><a name="ref">References:</a></H3>
 <UL>
-  <LI><a href="ftp://ftp.omg.org/pub/docs/orbos/99-04-10.pdf">
-      <CODE>[EXP]</CODE> 99-04-10</a> by Expersoft Corp., GMD Fokus,
-      OIS, OOC (ORBacus)
-  <LI><a href="ftp://ftp.omg.org/pub/docs/orbos/99-04-04.pdf">
-      <CODE>[IBM]</CODE> 99-04-04</a> by IBM
-  <LI><a href="ftp://ftp.omg.org/pub/docs/orbos/99-04-05.pdf">
-      <CODE>[INP]</CODE> 99-04-05</a> by Inprise (Visibroker) and BEA
-  <LI><a href="ftp://ftp.omg.org/pub/docs/orbos/99-04-08.pdf">
-      <CODE>[HPI]</CODE> 99-04-08</a> by HP and IONA (Orbix)
-  <LI><a href="ftp://ftp.omg.org/pub/docs/orbos/99-04-07.pdf">
-      <CODE>[SUN]</CODE> 99-04-07</a> by Eternal System, Expersoft and
-      Sun
+  <LI><a href="ftp://ftp.omg.org/pub/docs/orbos/99-10-01.pdf">
+      99-10-01</a> Portable Interceptors Working Draft - Joint Revised
+      Submission.
 </UL>
 </BODY>