TAO/tao/Exception.h

   1 // -*- C++ -*-
   2
   3 //=============================================================================
   4 /**
   5  *  @file    Exception.h
   6  *
   7  *   This file defines way in which CORBA exceptions are reported.
   8  *
   9  *  @author DOC Group at Vanderbilt U., Wash U, and UCI
  10  */
  11 //=============================================================================
  12
  13 #ifndef TAO_EXCEPTION_H
  14 #define TAO_EXCEPTION_H
  15
  16 #include /**/ "ace/pre.h"
  17
  18 // Do not try removing this. If you remove this for subsetting lots of
  19 // things go wrong in TAO.
  20 #include "tao/orbconf.h"
  21
  22 #if !defined (ACE_LACKS_PRAGMA_ONCE)
  23 # pragma once
  24 #endif /* ACE_LACKS_PRAGMA_ONCE */
  25
  26 #include /**/ "tao/TAO_Export.h"
  27 #include "tao/Basic_Types.h"
  28 #include "tao/CORBA_String.h"
  29 #include "ace/SStringfwd.h"
  30 #include "ace/iosfwd.h"
  31 #include "ace/CORBA_macros.h"
  32
  33
  34 ACE_BEGIN_VERSIONED_NAMESPACE_DECL
  35 class ACE_Allocator;
  36 ACE_END_VERSIONED_NAMESPACE_DECL
  37
  38 TAO_BEGIN_VERSIONED_NAMESPACE_DECL
  39
  40 class TAO_OutputCDR;
  41 class TAO_InputCDR;
  42
  43 // This is already done in orbconf.h. But this file is totally
  44 // decoupled from its contents that we have to do this here. Including
  45 // orbconf.h is probably going to be a overhead.
  46 #if defined (minor)
  47 #undef minor
  48 #endif /* minor */
  49
  50 namespace CORBA
  51 {
  52   class TypeCode;
  53   typedef TypeCode * TypeCode_ptr;
  54
  55   class Environment;
  56
  57   class Any;
  58   typedef Any * Any_ptr;
  59
  60   class SystemException;
  61
  62   /**
  63    * @enum exception_type
  64    *
  65    * @brief Enumeration used to identify the type of CORBA exception.
  66    *
  67    * CORBA exceptions generally fall into two categories, user
  68    * exceptions and system exceptions.  This enumeration is used when
  69    * identifying the type of CORBA exception.
  70    */
  71   enum exception_type
  72   {
  73     NO_EXCEPTION,
  74     USER_EXCEPTION,
  75     SYSTEM_EXCEPTION
  76   };
  77
  78   /**
  79    * @class Exception
  80    *
  81    * @brief Exception
  82    *
  83    * CORBA2-specified exception hierarchy.  All exceptions have a
  84    * type (represented by a @c TypeCode) and a widely scoped type ID
  85    * (in the @c TypeCode) that are generated by any OMG-IDL compiler
  86    * and available through the Interface Repository.  Think of it as a
  87    * "globally scoped" name distinguishing each exception.
  88     *
  89     * @todo According to the OMG CORBA C++ Mapping version 1.1,
  90     *       the copy constructors
  91     *       should be moved to "protected" section in class
  92     *       declarations.  Since the current MS Visual C++ 7.1 compiler
  93     *       will cause some problems to TAO's exception mechanism, we
  94     *       defer doing this until we drop support for MSVC++ 7.1. Maybe
  95     *       there is another solution, have to test that later.
  96     */
  97   class TAO_Export Exception
  98   {
  99   public:
 100     /// Copy constructor.
 101     /**
 102      * @note This constructor should be protected, but VC7.1 at
 103      *       warning level 4 complains about the inaccessible copy
 104      *       constructor preventing it from being caught.  However,
 105      *       that probably isn't true for most cases since CORBA
 106      *       exceptions are typically caught by reference, not by
 107      *       copy.
 108      */
 109     Exception (const Exception &src);
 110
 111     /// Destructor.
 112     virtual ~Exception () = default;
 113
 114     // = To throw the exception (when using the standard mapping).
 115     virtual void _raise () const = 0;
 116
 117     // = The static narrow operations.
 118     static Exception * _downcast (Exception * x);
 119     static Exception const * _downcast (Exception const * x);
 120
 121     /// Return the repository ID of the Exception.
 122     virtual const char * _rep_id () const;
 123
 124     /// Return the name of the Exception.
 125     virtual const char * _name () const;
 126
 127     // = These are TAO-specific extensions.
 128
 129     /// Will be overridden in the concrete derived classes.
 130     virtual CORBA::TypeCode_ptr _tao_type () const = 0;
 131
 132     /// Print the exception to output determined by @a f.
 133     /**
 134      * @note This method is TAO-specific.
 135      */
 136     void _tao_print_exception (const char *info, FILE *f = stdout) const;
 137
 138 #if defined (ACE_USES_WCHAR)
 139     /// ACE_WCHAR_T version of _tao_print_exception.
 140     /**
 141      * @note This method is TAO-specific.
 142      */
 143     void _tao_print_exception (const ACE_WCHAR_T *info, FILE *f = stdout) const;
 144 #endif  // ACE_USES_WCHAR
 145
 146     /// Returns a string containing information about the exception. This
 147     /// function is not CORBA compliant.
 148     virtual ACE_CString _info () const = 0;
 149
 150     virtual void _tao_encode (TAO_OutputCDR &cdr) const = 0;
 151
 152     virtual void _tao_decode (TAO_InputCDR &cdr) = 0;
 153
 154     /// Used in the non-copying Any insertion operator.
 155     static void _tao_any_destructor (void *);
 156
 157     /// Deep copy
 158     /**
 159      * The following operation is used in the implementation of
 160      * it performs a deep copy of the
 161      * exception, normally it is implemented as:
 162      *
 163      * <PRE>
 164      * class SomeException : public // Derives from CORBA::Exception
 165      * {
 166      * public:
 167      *   CORBA::Exception *_tao_duplicate () override const
 168      *   {
 169      *     CORBA::Exception *result {};
 170      *     ACE_NEW_RETURN (
 171      *         result,
 172      *         SomeException (*this),
 173      *         nullptr);
 174      *     return result;
 175      *   }
 176      * };
 177      * </PRE>
 178      */
 179     virtual CORBA::Exception *_tao_duplicate () const = 0;
 180
 181   protected:
 182     /// Default constructor.
 183     Exception () = default;
 184
 185     /// Assignment operator.
 186     Exception & operator = (const Exception & src);
 187
 188     /// Construct from a repository id.
 189     Exception (const char *repository_id, const char *local_name);
 190
 191   private:
 192     /// Repository Id
 193     CORBA::String_var id_;
 194
 195     /// Local name.
 196     CORBA::String_var name_;
 197   };
 198
 199 #if !defined (ACE_LACKS_IOSTREAM_TOTALLY)
 200
 201   // Required by C++ mapping.
 202   TAO_Export ACE_OSTREAM_TYPE& operator<< (ACE_OSTREAM_TYPE &os,
 203                                            const CORBA::Exception &e);
 204
 205   TAO_Export ACE_OSTREAM_TYPE& operator<< (ACE_OSTREAM_TYPE &os,
 206                                            const CORBA::Exception *e);
 207
 208 #endif /* (ACE_LACKS_IOSTREAM_TOTALLY) */
 209 } // End CORBA namespace
 210
 211 namespace TAO
 212 {
 213   /// Create a CORBA::SystemException given the interface repository ID.
 214   TAO_Export CORBA::SystemException *create_system_exception (const char *id);
 215 }
 216
 217 TAO_END_VERSIONED_NAMESPACE_DECL
 218
 219 #if defined (__ACE_INLINE__)
 220 # include "tao/Exception.inl"
 221 #endif /* __ACE_INLINE__ */
 222
 223 #include /**/"ace/post.h"
 224
 225 #endif /* TAO_EXCEPTION_H */