Classes
class	DynamicLibraryException
	This exception is thrown if an invalid value was specified for a property. More...

class	ExpressionException
	This exception is thrown if the macro ARMARX_CHECK_EXPRESSION is used. More...

class	FileIOException
	This exception is thrown when an error occurs during file access. More...

class	InvalidPropertyValueException
	This exception is thrown if an invalid value was specified for a property. More...

class	MissingRequiredPropertyException
	This exception is thrown if a property marked as required has not been specified. More...

class	PropertyInheritanceCycleException
	This exception is thrown if a property inheritance cycle has been encountered. More...

class	ProxyNotInitializedException
	This exception is thrown when accessing an uninitialized proxy. More...

class	UnmappedValueException
	This exception is thrown if a value specified for a property is not found in the property mapping PropertyMapper. More...

class	ValueRangeExceededException
	This exception is thrown if a value is out of a specified or allowed range. More...

class	NotImplementedYetException
	Throw this exception to indicate missing functionality. More...

Macros
#define	ARMARX_CHECK(expression) ARMARX_CHECK_EXPRESSION(expression)
	Shortcut for ARMARX_CHECK_EXPRESSION. More...

#define	ARMARX_CHECK_AND_THROW(expression, ExceptionType)
	This macro evaluates the expression and if it turns out to be false it will throw an exception of the given type. More...

#define	ARMARX_CHECK_BINARY_PREDICATE(lhs, rhs, cmp)
	This macro evaluates the expression (pred(lhs, rhs)) and if it turns out to be false it will throw an ExpressionException with the expression converted into a string. More...

#define	ARMARX_CHECK_CLOSE(lhs, rhs, prec)
	Check whether `lhs` is close to `rhs`, i.e. whether the absolute difference s not more than `prec`. More...

#define	ARMARX_CHECK_EQUAL(lhs, rhs) ARMARX_CHECK_BINARY_PREDICATE(lhs, rhs, ==)
	This macro evaluates whether lhs is equal (==) rhs and if it turns out to be false it will throw an ExpressionException with the expression converted into a string. More...

#define	ARMARX_CHECK_EXPRESSION(expression)
	This macro evaluates the expression and if it turns out to be false it will throw an ExpressionException with the expression converted into a string. More...

#define	ARMARX_CHECK_FINITE(number)
	This macro evaluates whether number is finite (not nan or inf) and if it turns out to be false it will throw an ExpressionException with the expression converted into a string. More...

#define	ARMARX_CHECK_FITS_SIZE(number, size)
	Check whether number is nonnegative (>= 0) and less than size. If it is not, throw an ExpressionException with the expression converted into a string. More...

#define	ARMARX_CHECK_GREATER(lhs, rhs) ARMARX_CHECK_BINARY_PREDICATE(lhs, rhs, >)
	This macro evaluates whether lhs is greater (>) than rhs and if it turns out to be false it will throw an ExpressionException with the expression converted into a string. More...

#define	ARMARX_CHECK_GREATER_EQUAL(lhs, rhs) ARMARX_CHECK_BINARY_PREDICATE(lhs, rhs, >=)
	This macro evaluates whether lhs is greater or equal (>=) rhs and if it turns out to be false it will throw an ExpressionException with the expression converted into a string. More...

#define	ARMARX_CHECK_IS_NULL(ptr)
	This macro evaluates whether ptr is null and if it turns out to be false it will throw an ExpressionException with the expression converted into a string. More...

#define	ARMARX_CHECK_LESS(lhs, rhs) ARMARX_CHECK_BINARY_PREDICATE(lhs, rhs, <)
	This macro evaluates whether lhs is less (<) than rhs and if it turns out to be false it will throw an ExpressionException with the expression converted into a string. More...

#define	ARMARX_CHECK_LESS_EQUAL(lhs, rhs) ARMARX_CHECK_BINARY_PREDICATE(lhs, rhs, <=)
	This macro evaluates whether lhs is less or equal (<=) rhs and if it turns out to be false it will throw an ExpressionException with the expression converted into a string. More...

#define	ARMARX_CHECK_NONNEGATIVE(number) ARMARX_CHECK_GREATER_EQUAL(number, 0)
	Check whether number is nonnegative (>= 0). If it is not, throw an ExpressionException with the expression converted into a string. More...

