Exception.h
Go to the documentation of this file.
1
/*
2
* This file is part of ArmarX.
3
*
4
* Copyright (C) 2011-2016, High Performance Humanoid Technologies (H2T), Karlsruhe Institute of Technology (KIT), all rights reserved.
5
*
6
* ArmarX is free software; you can redistribute it and/or modify
7
* it under the terms of the GNU General Public License version 2 as
8
* published by the Free Software Foundation.
9
*
10
* ArmarX is distributed in the hope that it will be useful, but
11
* WITHOUT ANY WARRANTY; without even the implied warranty of
12
* MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
13
* GNU General Public License for more details.
14
*
15
* You should have received a copy of the GNU General Public License
16
* along with this program. If not, see <http://www.gnu.org/licenses/>.
17
*
18
* @package ArmarXCore::core
19
* @author Jan Issac (jan dot issac at gmx dot de)
20
* @author Kai Welke (welke at kit dot edu)
21
* @date 2011
22
* @copyright http://www.gnu.org/licenses/gpl-2.0.txt
23
* GNU General Public License
24
*/
25
26
#pragma once
27
28
#include <
ArmarXCore/core/exceptions/LocalException.h
>
29
#include <ArmarXCore/interface/core/UserException.h>
30
31
/**
32
\page ExceptionsDoc ArmarX Exceptions
33
Different exception types are provided by the ArmarX framework
34
35
\li LocalExceptions: used for dealing with exceptions locally
36
\li UserExceptions: exceptions get propagated through Ice to other processes
37
38
Both can be thought as an extension to the Ice exceptions.
39
The basic difference is that ArmarX exceptions declare a publicly accessible 'reason'
40
string member to provide more details on the error.
41
It is also possible to generate a backtrace for tracking the origin of its occurence.
42
43
The API documentation can be found here: \ref Exceptions
44
45
\section exceptions-difference User vs Local Exceptions
46
47
Splitting the exceptions into these two groups comes along with the Ice concept.
48
Generally an exception can be thrown at any point in time.
49
To handle exceptions thrown during a remote procedure call (via Ice) properly,
50
the exception type and its members have to be streamed to the RPC invoker.
51
On the invoker side a new instance of that specific exception type is instantiated along
52
with the transmitted member values.
53
The exception is then thrown again.
54
This procedure is carried out by Ice, if the thrown exception is of ype Ice::UserException
55
or armarx::UserException.
56
Otherwise, the exception type remains unknown and is replaces with Ice::UnknownLocalException,
57
since no information about the exception are streamed.
58
59
\section exceptions-custom Customized Exceptions
60
61
While working with the ArmarX Framework the exceptions should be defined within
62
the namespaces armarx::exceptions::local and armarx::exceptions::user, respectively.
63
Similarly if you are working on a different domain such as VisionX the namespaces
64
should be visionx::exceptions::local or armarx::exceptions::user depending what kind
65
of exception you are implementing.
66
67
\subsection exceptions-custom-user Customized UserException
68
69
Customizing a UserException involves a brief slice definition.
70
Here is the FrameRateNotSupportedException as an example:
71
\code
72
// armarx::Exception
73
#include <core/Exception.ice>
74
module visionx
75
{
76
exception FrameRateNotSupportedException extends armarx::UserException
77
{
78
float frameRate;
79
};
80
};
81
\endcode
82
83
To provide more detailed and verbose information about the error we implement
84
a subclass of visionx::FrameRateNotSupportedException within the
85
visionx::exceptions::user namespace:
86
87
\code
88
namespace visionx::exceptions::user
89
{
90
class FrameRateNotSupportedException: public visionx::FrameRateNotSupportedException
91
{
92
public:
93
FrameRateNotSupportedException(float frameRate)
94
:visionx::FrameRateNotSupportedException("", frameRate)
95
{
96
std::stringstream ss;
97
ss << "Frame rate not supported: " << frameRate;
98
reason = ss.str();
99
}
100
~FrameRateNotSupportedException() throw() { };
101
};
102
}
103
\endcode
104
105
By doing this we only have to pass the frameRate and the error reason phrase
106
is generated right before throwing the exception without any further ado.
107
Of course, it possible to create the exception and then specify a custom error message
108
in reason before throwing.
109
110
As you may have noticed we have to implement the destructor as well.
111
Otherwise, a default destructor without the throw() specification is defined
112
which in turn weakens the destructor declaration in the super-class generated by Ice
113
(here: visionx::FrameRateNotSupportedException).
114
115
An exception is thrown the following way:
116
\code
117
throw visionx::exceptions::user::FrameRateNotSupportedException(myFrameRate);
118
\endcode
119
120
To throw exception with custom error phrase use the following code:
121
\code
122
visionx::exceptions::user::FrameRateNotSupportedException exception(0);
123
exception.reason = “No frame rate set”;
124
throw exception;
125
\endcode
126
127
\subsection exceptions-custom-local Customized LocalException
128
129
Since armarx::LocalException is not marshaled by Ice, we only need to implement
130
the desired exception that inherits from armarx::LocalException as done in the following example:
131
\code
132
namespace armarx::exceptions::local
133
{
134
class MissingRequiredPropertyException: public armarx::LocalException
135
{
136
public:
137
std::string propertyName;
138
MissingRequiredPropertyException(std::string propertyName):
139
armarx::LocalException(0, 0),
140
propertyName(propertyName)
141
{
142
reason = " Missing required property <" + propertyName + ">";
143
};
144
~MissingRequiredPropertyException() throw() { };
145
virtual std::string ice_id() const { return "armarx::exceptions::local::MissingRequiredPropertyException"; };
146
};
147
}
148
\endcode
149
150
Note that the ice_id(...) function should be overridden to provide the real exception name.
151
The armarx::LocalException differs from the armarx::UserException in one additional way.
152
In armarx::LocalException the reason string will be printed along with a backtrace
153
managed by Ice while armarx::UserException will provide only the backtrace information
154
and the reason string has to printed manually.
155
156
Throwing a LocalException is analogous to throwing UserExcepotions as stated above.
157
158
\defgroup Exceptions
159
\ingroup core-utility
160
*/
161
namespace
armarx
162
{
163
164
}
165
166
LocalException.h
armarx
This file offers overloads of toIce() and fromIce() functions for STL container types.
Definition:
ArmarXTimeserver.cpp:28
ArmarXCore
core
exceptions
Exception.h
Generated on Sat Oct 5 2024 09:13:54 for armarx_documentation by
1.8.17