On this page:
C++ Mapping for User Exceptions
Here is a fragment of the Slice definition for our world time server once more:
These exception definitions map as follows:
Each Slice exception is mapped to a C++ class with the same name. For each exception member, the corresponding class contains a public data member. (Since
BadZoneName do not have members, the generated classes for these exceptions also do not have members.) Optional data members are mapped to instances of the
The inheritance structure of the Slice exceptions is preserved for the generated classes, so
BadZoneName inherit from
Each exception has three additional member functions:
ice_idAs the name suggests, this member function returns the type ID of the exception. For example, if you call the
ice_idmember function of a
BadZoneNameexception defined in module
M, it returns the string
ice_idmember function is useful if you catch exceptions generically and want to produce a more meaningful diagnostic, for example:
If an exception is raised, this code prints the id of the actual exception (such as
::M::BadZoneName). For exception that are not defined in Slice,
ice_idreturns the full name of the C++ class.
ice_filereturns the file name provided to the second constructor of
ice_linereturns the line number provided to the second constructor of
ice_printThe default implementation of
ice_printprints the file name and line number (when available), and the type ID of the exception.
ice_stackTracefunction returns the full stack trace when the exception was constructed, or an empty string, depending on the value of the
This member function allows you to polymorphically clone an exception. For example:
ice_cloneis useful if you need to make a copy of an exception without knowing its precise run-time type. This allows you to remember the exception and throw it later by calling
ice_throwallows you to throw an exception without knowing its precise run-time type. It is implemented as:
You can call
ice_throwto throw an exception that you previously cloned with
Each exception has a default constructor. Members having a complex type, such as strings, sequences, and dictionaries, are initialized by their own default constructor. However, the default constructor performs no initialization for members having one of the simple built-in types boolean, integer, floating point, or enumeration. For such a member, it is not safe to assume that the member has a reasonable default value. This is especially true for enumerated types as the member's default value may be outside the legal range for the enumeration, in which case an exception will occur during marshaling unless the member is explicitly set to a legal value.
To ensure that data members of primitive types are initialized to reasonable values, you can declare default values in your Slice definition. The default constructor initializes each of these data members to its declared value. Optional data members are unset unless they declare default values.
An exception also has a second constructor that accepts one argument for each exception member. This constructor allows you to instantiate and initialize an exception in a single statement, instead of having to first instantiate the exception and then assign to its members. For each optional data member, its corresponding constructor parameter uses the same mapping as for operation parameters, allowing you to pass its initial value or
IceUtil::None to indicate an unset value.
For derived exceptions, the constructor accepts one argument for each base exception member, plus one argument for each derived exception member, in base-to-derived order.
Note that the generated exception classes contain other member functions that are not shown here. However, those member functions are internal to the C++ mapping and are not meant to be called by application code.
All user exceptions ultimately inherit from
Ice::UserException. In turn,
Ice::UserException inherits from
Ice::Exception (which is an alias for
Ice::Exception forms the root of the exception inheritance tree. Apart from the usual
ice_throw member functions, it contains the
ice_print member functions. The default implementation of
ice_print prints the file name and line number (when available) and the type ID of the exception. For example, calling
ice_print on a
BadTimeVal exception defined in module
To make printing more convenient,
operator<< is overloaded for
Ice::Exception, so you can also write:
This produces the same output because
ice_print internally. You can optionally provide your own
ice_print implementation using the
cpp::ice_print metadata directive.
For Ice run time exceptions,
ice_print also shows the file name and line number at which the exception was thrown.
C++ Default Constructors for Exceptions
Exceptions have a default constructor that default-constructs each data member. Members having a complex type, such as strings, sequences, and dictionaries, are initialized by their own default constructor. However, the default constructor performs no initialization for members having one of the simple built-in types boolean, integer, floating point, or enumeration. For such a member, it is not safe to assume that the member has a reasonable default value. This is especially true for enumerated types as the member's default value may be outside the legal range for the enumeration, in which case an exception will occur during marshaling unless the member is explicitly set to a legal value.
To ensure that data members of primitive types are initialized to reasonable values, you can declare default values in your Slice definition. The default constructor initializes each of these data members to its declared value.
Exceptions also have a second constructor that has one parameter for each data member. This allows you to construct and initialize a class instance in a single statement (instead of first having to construct the instance and then assign to its members). For derived exceptions, this constructor has one parameter for each of the base class's data members, plus one parameter for each of the derived class's data members, in base-to-derived order.
C++ Mapping for Run-Time Exceptions
The Ice run time throws run-time exceptions for a number of pre-defined error conditions. All run-time exceptions directly or indirectly derive from
Ice::LocalException (which, in turn, derives from
Ice::LocalException has the usual member functions:
ice_throw, and (inherited from
Recall the inheritance diagram for user and run-time exceptions. By catching exceptions at the appropriate point in the hierarchy, you can handle exceptions according to the category of error they indicate:
This is the root of the complete inheritance tree. Catching
Ice::Exceptioncatches both user and run-time exceptions. As shown earlier,
Ice::Exceptionis a typedef for
This is the root exception for all user exceptions. Catching
Ice::UserExceptioncatches all user exceptions (but not run-time exceptions).
This is the root exception for all run-time exceptions. Catching
Ice::LocalExceptioncatches all run-time exceptions (but not user exceptions).
This is the base exception for both operation-invocation and connection-establishment timeouts.
This exception is raised when the initial attempt to establish a connection to a server times out.
For example, a
ConnectTimeoutException can be handled as
You will probably have little need to catch run-time exceptions as their most-derived type and instead catch them as
LocalException; the fine-grained error handling offered by the remainder of the hierarchy is of interest mainly in the implementation of the Ice run time. Exceptions to this rule are the exceptions related to facet and object life cycles, which you may want to catch explicitly. These exceptions are
- User Exceptions
- Run-Time Exceptions
- C++98 Mapping for Identifiers
- C++98 Mapping for Modules
- C++98 Mapping for Built-In Types
- C++98 Mapping for Enumerations
- C++98 Mapping for Structures
- C++98 Mapping for Sequences
- C++98 Mapping for Dictionaries
- C++98 Mapping for Constants
- C++98 Mapping for Optional Values
- Object Life Cycle