Exception.h

Go to the documentation of this file.

/*
* This file is part of ArmarX.
*
* Copyright (C) 2011-2016, High Performance Humanoid Technologies (H2T), Karlsruhe Institute of Technology (KIT), all rights reserved.
*
* ArmarX is free software; you can redistribute it and/or modify
* it under the terms of the GNU General Public License version 2 as
* published by the Free Software Foundation.
*
* ArmarX is distributed in the hope that it will be useful, but
* WITHOUT ANY WARRANTY; without even the implied warranty of
* MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
* GNU General Public License for more details.
*
* You should have received a copy of the GNU General Public License
* along with this program. If not, see <http://www.gnu.org/licenses/>.
*
* @package    ArmarXCore::core
* @author     Jan Issac (jan dot issac at gmx dot de)
* @author     Kai Welke (welke at kit dot edu)
* @date       2011
* @copyright  http://www.gnu.org/licenses/gpl-2.0.txt
*             GNU General Public License
*/
 
#pragma once
 
#include <ArmarXCore/core/exceptions/LocalException.h>
#include <ArmarXCore/interface/core/UserException.h>
 
/**
    \page ExceptionsDoc ArmarX Exceptions
Different exception types are provided by the ArmarX framework
 
\li LocalExceptions: used for dealing with exceptions locally
\li UserExceptions: exceptions get propagated through Ice to other processes
 
Both can be thought as an extension to the Ice exceptions.
The basic difference is that ArmarX exceptions declare a publicly accessible 'reason'
string member to provide more details on the error.
It is also possible to generate a backtrace for tracking the origin of its occurence.
 
The API documentation can be found here: \ref Exceptions
 
\section exceptions-difference User vs Local Exceptions
 
Splitting the exceptions into these two groups comes along with the Ice concept.
Generally an exception can be thrown at any point in time.
To handle exceptions thrown during a remote procedure call (via Ice) properly,
the exception type and its members have to be streamed to the RPC invoker.
On the invoker side a new instance of that specific exception type is instantiated along
with the transmitted member values.
The exception is then thrown again.
This procedure is carried out by Ice, if the thrown exception is of ype Ice::UserException
or armarx::UserException.
Otherwise, the exception type remains unknown and is replaces with Ice::UnknownLocalException,
since no information about the exception are streamed.
 
\section exceptions-custom Customized Exceptions
 
While working with the ArmarX Framework the exceptions should be defined within
the namespaces armarx::exceptions::local and armarx::exceptions::user, respectively.
Similarly if you are working on a different domain such as VisionX the namespaces
should be visionx::exceptions::local or armarx::exceptions::user depending what kind
of exception you are implementing.
 
\subsection exceptions-custom-user Customized UserException
 
Customizing a UserException involves a brief slice definition.
Here is the FrameRateNotSupportedException as an example:
\code
// armarx::Exception
#include <core/Exception.ice>
module visionx
{
    exception FrameRateNotSupportedException extends armarx::UserException
    {
        float frameRate;
    };
};
\endcode
 
To provide more detailed and verbose information about the error we implement
a subclass of visionx::FrameRateNotSupportedException within the
visionx::exceptions::user namespace:
 
\code
namespace visionx::exceptions::user
{
    class FrameRateNotSupportedException: public visionx::FrameRateNotSupportedException
    {
    public:
        FrameRateNotSupportedException(float frameRate)
            :visionx::FrameRateNotSupportedException("", frameRate)
        {
            std::stringstream ss;
            ss << "Frame rate not supported: " << frameRate;
            reason = ss.str();
        }
        ~FrameRateNotSupportedException() throw() {  };
    };
}
\endcode
 
By doing this we only have to pass the frameRate and the error reason phrase
is generated right before throwing the exception without any further ado.
Of course, it possible to create the exception and then specify a custom error message
in reason before throwing.
 
As you may have noticed we have to implement the destructor as well.
Otherwise, a default destructor without the throw() specification is defined
which in turn weakens the destructor declaration in the super-class generated by Ice
(here: visionx::FrameRateNotSupportedException).
 
An exception is thrown the following way:
\code
throw  visionx::exceptions::user::FrameRateNotSupportedException(myFrameRate);
\endcode
 
To throw exception with custom error phrase use the following code:
\code
visionx::exceptions::user::FrameRateNotSupportedException exception(0);
exception.reason = “No frame rate set”;
throw exception;
\endcode
 
\subsection exceptions-custom-local Customized LocalException
 
Since armarx::LocalException is not marshaled by Ice, we only need to implement
the desired exception that inherits from armarx::LocalException as done in the following example:
\code
    namespace armarx::exceptions::local
    {
        class MissingRequiredPropertyException: public armarx::LocalException
        {
        public:
            std::string propertyName;
            MissingRequiredPropertyException(std::string propertyName):
                armarx::LocalException(0, 0),
                 propertyName(propertyName)
            {
                reason = " Missing required property <" + propertyName + ">";
            };
            ~MissingRequiredPropertyException() throw() { };
            virtual std::string ice_id() const { return "armarx::exceptions::local::MissingRequiredPropertyException"; };
        };
    }
\endcode
 
Note that the ice_id(...) function should be overridden to provide the real exception name.
The armarx::LocalException differs from the armarx::UserException in one additional way.
In armarx::LocalException the reason string will be printed along with a backtrace
managed by Ice while armarx::UserException will provide only the backtrace information
and the reason string has to printed manually.
 
Throwing a LocalException is analogous to throwing UserExcepotions as stated above.
 
\defgroup Exceptions
\ingroup core-utility
*/
namespace armarx
{
 
}