ORB.h

Go to the documentation of this file.
00001 // -*- C++ -*-
00002 
00003 //=============================================================================
00004 /**
00005  *  @file    ORB.h
00006  *
00007  *  $Id: ORB.h 81270 2008-04-08 12:16:13Z iliyan $
00008  *
00009  *  Header file for CORBA's ORB type.
00010  *
00011  *  @author DOC Center - Washington University at St. Louis
00012  *  @author DOC Group - Vanderbilt University
00013  *  @author DOC Laboratory - University of California at Irvine
00014  */
00015 //=============================================================================
00016 
00017 #ifndef TAO_ORB_H
00018 #define TAO_ORB_H
00019 
00020 #include /**/ "ace/pre.h"
00021 
00022 #include "tao/UserException.h"
00023 
00024 #if !defined (ACE_LACKS_PRAGMA_ONCE)
00025 # pragma once
00026 #endif /* ACE_LACKS_PRAGMA_ONCE */
00027 
00028 #include "tao/orb_typesC.h"
00029 #include "tao/objectid.h"
00030 #include "tao/CORBA_methods.h"
00031 #include "tao/VarOut_T.h"
00032 #include "tao/Pseudo_VarOut_T.h"
00033 #include "tao/Seq_Var_T.h"
00034 #include "tao/Seq_Out_T.h"
00035 #include "tao/Sequence_T.h"
00036 #include "tao/Policy_ForwardC.h"
00037 #include "tao/ServicesC.h"
00038 
00039 #include "ace/Thread_Mutex.h"
00040 #include "ace/Guard_T.h"
00041 #include "ace/Atomic_Op.h"
00042 
00043 TAO_BEGIN_VERSIONED_NAMESPACE_DECL
00044 
00045 typedef enum
00046 {
00047   TAO_SERVICEID_NAMESERVICE,
00048   TAO_SERVICEID_TRADINGSERVICE,
00049   TAO_SERVICEID_IMPLREPOSERVICE,
00050   TAO_SERVICEID_INTERFACEREPOSERVICE,
00051   TAO_SERVICEID_MCASTSERVER
00052 } TAO_Service_ID;
00053 
00054 /// Forward declarations.
00055 class TAO_MProfile;
00056 class TAO_Client_Strategy_Factory;
00057 class TAO_Server_Strategy_Factory;
00058 class TAO_InputCDR;
00059 class TAO_OutputCDR;
00060 class TAO_Stub;
00061 class TAO_Valuetype_Adapter;
00062 class TAO_Acceptor_Filter;
00063 class TAO_ORB_Core;
00064 
00065 // ****************************************************************
00066 
00067 namespace CORBA
00068 {
00069   class EnumMemberSeq;
00070   class StructMemberSeq;
00071   class UnionMemberSeq;
00072   class ValueMemberSeq;
00073   class ORB_ObjectIdList;
00074 
00075   class ExceptionList;
00076   typedef ExceptionList * ExceptionList_ptr;
00077 
00078   class ContextList;
00079   typedef ContextList * ContextList_ptr;
00080 
00081   class Context;
00082   typedef Context * Context_ptr;
00083 
00084   class NVList;
00085   typedef NVList *NVList_ptr;
00086 
00087   class NamedValue;
00088   typedef NamedValue *NamedValue_ptr;
00089 
00090   class Policy;
00091   typedef Policy *Policy_ptr;
00092 
00093   typedef CORBA::ULong PolicyType;
00094 
00095   // TODO - implement OMG's 'ORBid CORBA::ORB::id (void)'.
00096 
00097   typedef
00098     TAO_VarSeq_Var_T<
00099         ORB_ObjectIdList
00100       >
00101     ORB_ObjectIdList_var;
00102 
00103   typedef
00104     TAO_Seq_Out_T<
00105         ORB_ObjectIdList
00106       >
00107     ORB_ObjectIdList_out;
00108 
00109   class ValueFactoryBase;
00110   typedef ValueFactoryBase *ValueFactory;
00111 
00112   typedef UShort ServiceType;
00113 
00114   class Request;
00115   typedef Request * Request_ptr;
00116   typedef TAO_Pseudo_Var_T<Request> Request_var;
00117   typedef TAO_Pseudo_Out_T<Request> Request_out;
00118 
00119   class ORB;
00120   typedef ORB * ORB_ptr;
00121   typedef TAO_Pseudo_Var_T<ORB> ORB_var;
00122   typedef TAO_Pseudo_Out_T<ORB> ORB_out;
00123 
00124   typedef CORBA::Short ValueModifier;
00125 
00126 #if (TAO_HAS_MINIMUM_CORBA == 0) && !defined (CORBA_E_COMPACT) && !defined (CORBA_E_MICRO)
00127 
00128     // Typedefs for CORBA::RequestSeq, which is an argument of
00129     // send_multiple_requests_*().
00130 
00131     typedef
00132       TAO::unbounded_object_reference_sequence<
00133           CORBA::Request, CORBA::Request_var
00134         >
00135       RequestSeq;
00136 
00137     typedef
00138       TAO_VarSeq_Var_T<
00139           RequestSeq
00140         >
00141       RequestSeq_var;
00142 
00143     typedef
00144       TAO_Seq_Out_T<
00145           RequestSeq
00146         >
00147       RequestSeq_out;
00148 #endif
00149 
00150   /**
00151    * @class ORB
00152    *
00153    * @brief ORB pseudo-object.
00154    *
00155    * The "ORB" pseudo-object is used in bootstrapping, such as to
00156    * create object references from strings.  This class is intended
00157    * to be inherited by others, which will provide some more of the
00158    * CORBA support.  Implementations of this "CORBA::ORB" class must
00159    * know how to create stringify/destringify their objrefs, as well
00160    * as how to marshal and unmarshal them.
00161    */
00162   class TAO_Export ORB
00163   {
00164   public:
00165 
00166     class TAO_Export InvalidName : public CORBA::UserException
00167     {
00168     public:
00169       InvalidName (void);
00170       InvalidName (const InvalidName &);
00171       ~InvalidName (void);
00172 
00173       InvalidName &operator= (const InvalidName &);
00174 
00175       static InvalidName *_downcast (CORBA::Exception *);
00176       static CORBA::Exception *_alloc (void);
00177 
00178       virtual CORBA::Exception *_tao_duplicate (void) const;
00179 
00180       virtual void _raise (void) const;
00181 
00182       virtual void _tao_encode (TAO_OutputCDR &) const;
00183 
00184       virtual void _tao_decode (TAO_InputCDR &);
00185     };
00186 
00187     typedef char *ObjectId;
00188     typedef CORBA::String_var ObjectId_var;
00189     typedef CORBA::String_out ObjectId_out;
00190     static CORBA::TypeCode_ptr const _tc_ObjectId;
00191 
00192     typedef CORBA::ORB_ObjectIdList ObjectIdList;
00193     typedef CORBA::ORB_ObjectIdList_var ObjectIdList_var;
00194     typedef CORBA::ORB_ObjectIdList_out ObjectIdList_out;
00195     typedef CORBA::ORB_ObjectIdList *ObjectIdList_ptr;
00196     static CORBA::TypeCode_ptr const _tc_ObjectIdList;
00197 
00198     /// Return a duplicate of @c orb.
00199     /**
00200      * When work with this duplicate is complete, it should be freed
00201      * up using CORBA::release().
00202      */
00203     static CORBA::ORB_ptr _duplicate (CORBA::ORB_ptr orb);
00204 
00205     /// Returns a pointer to a nil ORB, i.e., an non-existent ORB.  This
00206     /// can be used for initialization or in comparisons.
00207     static CORBA::ORB_ptr _nil (void);
00208 
00209     /// Return this ORB's ORBid.
00210     char * id (void);
00211 
00212     /**
00213      * Turn a string-ified object reference back into an object
00214      * pointer.  Typically these strings are created using
00215      * object_to_string(), but not necessarily locally.
00216      */
00217     CORBA::Object_ptr string_to_object (const char *str);
00218 
00219     /**
00220      * Turn an object reference into a string.  Each type of ORB,
00221      * e.g. an IIOP ORB, must implement this.  This can be used by
00222      * servers to publish their whereabouts to clients.  The output of
00223      * this is typically eventually given to @c string_to_object() as
00224      * an argument.
00225      */
00226     char * object_to_string (CORBA::Object_ptr obj);
00227 
00228 #if !defined(CORBA_E_MICRO)
00229     // Value factory operations  (CORBA 2.3 ptc/98-10-05 Ch. 4.2 p.4-7)
00230     CORBA::ValueFactory register_value_factory (
00231         const char *repository_id,
00232         CORBA::ValueFactory factory);
00233 #endif
00234 
00235 #if !defined(CORBA_E_MICRO)
00236     void unregister_value_factory (const char * repository_id);
00237 #endif
00238 
00239 #if !defined(CORBA_E_MICRO)
00240     CORBA::ValueFactory lookup_value_factory (const char *repository_id);
00241 #endif
00242 
00243 #if (TAO_HAS_MINIMUM_CORBA == 0) && !defined (CORBA_E_COMPACT) && !defined (CORBA_E_MICRO)
00244 
00245     void create_list (CORBA::Long count, CORBA::NVList_ptr &new_list);
00246 
00247     void create_operation_list(CORBA::OperationDef_ptr opDef,
00248                                CORBA::NVList_ptr& result);
00249 
00250     void create_named_value (CORBA::NamedValue_ptr &nmval);
00251 
00252     void create_exception_list (CORBA::ExceptionList_ptr &exclist);
00253 
00254     void create_environment (CORBA::Environment_ptr &new_env);
00255 
00256     // The following are not implemented and just throw
00257     // CORBA::NO_IMPLEMENT.
00258 
00259     void create_context_list (CORBA::ContextList_ptr &ctxtlist);
00260 
00261     void get_default_context (CORBA::Context_ptr &ctx);
00262 
00263     CORBA::Boolean get_service_information (
00264       CORBA::ServiceType service_type,
00265       CORBA::ServiceInformation_out service_information);
00266 
00267     void send_multiple_requests_oneway (const CORBA::RequestSeq &req);
00268 
00269     void send_multiple_requests_deferred (const CORBA::RequestSeq &req);
00270 
00271     void get_next_response (CORBA::Request_ptr &req);
00272 
00273     CORBA::Boolean poll_next_response (void);
00274 
00275     /// The ORB TypeCode creation functions.
00276 
00277     CORBA::TypeCode_ptr create_struct_tc (
00278         const char *id,
00279         const char *name,
00280         const CORBA::StructMemberSeq &members);
00281 
00282     CORBA::TypeCode_ptr create_union_tc (
00283         const char *id,
00284         const char *name,
00285         CORBA::TypeCode_ptr discriminator_type,
00286         const CORBA::UnionMemberSeq &members);
00287 
00288     CORBA::TypeCode_ptr create_enum_tc (
00289         const char *id,
00290         const char *name,
00291         const CORBA::EnumMemberSeq &members);
00292 
00293     CORBA::TypeCode_ptr create_alias_tc (
00294         const char *id,
00295         const char *name,
00296         CORBA::TypeCode_ptr original_type);
00297 
00298     CORBA::TypeCode_ptr create_exception_tc (
00299         const char *id,
00300         const char *name,
00301         const CORBA::StructMemberSeq &members);
00302 
00303     CORBA::TypeCode_ptr create_interface_tc (const char *id, const char *name);
00304 
00305     CORBA::TypeCode_ptr create_string_tc (CORBA::ULong bound);
00306 
00307     CORBA::TypeCode_ptr create_wstring_tc (CORBA::ULong bound);
00308 
00309     CORBA::TypeCode_ptr create_fixed_tc (
00310         CORBA::UShort digits,
00311         CORBA::UShort scale);
00312 
00313     CORBA::TypeCode_ptr create_sequence_tc (
00314         CORBA::ULong bound,
00315         CORBA::TypeCode_ptr element_type);
00316 
00317     CORBA::TypeCode_ptr create_array_tc (
00318         CORBA::ULong length,
00319         CORBA::TypeCode_ptr element_type);
00320 
00321     CORBA::TypeCode_ptr create_value_tc (
00322         const char *id,
00323         const char *name,
00324         CORBA::ValueModifier type_modifier,
00325         CORBA::TypeCode_ptr concrete_base,
00326         const CORBA::ValueMemberSeq &members);
00327 
00328     CORBA::TypeCode_ptr create_value_box_tc (
00329         const char *id,
00330         const char *name,
00331         CORBA::TypeCode_ptr boxed_type);
00332 
00333     CORBA::TypeCode_ptr create_native_tc (const char *id, const char *name);
00334 
00335     CORBA::TypeCode_ptr create_recursive_tc (const char *id);
00336 
00337     CORBA::TypeCode_ptr create_abstract_interface_tc (
00338         const char *id,
00339         const char *name);
00340 
00341     CORBA::TypeCode_ptr create_local_interface_tc (
00342         const char *id,
00343         const char *name);
00344 
00345     CORBA::TypeCode_ptr create_component_tc (
00346         const char *id,
00347         const char *name);
00348 
00349     CORBA::TypeCode_ptr create_home_tc (
00350         const char *id,
00351         const char *name);
00352 
00353     CORBA::TypeCode_ptr create_event_tc (
00354         const char *id,
00355         const char *name,
00356         CORBA::ValueModifier type_modifier,
00357         CORBA::TypeCode_ptr concrete_base,
00358         const CORBA::ValueMemberSeq &members);
00359 
00360 #endif /* TAO_HAS_MINIMUM_CORBA */
00361 
00362     // = ORB event loop methods.
00363 
00364     /**
00365      * Instructs the ORB to initialize itself and run its event loop in
00366      * the current thread, not returning until the ORB has shut down.
00367      * If an error occurs during initialization or at runtime, a CORBA
00368      * system exception will be thrown.
00369      */
00370     void run (void);
00371 
00372     /**
00373      * Instructs the ORB to initialize itself and run its event loop in
00374      * the current thread, not returning until the ORB has shut down or
00375      * the time value specified through @a tv has expired.  If an
00376      * error occurs during initialization or at runtime, a CORBA
00377      * system exception will be thrown.  @a tv is reduced by the
00378      * amount of time spent in this call.
00379      *
00380      * If this function is called with a @ tv value, client threads
00381      * making invocations will continue their operations. When the
00382      * operation timesout and returns, any invocations showing up on
00383      * the server will be buffered by TCP.
00384      **/
00385     void run (ACE_Time_Value &tv);
00386 
00387     /**
00388      * Instructs the ORB to initialize itself and run its event loop in
00389      * the current thread, not returning until the ORB has shut down or
00390      * the time value specified through @a tv has expired.  If an error
00391      * occurs during initialization or at runtime, a CORBA system
00392      * exception will be thrown.  @a tv is reduced by the amount of time
00393      * spent in this call.  If @a tv is 0, it means that the timeout
00394      * is infinite.  If @a tv is @c ACE_Time_Value::zero, it specifies
00395      * to poll and does not block.
00396      *
00397      * If this function is called with @a tv value, client threads
00398      * making invocations will continue their operations. When the
00399      * operation times out and returns, any invocations showing up on
00400      * the server will be buffered by TCP.
00401      **/
00402     void run (ACE_Time_Value *tv);
00403 
00404     /// Returns an indication of whether the ORB needs to perform some
00405     /// work.
00406     CORBA::Boolean work_pending (void);
00407 
00408     /// Returns an indication of whether the ORB needs to perform some
00409     /// work but will look for work pending for no more than the
00410     /// specified time.
00411     /**
00412      * @note This is useful for implementing an event loop with an
00413      *       idle timeout.
00414      */
00415     CORBA::Boolean work_pending (ACE_Time_Value &tv);
00416 
00417     /**
00418      * This operation performs an implementation-defined unit of work.
00419      * Note that the default behavior is to block if the unit of work
00420      * is not present; this behavior can be modified by passing an
00421      * appropriate @c ACE_Time_Value as described in run().
00422      **/
00423     void perform_work (void);
00424     void perform_work (ACE_Time_Value &tv);
00425     void perform_work (ACE_Time_Value *tv);
00426 
00427     /**
00428      * This operation instructs the ORB to shut down. Shutting down the
00429      * ORB causes all Object Adapters to be shut down. If
00430      * @c wait_for_completion parameter is TRUE, this operation blocks
00431      * until all ORB processing (including request processing and object
00432      * deactivation or other operations associated with object adapters)
00433      * has completed.
00434      */
00435     void shutdown (CORBA::Boolean wait_for_completion = false);
00436 
00437     /**
00438      * Explicitly destroy the ORB, releasing any resources.  Note that
00439      * TAO *cannot* implicitly release the resources even if you have
00440      * destroyed all the references to a particular ORB since
00441      * CORBA::ORB_init() is required to return the same pointer if
00442      * called with the same ORBid, only after ORB::destroy() is called
00443      * it may return a new one.
00444      *
00445      * The results of multi-threaded applications, trying to destroy ()
00446      * the ORB in one thread and trying to service a request in another
00447      * thread are not well defined. TAO does not support such cases.
00448      */
00449     void destroy (void);
00450 
00451     /**
00452      * This method acts as a mini-bootstrapping Naming Service, which is
00453      * provided by the ORB for certain well-known object references.  TAO
00454      * supports the "NameService", "TradingService", "RootPOA",
00455      * "ImplRepo", and "POACurrent" via this method.  The @c timeout
00456      * value bounds the amount of time the ORB blocks waiting to
00457      * resolve the service.  This is most useful for bootstrapping
00458      * remote services, such as the "NameService" or "TradingService",
00459      * that are commonly resolved via multicast.  By default, the
00460      * value is 0, which means "use the @c
00461      * TAO_DEFAULT_SERVICE_RESOLUTION_TIMEOUT timeout period".
00462      *
00463      * @note By using a default value for the @c timeout parameter,
00464      *       TAO will remains compliant with the CORBA
00465      *       resolve_initial_references() specification.
00466      */
00467     CORBA::Object_ptr resolve_initial_references (
00468       const char *name,
00469       ACE_Time_Value *timeout = 0);
00470 
00471 #if !defined(CORBA_E_MICRO)
00472     /// Register an object reference with the ORB.
00473     void register_initial_reference (const char * id, CORBA::Object_ptr obj);
00474 #endif
00475 
00476     /// Returns a sequence of ObjectIds that lists which objects have
00477     /// references available via the initial references mechanism.
00478     CORBA::ORB::ObjectIdList_ptr list_initial_services (void);
00479 
00480 #if !defined(CORBA_E_MICRO)
00481     CORBA::Policy_ptr create_policy (CORBA::PolicyType type,
00482                                      const CORBA::Any& val);
00483 #endif
00484 
00485     // ----------------------------------------------------------------
00486     // = TAO-specific extensions to the CORBA specification.
00487     // ----------------------------------------------------------------
00488 
00489 #if !defined(CORBA_E_MICRO)
00490     /// Create an empty policy, usually to be filled in later by
00491     /// demarshaling.
00492     CORBA::Policy_ptr _create_policy (CORBA::PolicyType type);
00493 #endif
00494 
00495     // Reference counting...
00496     unsigned long _incr_refcnt (void);
00497     unsigned long _decr_refcnt (void);
00498 
00499     /// Set the IOR flag.
00500     void _use_omg_ior_format (CORBA::Boolean ior);
00501 
00502     /// Get the IOR flag.
00503     CORBA::Boolean _use_omg_ior_format (void);
00504 
00505     /// Get the ORB core.
00506     TAO_ORB_Core *orb_core (void) const;
00507 
00508     /// Factory method that creates an ORB.
00509     static CORBA::ORB_ptr _tao_make_ORB (TAO_ORB_Core * orb_core);
00510 
00511     // Useful for template programming.
00512     typedef ORB_ptr _ptr_type;
00513     typedef ORB_var _var_type;
00514     typedef ORB_out _out_type;
00515 
00516     /// Get the Timeout value
00517     ACE_Time_Value *get_timeout (void);
00518 
00519   protected:
00520 
00521     // We must be created via the @c CORBA::ORB_init() function.
00522     ORB (TAO_ORB_Core *orb_core);
00523 
00524     /// Destructor
00525     /**
00526      * Protected destructor to enforce proper memory management
00527      * through the reference counting mechanism.
00528      */
00529     ~ORB (void);
00530 
00531     /// Resolve the Policy Manager for this ORB.
00532     CORBA::Object_ptr resolve_policy_manager (void);
00533 
00534     /// Resolve the Policy Current for this thread.
00535     CORBA::Object_ptr resolve_policy_current (void);
00536 
00537   private:
00538 
00539     /// Resolve the given service based on the service ID.
00540     /**
00541      * "@c resolve_service" is a legacy name.  This method now simply
00542      * sets up a default initial reference that will be subsequently
00543      * used in resolve_initial_references().
00544      */
00545     void resolve_service (TAO::MCAST_SERVICEID service_id);
00546 
00547     /// Convert an OMG IOR into an object reference.
00548     CORBA::Object_ptr ior_string_to_object (const char* ior);
00549 
00550     /// Convert an URL style IOR into an object reference.
00551     CORBA::Object_ptr url_ior_string_to_object (const char* ior);
00552 
00553     /// Check if ORB has shutdown.  If it has, throw the appropriate
00554     /// exception.
00555     void check_shutdown (void);
00556 
00557     /// Set the timeout value
00558     void set_timeout (ACE_Time_Value * timeout);
00559 
00560   private:
00561 
00562     /// Maintains a reference count of number of instantiations of the
00563     /// ORB.
00564     ACE_Atomic_Op<TAO_SYNCH_MUTEX, unsigned long> refcount_;
00565 
00566     /// The ORB_Core that created us....
00567     TAO_ORB_Core * orb_core_;
00568 
00569     /// Decides whether to use the URL notation or to use IOR notation.
00570     CORBA::Boolean use_omg_ior_format_;
00571 
00572     // Prevent copying and assignment.
00573     ORB (const ORB &);
00574     ORB &operator= (const ORB &);
00575 
00576     /// Timeout value
00577     ACE_Time_Value * timeout_;
00578 
00579   };
00580 }  // End namespace CORBA
00581 
00582 
00583 TAO_END_VERSIONED_NAMESPACE_DECL
00584 
00585 #if defined (__ACE_INLINE__)
00586 # include "tao/ORB.inl"
00587 #endif /* __ACE_INLINE__ */
00588 
00589 #include /**/ "ace/post.h"
00590 
00591 #endif /* TAO_ORB_H */

Generated on Tue Feb 2 17:37:52 2010 for TAO by  doxygen 1.4.7