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 
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