TAO/docs/poa_migration.html

   1 <HTML>
   2 <HEAD>
   3   <META NAME="GENERATOR" CONTENT="Adobe PageMill 2.0 Mac">
   4   <TITLE>Migrating from the BOA to the POA</TITLE>
   5   <!--  -->
   6 </HEAD>
   7
   8 <BODY text = "#000000"
   9 link="#0000ff"
  10 vlink="#cc0000"
  11 bgcolor="#ffffff">
  12
  13 <HR><P>
  14 <H3>Migrating CORBA Applications from BOA to POA</H3>
  15
  16 Starting with the CORBA 2.2, the Basic Object Adapter (BOA) has been
  17 deprecated in favor of the <A
  18 HREF="http://www.cs.wustl.edu/~schmidt/POA.ps.gz">Portable Object
  19 Adapter</A> (POA).  This document explains the changes required to
  20 migrate CORBA applications based on the BOA to use TAO's POA
  21 implementation, which is the only Object Adapter supported by TAO.
  22 For more information on the benefits of the POA please see the <A
  23 HREF="http://www.cs.wustl.edu/~schmidt/report-doc.html">Object
  24 Interconnection</A> columns written by <A
  25 HREF="http://www.dre.vanderbilt.edu/~schmidt/">Doug Schmidt</A> and <A
  26 HREF="http://www.iona.com/hyplan/vinoski/">Steve Vinoski</a>.
  27
  28 <h3>Contents</h3>
  29 <ul>
  30   <li><a href="#Client-side Changes">Client-side Changes</a>
  31   <li><a href="#Server-side Changes">Server-side Changes</a>
  32   <li><a href="#Reference counting Servants">Reference counting Servants</a>
  33 </ul>
  34
  35 <H4><a name="Client-side Changes">Client-side Changes</a></h4>
  36
  37 <ul>
  38 <li>Very little has changed.  Thus, many applications require no changes.</li><P>
  39 </ul>
  40
  41 <h4><a name="Server-side Changes">Server-side Changes</a></h4>
  42
  43 <UL>
  44 <li><CODE>POA_init</CODE> is replaced with <CODE>resolve_initial_references("RootPOA")</CODE> followed
  45 by a <CODE>_narrow</CODE> operation.</li><P>
  46
  47 <li>The implementation no longer inherits from the client-side stub.
  48 Instead, they inherit from <CODE>PortableServer::ServantBase</CODE>.
  49 The implications of this are (a) if you want a object reference for
  50 that, you must use the <CODE>_this</CODE> method.</li><P>
  51
  52 <li>Object ID's are assigned by the POA unless you activate the
  53 servant with a specific ID.  <A
  54 HREF="../performance-tests/Cubit/TAO/IDL_Cubit">IDL_Cubit</A>
  55 has examples on how to do this.</li><P>
  56
  57 <li>Unlike the BOA, the POA explicitly addresses the temporal nature
  58 of servants and declares that a POA can service either transient or
  59 persistent servants (not both).  The root POA's (mandated,
  60 unchangeable) policy is "transient".  The implications of this are
  61 that in order for a client to be able to manufacture an object
  62 reference on its own and use that to access an object, the servant for
  63 that object must be registered with a POA whose policy is
  64 "persistent".  Thus, you must create a child POA with that policy and
  65 register the servant with that POA.  NOTE: when the POA declares
  66 something as "persistent", it is only stating that the key is valid
  67 between different runs of the server; it makes no claims that state or
  68 anything else is persistent.</li><P>
  69
  70 <ul>
  71         <li> Servants are not automatically activated, hence you must register
  72         them by calling some of the <CODE>activate_object*</CODE> methods on a POA or
  73         calling <CODE>_this</CODE> on the servant; with the latest you have no control on
  74         the ObjectId (which sometimes is good), and the POA must support the
  75         right policies (the RootPOA does).</li><P>
  76
  77         <li>Servant constructors use to take a <CODE>const
  78 char*</CODE> parameter to set
  79         they object id, this is not needed now, in fact in many cases they use
  80         to pass this argument to the skeleton class: this will fail
  81 now.</li><P> </ul> This list is not intended to be exhaustive, but
  82 should give you a good starting point.  If you find things along the
  83 way that change your applications and I didn't note them, please send
  84 them to me.  Perhaps we can work together on the ultimate migration
  85 document. <P> </UL>
  86
  87 <h4><a name="Reference counting Servants">Reference counting Servants</h4>
  88
  89 The new POA/servant <a
  90 href="ftp://ftp.omg.org/pub/docs/orbos/98-07-12.pdf">reference
  91 counting rules</a> of the CORBA 2.3 spec are somewhat tricky. Here are
  92 two main reasons why: <p>
  93
  94 <ul>
  95
  96 <li> If a servant is deleted without deactivating from the POA, the
  97 application will crash because the POA will try to access the still
  98 registered (but now non-existent) servant when the POA is destroyed. <p>
  99
 100 The solution to this is to make sure that the servant is deleted after
 101 the POA is deleted or make sure that the servant is deactivated from
 102 the POA before the servant is deleted. </li> <p>
 103
 104 <li> You cannot delete a servant which is the target of the current
 105 upcall/request.  A good example of this is the typical destroy()
 106 method, usually written like this:
 107
 108 <PRE>
 109
 110 class TAO_Export TAO_Thread_Policy : public POA_PortableServer::ThreadPolicy
 111 {
 112   void destroy ();
 113 };
 114
 115 void
 116 TAO_Thread_Policy::destroy ()
 117 {
 118   PortableServer::POA_var poa = this->_default_POA ();
 119
 120   PortableServer::ObjectId_var id = poa->servant_to_id (this);
 121
 122   poa->deactivate_object (id.in ());
 123
 124   // Commit suicide: must have been dynamically allocated.
 125   delete this;
 126 }
 127
 128 </PRE>
 129
 130 The correct implementation is:
 131
 132 <PRE>
 133
 134 class TAO_Export TAO_Thread_Policy : public virtual POA_PortableServer::ThreadPolicy
 135 {
 136   void destroy ();
 137 };
 138
 139 void
 140 TAO_Thread_Policy::destroy ()
 141 {
 142   // Remove self from POA.  Because of reference counting, the POA
 143   // will automatically delete the servant when all pending requests
 144   // on this servant are complete.
 145
 146   PortableServer::POA_var poa = this->_default_POA ();
 147
 148   PortableServer::ObjectId_var id = poa->servant_to_id (this);
 149
 150   poa->deactivate_object (id.in ());
 151 }
 152
 153 </PRE>
 154
 155 One additional step required is to make the POA responsible for the
 156 servant after it has been registered with the POA:
 157
 158 <PRE>
 159   // Register with the POA.
 160   PortableServer::ThreadPolicy_var result = new_thread_policy->_this ();
 161
 162   // Give ownership of this servant to the POA.
 163   new_thread_policy->_remove_ref ();
 164 </PRE>
 165
 166 If you use the above approach of multiple inheritance, you must add
 167 the following to your header file:
 168
 169 <PRE>
 170
 171 // This is to remove "inherits via dominance" warnings from MSVC.
 172 // MSVC is being a little too paranoid.
 173 #if defined (_MSC_VER)
 174 # pragma warning (disable : 4250)
 175 #endif /* _MSC_VER */
 176
 177 </PRE>
 178
 179 To see the above example in detail, checkout <A
 180 HREF="../examples/POA/Reference_Counted_Servant">TAO/examples/POA/Reference_Counted_Servant</A>
 181 and/or <A HREF="../tao/PortableServer/Root_POA.cpp">Root_POA.cpp</A> and <A
 182 HREF="../tao/PortableServer/Root_POA.h">Root_POA.h</A>. </li> <p>
 183
 184 </ul>
 185
 186 <hr><P>
 187
 188 Back to the <A HREF="index.html">TAO
 189 documentation</A> page.
 190
 191 <!--#include virtual="/~schmidt/cgi-sig.html" -->
 192 </BODY>
 193 </html>