#define	ARMARX_CHECK_NOT_EQUAL(lhs, rhs) ARMARX_CHECK_BINARY_PREDICATE(lhs, rhs, !=)
	This macro evaluates whether lhs is inequal (!=) rhs and if it turns out to be false it will throw an ExpressionException with the expression converted into a string. More...

#define	ARMARX_CHECK_NOT_NULL(ptr)
	This macro evaluates whether ptr is not null and if it turns out to be false it will throw an ExpressionException with the expression converted into a string. More...

#define	ARMARX_CHECK_POSITIVE(number) ARMARX_CHECK_GREATER(number, 0)
	This macro evaluates whether number is positive (> 0) and if it turns out to be false it will throw an ExpressionException with the expression converted into a string. More...

Detailed Description

\page ExceptionsDoc ArmarX Exceptions

Different exception types are provided by the ArmarX framework

LocalExceptions: used for dealing with exceptions locally
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: Exceptions

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.

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.

Customized UserException

Customizing a UserException involves a brief slice definition. Here is the FrameRateNotSupportedException as an example:

// armarx::Exception
#include <core/Exception.ice>
module visionx
{
    exception FrameRateNotSupportedException extends armarx::UserException
    {
        float frameRate;
    };
};

To provide more detailed and verbose information about the error we implement a subclass of visionx::FrameRateNotSupportedException within the visionx::exceptions::user namespace:

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() {  };
    };
}

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:

throw visionx::exceptions::user::FrameRateNotSupportedException(myFrameRate);

To throw exception with custom error phrase use the following code:

visionx::exceptions::user::FrameRateNotSupportedException exception(0);
exception.reason = “No frame rate set”;
throw exception;

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:

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"; };
    };
}

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.

Macro Definition Documentation

◆ ARMARX_CHECK

#define ARMARX_CHECK ( expression ) ARMARX_CHECK_EXPRESSION(expression)

#include <ArmarXCore/core/exceptions/local/ExpressionException.h>

Shortcut for ARMARX_CHECK_EXPRESSION.

Definition at line 82 of file ExpressionException.h.

◆ ARMARX_CHECK_AND_THROW

#define ARMARX_CHECK_AND_THROW	(	expression,
		ExceptionType
	)

#include <ArmarXCore/core/exceptions/local/ExpressionException.h>

Value:

    do                                                                                             \
    {                                                                                              \
        if (!(expression))                                                                         \
            throw ExceptionType(#expression);                                                      \
    } while (0);

This macro evaluates the expression and if it turns out to be false it will throw an exception of the given type.

Definition at line 245 of file ExpressionException.h.

◆ ARMARX_CHECK_BINARY_PREDICATE

#define ARMARX_CHECK_BINARY_PREDICATE	(	lhs,
		rhs,
		cmp
	)

#include <ArmarXCore/core/exceptions/local/ExpressionException.h>

Value:

    if (!(lhs cmp rhs))                                                                            \
    throw ::armarx::exceptions::local::ExpressionException(#lhs " " #cmp " " #rhs)                 \
        << "\n(lhs = " << lhs << ", rhs = " << rhs << ")"                                          \
        << "\n(at " << __FILE__ << ':' << __LINE__ << " in " << __FUNCTION__ << "(...))\n"

This macro evaluates the expression (pred(lhs, rhs)) and if it turns out to be false it will throw an ExpressionException with the expression converted into a string.

Definition at line 90 of file ExpressionException.h.

◆ ARMARX_CHECK_CLOSE

#define ARMARX_CHECK_CLOSE	(	lhs,
		rhs,
		prec
	)

#include <ArmarXCore/core/exceptions/local/ExpressionException.h>

