TAO/tao/Utils/ORB_Manager.h

   1 // -*- C++ -*-
   2
   3 //=============================================================================
   4 /**
   5  *  @file   ORB_Manager.h
   6  *
   7  *  @author Chris Cleeland <cleeland@cs.wustl.edu>
   8  */
   9 //=============================================================================
  10
  11 #ifndef TAO_ORB_MANAGER_H
  12 #define TAO_ORB_MANAGER_H
  13 #include /**/ "ace/pre.h"
  14
  15 #include "tao/Utils/utils_export.h"
  16 #include "tao/PortableServer/PortableServer.h"
  17
  18 #if !defined (ACE_LACKS_PRAGMA_ONCE)
  19 # pragma once
  20 #endif /* ACE_LACKS_PRAGMA_ONCE */
  21
  22 #include "tao/ORB.h"
  23
  24 TAO_BEGIN_VERSIONED_NAMESPACE_DECL
  25
  26 /**
  27  * @class TAO_ORB_Manager
  28  *
  29  * @brief Helper class for simple ORB/POA initialization and
  30  * registering servants with the POA.
  31  *
  32  * This class is a TAO extension that makes it easier to write
  33  * CORBA applications.  It's just a wrapper and doesn't do
  34  * anything special within the ORB itself.
  35  */
  36 class TAO_UTILS_Export TAO_ORB_Manager
  37 {
  38 public:
  39   /** Constructor.
  40    *
  41    *  @param orb  pointer to an ORB which is duplicated an stored
  42    *              internally in an ORB_var.  If pointer is 0,
  43    *              a new ORB pointer is created internally in the init()
  44    *              call.
  45    *
  46    *  @param poa  pointer to a POA which is duplicated and stored
  47    *              internally in a POA_var.  If pointer is 0,
  48    *              a pointer to the Root POA is obtained from the ORB.
  49    *
  50    *  @param poa_manager pointer to a POA Manager which is duplicated
  51    *                     and stored internally in a POAManager_var.
  52    *                     If pointer is 0, a new POAManager is created
  53    *                     internally in the init() call.
  54    */
  55   TAO_ORB_Manager (CORBA::ORB_ptr orb = CORBA::ORB::_nil(),
  56                    PortableServer::POA_ptr poa = PortableServer::POA::_nil(),
  57                    PortableServer::POAManager_ptr poa_manager =
  58                       PortableServer::POAManager::_nil());
  59
  60   /**
  61    * Initialize the ORB/root POA, using the supplied command line
  62    * arguments or the default ORB components.
  63    *
  64    * @retval -1 Failure
  65    * @retval 0 Success
  66    */
  67   int init (int &argc,
  68             ACE_TCHAR *argv[],
  69             const char *orb_name = 0);
  70
  71 #if !defined (CORBA_E_MICRO)
  72   /**
  73    * Creates a child poa under the root poa with PERSISTENT and
  74    * USER_ID policies.  Call this if you want a @a child_poa with the
  75    * above policies, otherwise call init.
  76    *
  77    * @retval -1 Failure
  78    * @retval 0 Success
  79    */
  80   int init_child_poa (int &argc,
  81                       ACE_TCHAR *argv[],
  82                       const char *poa_name,
  83                       const char *orb_name = 0);
  84 #endif /* CORBA_E_MICRO */
  85
  86   /**
  87    * Shut down.  Invoke the destroy() methods on the orb and poa.
  88    *
  89    * @retval -1 Failure
  90    * @retval 0 Success
  91    */
  92   int fini ();
  93
  94   /// Destructor.
  95   ~TAO_ORB_Manager ();
  96
  97   // = Accessor methods.
  98
  99   /**
 100    *  Put POA manager into the <Active> state, so that incoming corba
 101    *  requests are processed.  This method is useful for clients,
 102    *  which are not going to enter "orb->run" loop, yet may want to
 103    *  service incoming requests while waiting for a result of CORBA
 104    *  call on a server.
 105    *
 106    * @retval -1 Failure
 107    * @retval 0 Success
 108    */
 109   int activate_poa_manager ();
 110
 111   /**
 112    * Activate <servant>, using the POA <activate_object> call.  Users
 113    * can call this method multiple times to activate multiple objects.
 114    *
 115    * @return 0 on failure, a string representation of the object ID if
 116    *         successful.  Caller of this method is responsible for
 117    *         memory deallocation of the string.
 118    */
 119   char *activate (PortableServer::Servant servant);
 120
 121   /** Deactivate object in RootPOA.
 122    *
 123    *  @param id  A string representation of the Object ID
 124    *             of the servant to deactivate in the POA
 125    */
 126   void deactivate (const char *id);
 127
 128 #if !defined (CORBA_E_MICRO)
 129   /**
 130    * Precondition: init_child_poa has been called.  Activate <servant>
 131    * using the POA <activate_object_with_id> created from the string
 132    * <object_name>. Users should call this to activate objects under
 133    * the child_poa.
 134    *
 135    * @param object_name  String name which will be used to create
 136    *                     an Object ID for the servant.
 137    * @param servant  The servant to activate under the child POA.
 138    *
 139    * @return 0 on failure, a string representation of the object ID if
 140    *           successful.  Caller of this method is responsible for
 141    *           memory deallocation of the string.
 142    */
 143   char *activate_under_child_poa (const char *object_name,
 144                                   PortableServer::Servant servant);
 145
 146   /**
 147    * Deactivate object in child POA.
 148    *
 149    * @param id  string representation of the object ID, which represents
 150    *            the object to deactivate in the POA
 151    */
 152   void deactivate_under_child_poa (const char *id);
 153 #endif /* CORBA_E_MICRO */
 154
 155   /**
 156    * Run the ORB event loop with the specified @a tv time value.
 157    *
 158    * @param tv  the time interval for how long to run the ORB event loop.
 159    * @retval -1 Failure
 160    * @retval 0 Success
 161    */
 162   int run (ACE_Time_Value &tv);
 163
 164   /**
 165    * Run the ORB event loop.
 166    */
 167   int run ();
 168
 169   /**
 170    * Accessor which returns the ORB pointer.  Following the normal
 171    * CORBA memory management rules of return values from functions,
 172    * this function duplicates the orb return value before returning
 173    * it.
 174    *
 175    * @return ORB pointer which has been duplicated, so caller
 176    *         must release pointer when done.
 177    */
 178   CORBA::ORB_ptr orb ();
 179
 180   /**
 181    * Accessor which returns the root poa. Following the normal CORBA
 182    * memory management rules of return values from functions, this
 183    * function duplicates the poa return value before returning it.
 184    *
 185    * @return Root POA pointer which has been duplicated.  Caller
 186    *         must release pointer when done.
 187    */
 188   PortableServer::POA_ptr root_poa ();
 189
 190   /**
 191    * Accessor which returns the child poa. Following the normal CORBA
 192    * memory management rules of return values from functions, this
 193    * function duplicates the poa return value before returning it.
 194    *
 195    * @return Child POA pointer which has been duplicated.  Caller
 196    *         must release pointer when done.
 197    */
 198   PortableServer::POA_ptr child_poa ();
 199
 200   /**
 201    * Accessor which returns the poa manager. Following the normal
 202    * CORBA memory management rules of return values from functions,
 203    * this function duplicates the poa manager return value before
 204    * returning it.
 205    *
 206    * @return POAManager pointer which has been duplicated.  Caller
 207    *         must release pointer when done.
 208    */
 209   PortableServer::POAManager_ptr poa_manager ();
 210
 211 protected:
 212   /// The ORB.
 213   CORBA::ORB_var orb_;
 214
 215   /// The POA for this ORB.
 216   PortableServer::POA_var poa_;
 217
 218   /// Child poa under the root POA.
 219   PortableServer::POA_var child_poa_;
 220
 221   /// The POA manager of poa_.
 222   PortableServer::POAManager_var poa_manager_;
 223 };
 224
 225 TAO_END_VERSIONED_NAMESPACE_DECL
 226
 227 #include /**/ "ace/post.h"
 228 #endif /* TAO_ORB_MANAGER_H */