00001 // -*- C++ -*- 00002 00003 //============================================================================= 00004 /** 00005 * @file Environment.h 00006 * 00007 * $Id: Environment.h 74014 2006-08-14 13:52:22Z johnnyw $ 00008 * 00009 * Declare the CORBA::Environment class. Note that this header file 00010 * only requires a few forward declarations of CORBA classes, this 00011 * is *very* important because even the ORB needs to know about it; 00012 * make your changes with care. It is also a good idea trying to 00013 * minimize cross dependencies between header files. 00014 * 00015 * @author Carlos O'Ryan <coryan@cs.wustl.edu> 00016 */ 00017 //============================================================================= 00018 #ifndef TAO_ENVIRONMENT_H 00019 #define TAO_ENVIRONMENT_H 00020 00021 #include /**/ "ace/pre.h" 00022 00023 #include /**/ "tao/TAO_Export.h" 00024 00025 #if !defined (ACE_LACKS_PRAGMA_ONCE) 00026 # pragma once 00027 #endif /* ACE_LACKS_PRAGMA_ONCE */ 00028 00029 #include "tao/Basic_Types.h" 00030 #include "tao/CORBA_methods.h" 00031 #include "tao/orbconf.h" 00032 #include "tao/Pseudo_VarOut_T.h" 00033 #include "tao/default_environment.h" 00034 00035 TAO_BEGIN_VERSIONED_NAMESPACE_DECL 00036 00037 class TAO_ORB_Core; 00038 00039 namespace CORBA 00040 { 00041 class Exception; 00042 00043 class Environment; 00044 typedef Environment *Environment_ptr; 00045 typedef TAO_Pseudo_Var_T<Environment> Environment_var; 00046 typedef TAO_Pseudo_Out_T<Environment> Environment_out; 00047 00048 /** 00049 * @class Environment 00050 * 00051 * @brief Environment 00052 * 00053 * A CORBA::Environment is a way to automagically ensure that 00054 * exception data is freed -- the "var" class for Exceptions. It 00055 * adds just a bit of convenience function support, helping 00056 * classify exceptions as well as reducing memory leakage. 00057 * The thread has a default environment to simplify porting 00058 * between platforms that support native C++ exceptions and those 00059 * that don't. This is a TSS resource (always), but with a twist: 00060 * if the user creates a new environment the old one is "pushed" 00061 * (actually the new one remembers it), eventually the new 00062 * environment destructor pops itself from the stack and we 00063 * recover the old environment. This means that if the user 00064 * create a new environment and somebody calls a function using 00065 * the default one the exception will still be received in the 00066 * environment created by the user. The only drawback is that 00067 * environments life time must nest properly, this shouldn't be a 00068 * problem because environments are usually created on the stack, 00069 * but, the spec allows their creation on the heap and/or as class 00070 * members; we need to investigate the tradeoffs and take a 00071 * decision. 00072 */ 00073 class TAO_Export Environment 00074 { 00075 public: 00076 /// The default constructor. The environment will hold no 00077 /// exceptions. 00078 Environment (void); 00079 00080 /// Copy constructor. 00081 Environment (const Environment &ACE_TRY_ENV); 00082 00083 /// Assingment. 00084 Environment &operator=(const Environment &ACE_TRY_ENV); 00085 00086 /// Destructor, release the exception. 00087 ~Environment (void); 00088 00089 /// Some static methods that need to be defined in every pseudo object 00090 static Environment * _duplicate (Environment *); 00091 static Environment * _nil (void); 00092 00093 /// Return the contained CORBA::Exception. 00094 /** 00095 * CORBA::Environment retains ownership of the exception, this is 00096 * contrary to the normal memory management rules in the C++ 00097 * mapping, but actually mandated by the specification: 00098 * 00099 * "C++ Language Mapping" (formal/00-01-02). Section 1.27 00100 * Environment (page 1-113) 00101 */ 00102 CORBA::Exception* exception (void) const; 00103 00104 /// Set the contained CORBA::Exception to <ex> 00105 /** 00106 * CORBA::Environment assumes ownership of the exception, this is 00107 * contrary to the normal memory management rules in the C++ 00108 * mapping, but actually mandated by the specification: 00109 * 00110 * "C++ Language Mapping" (formal/00-01-02). Section 1.27 00111 * Environment (page 1-113) 00112 * 00113 */ 00114 void exception (CORBA::Exception *ex); 00115 00116 /// Return if the exception is a user exception or a system 00117 /// exception. 00118 int exception_type (void) const; 00119 00120 /// return the repository ID for the exception. 00121 const char *exception_id (void) const; 00122 00123 /// Clear the exception. 00124 void clear (void); 00125 00126 /// Print the exception to output determined by f. This function 00127 /// is not CORBA compliant. 00128 void print_exception (const char *info, 00129 FILE *f=stdout) const; 00130 00131 // = Obtain a default environment to use with TAO. 00132 static CORBA::Environment &default_environment (void); 00133 00134 // Useful for template programming. 00135 typedef CORBA::Environment_ptr _ptr_type; 00136 typedef CORBA::Environment_var _var_type; 00137 typedef CORBA::Environment_out _out_type; 00138 00139 private: 00140 00141 /// Initialize using a well known ORB Core; this is intended for 00142 /// the bootstraping of the ORB_Core, not for general 00143 /// consumption. 00144 Environment (TAO_ORB_Core *orb_core); 00145 00146 /// Pointer to the exception object contained in the environment. 00147 CORBA::Exception *exception_; 00148 00149 /// The previous environment on the "default environment stack". 00150 Environment *previous_; 00151 }; 00152 } // End CORBA namespace 00153 00154 TAO_END_VERSIONED_NAMESPACE_DECL 00155 00156 00157 #if defined (__ACE_INLINE__) 00158 # include "tao/Environment.inl" 00159 #endif /* __ACE_INLINE__ */ 00160 00161 #include /**/ "ace/post.h" 00162 #endif /* TAO_ENVIRONMENT_H */