Value:

    if (!(std::abs(lhs - rhs) <= prec))                                                            \
    throw ::armarx::exceptions::local::ExpressionException("| " #lhs " - " #rhs "| <= " #prec)     \
        << "\n(lhs = " << lhs << ", rhs = " << rhs << ", prec = " << prec << ")"                   \
        << "\n(at " << __FILE__ << ':' << __LINE__ << " in " << __FUNCTION__ << "(...))\n"

Check whether lhs is close to rhs, i.e. whether the absolute difference s not more than prec.

Exceptions

an	ExpressionException with the expression converted into a string.

Definition at line 169 of file ExpressionException.h.

◆ ARMARX_CHECK_EQUAL

#define ARMARX_CHECK_EQUAL	(	lhs,
		rhs
	)	ARMARX_CHECK_BINARY_PREDICATE(lhs, rhs, ==)

#include <ArmarXCore/core/exceptions/local/ExpressionException.h>

This macro evaluates whether lhs is equal (==) rhs and if it turns out to be false it will throw an ExpressionException with the expression converted into a string.

Definition at line 130 of file ExpressionException.h.

◆ ARMARX_CHECK_EXPRESSION

#define ARMARX_CHECK_EXPRESSION ( expression )

#include <ArmarXCore/core/exceptions/local/ExpressionException.h>

Value:

    if (!(expression))                                                                             \
    throw ::armarx::exceptions::local::ExpressionException(#expression)                            \
        << "\n(at " << __FILE__ << ':' << __LINE__ << " in " << __FUNCTION__ << "(...))\n"

This macro evaluates the expression and if it turns out to be false it will throw an ExpressionException with the expression converted into a string.

Definition at line 73 of file ExpressionException.h.

◆ ARMARX_CHECK_FINITE

#define ARMARX_CHECK_FINITE ( number )

#include <ArmarXCore/core/exceptions/local/ExpressionException.h>

Value:

    if (!(std::isfinite(number)))                                                                  \
    throw ::armarx::exceptions::local::ExpressionException("std::isfinite(" #number ")")           \
        << "\n(number = " << number << ")"                                                         \
        << "\n(at " << __FILE__ << ':' << __LINE__ << " in " << __FUNCTION__ << "(...))\n"

This macro evaluates whether number is finite (not nan or inf) and if it turns out to be false it will throw an ExpressionException with the expression converted into a string.

Definition at line 182 of file ExpressionException.h.

◆ ARMARX_CHECK_FITS_SIZE

#define ARMARX_CHECK_FITS_SIZE	(	number,
		size
	)

#include <ArmarXCore/core/exceptions/local/ExpressionException.h>

Value:

ARMARX_CHECK_NONNEGATIVE(number); \

ARMARX_CHECK_LESS(size_t(number), size)

Check whether number is nonnegative (>= 0) and less than size. If it is not, throw an ExpressionException with the expression converted into a string.

Definition at line 159 of file ExpressionException.h.

◆ ARMARX_CHECK_GREATER

#define ARMARX_CHECK_GREATER	(	lhs,
		rhs
	)	ARMARX_CHECK_BINARY_PREDICATE(lhs, rhs, >)

#include <ArmarXCore/core/exceptions/local/ExpressionException.h>

This macro evaluates whether lhs is greater (>) than rhs and if it turns out to be false it will throw an ExpressionException with the expression converted into a string.

Definition at line 116 of file ExpressionException.h.

◆ ARMARX_CHECK_GREATER_EQUAL

#define ARMARX_CHECK_GREATER_EQUAL	(	lhs,
		rhs
	)	ARMARX_CHECK_BINARY_PREDICATE(lhs, rhs, >=)

#include <ArmarXCore/core/exceptions/local/ExpressionException.h>

This macro evaluates whether lhs is greater or equal (>=) rhs and if it turns out to be false it will throw an ExpressionException with the expression converted into a string.

Definition at line 123 of file ExpressionException.h.

◆ ARMARX_CHECK_IS_NULL

#define ARMARX_CHECK_IS_NULL ( ptr )

#include <ArmarXCore/core/exceptions/local/ExpressionException.h>

Value:

    if (ptr)                                                                                       \
    throw ::armarx::exceptions::local::ExpressionException(#ptr " == nullptr")                     \
        << "\n(ptr = " << ptr << ")"                                                               \
        << "\n(at " << __FILE__ << ':' << __LINE__ << " in " << __FUNCTION__ << "(...))\n"

This macro evaluates whether ptr is null and if it turns out to be false it will throw an ExpressionException with the expression converted into a string.

Definition at line 194 of file ExpressionException.h.

◆ ARMARX_CHECK_LESS

#define ARMARX_CHECK_LESS	(	lhs,
		rhs
	)	ARMARX_CHECK_BINARY_PREDICATE(lhs, rhs, <)

#include <ArmarXCore/core/exceptions/local/ExpressionException.h>

This macro evaluates whether lhs is less (<) than rhs and if it turns out to be false it will throw an ExpressionException with the expression converted into a string.

Definition at line 102 of file ExpressionException.h.

◆ ARMARX_CHECK_LESS_EQUAL

#define ARMARX_CHECK_LESS_EQUAL	(	lhs,
		rhs
	)	ARMARX_CHECK_BINARY_PREDICATE(lhs, rhs, <=)

#include <ArmarXCore/core/exceptions/local/ExpressionException.h>

This macro evaluates whether lhs is less or equal (<=) rhs and if it turns out to be false it will throw an ExpressionException with the expression converted into a string.

Definition at line 109 of file ExpressionException.h.

◆ ARMARX_CHECK_NONNEGATIVE

#define ARMARX_CHECK_NONNEGATIVE ( number ) ARMARX_CHECK_GREATER_EQUAL(number, 0)

#include <ArmarXCore/core/exceptions/local/ExpressionException.h>

Check whether number is nonnegative (>= 0). If it is not, throw an ExpressionException with the expression converted into a string.

Definition at line 152 of file ExpressionException.h.

◆ ARMARX_CHECK_NOT_EQUAL

#define ARMARX_CHECK_NOT_EQUAL	(	lhs,
		rhs
	)	ARMARX_CHECK_BINARY_PREDICATE(lhs, rhs, !=)

#include <ArmarXCore/core/exceptions/local/ExpressionException.h>

This macro evaluates whether lhs is inequal (!=) rhs and if it turns out to be false it will throw an ExpressionException with the expression converted into a string.

Definition at line 137 of file ExpressionException.h.

◆ ARMARX_CHECK_NOT_NULL

#define ARMARX_CHECK_NOT_NULL ( ptr )

#include <ArmarXCore/core/exceptions/local/ExpressionException.h>

Value:

    if (!ptr)                                                                                      \
    throw ::armarx::exceptions::local::ExpressionException(#ptr " != nullptr")                     \
        << "\n(ptr = nullptr)"                                                                     \
        << "\n(at " << __FILE__ << ':' << __LINE__ << " in " << __FUNCTION__ << "(...))\n"

This macro evaluates whether ptr is not null and if it turns out to be false it will throw an ExpressionException with the expression converted into a string.

Definition at line 206 of file ExpressionException.h.

◆ ARMARX_CHECK_POSITIVE

#define ARMARX_CHECK_POSITIVE ( number ) ARMARX_CHECK_GREATER(number, 0)

#include <ArmarXCore/core/exceptions/local/ExpressionException.h>

This macro evaluates whether number is positive (> 0) and if it turns out to be false it will throw an ExpressionException with the expression converted into a string.

Definition at line 145 of file ExpressionException.h.

Classes

Macros

Detailed Description

User vs Local Exceptions

Customized Exceptions

Customized UserException

Customized LocalException

Macro Definition Documentation

◆ ARMARX_CHECK

◆ ARMARX_CHECK_AND_THROW

◆ ARMARX_CHECK_BINARY_PREDICATE

◆ ARMARX_CHECK_CLOSE

◆ ARMARX_CHECK_EQUAL

◆ ARMARX_CHECK_EXPRESSION

◆ ARMARX_CHECK_FINITE

◆ ARMARX_CHECK_FITS_SIZE

◆ ARMARX_CHECK_GREATER

◆ ARMARX_CHECK_GREATER_EQUAL

◆ ARMARX_CHECK_IS_NULL

◆ ARMARX_CHECK_LESS

◆ ARMARX_CHECK_LESS_EQUAL

◆ ARMARX_CHECK_NONNEGATIVE

◆ ARMARX_CHECK_NOT_EQUAL

◆ ARMARX_CHECK_NOT_NULL

◆ ARMARX_CHECK_POSITIVE