errorevents.h

Go to the documentation of this file.

////////////////////////////////////////////////////////////////////////////////
///
/// \file
/// \author Gerald Fahrnholz
/// 
/// \defgroup GrpErrorEvents Using ErrorEvents
/// @{
/// \ingroup GrpTestUtils 
/// \brief
/// Class ErrorEvents is a storage class for error events and supports
/// filtering and verification functionalities.
///
/// \sa ErrorEvents.h (File documentation)
/// \sa TestToolBox::ErrorEvents (class documentation)
/// \sa GrpTestExtensionsForBoost (unit test using boost.Test and ErrorEvents)
/// 
////////////////////////////////////////////////////////////////////////////////

#pragma once

#include "TestToolBox/CommonSources/CommonDefinitions.h"
#include "TestToolBox/CommonSources/ObjectLock.h"
#include <map>
#include <list>
#include <set>

namespace TestToolBox
{

/// Severity classification for an error
enum DefaultSeverity
{
    S_UNKNOWN,
    S_INFO,
    S_WARNING,
    S_ERROR,
    S_FATAL_ERROR
};

/// Possible actions to execute
enum NotificationAction
{
    ACTION_NOT_SPECIFIED,
    ACTION_INFO,
    ACTION_ERROR_CONTINUE_TEST_CASE,
    ACTION_ERROR_BREAK_TEST_CASE,
    ACTION_IGNORE
};

/// Stores instructions how to react when an error occures
struct HandlingInstruction
{
///\cond

    HandlingInstruction()
        :
        m_notificationAction (ACTION_NOT_SPECIFIED)
        {}

    HandlingInstruction(NotificationAction in_notificationAction )
        :
        m_notificationAction (in_notificationAction)
        {}

    NotificationAction m_notificationAction;

    // possible extensions:
    // flag indicating whether the reaction shall be executed in the moment of
    // error creation (currently the reaction is executed when the stored errros
    // are reported)
    // flag to individually control generation of sync event
///\endcond

};


template<typename T_CATEGORY=long, typename T_ERROR_ID=long,typename T_SEVERITY=DefaultSeverity>
class ErrorEvents;

/// \brief This class  represents a single error event
template<typename T_CATEGORY, typename T_ERROR_ID=long,typename T_SEVERITY=DefaultSeverity>
class ErrorEvent
{
public:

///\cond do not document
    typedef T_CATEGORY Category;
    typedef T_ERROR_ID ErrorId;
    typedef T_SEVERITY Severity;
    typedef ErrorEvent<Category,ErrorId,Severity> ErrorEventType;
///\endcond

    /// Get a textual description of the error
    std::string GetDescription (void)
        {return m_description;}

    /// Report all child errors of this error
    void ReportChildError (int in_indentation);

private:

    /// \brief textual description for the error situation
    // Remark: it is assumed that all parameters are already contained
    // within the text.
    std::string m_description;

    /// \brief identifies the message/error text that describes the error
    /// the text may be subject for internationalization
    long m_errorMsgNum;

    /// unique identifier for the error (generated by the system under test)
    ErrorId  m_externalErrorId;

    /// \brief unique identifier for the error (generated by the test system at the moment
    /// when the error is detected/created)
    long  m_internalErrorId;

    /// topic area the error corresponds to
    Category m_category;

    /// error severity
    Severity m_severity;

    /// List of child error chains connected to this error
    typedef std::list<ErrorEventType> ErrorList;

    /// List of child errors, each of type \ref ErrorEvent
    ErrorList m_listOfChildErrors;

    friend class ErrorEvents<T_CATEGORY,T_ERROR_ID,T_SEVERITY>;

private:
///\cond

    ErrorEvent(){};

    explicit ErrorEvent (
        std::string const & in_rDescription,
        long                in_errMsgNum    = 0,
        ErrorId             in_extErrorId   = ErrorId(),
        long                in_intErrorId   = 0,
        Category            in_category     = Category(),
        Severity            in_severity     = Severity())
        :
        m_description     (in_rDescription),
        m_errorMsgNum     (in_errMsgNum),
        m_externalErrorId (in_extErrorId),
        m_internalErrorId (in_intErrorId),
        m_category        (in_category),
        m_severity        (in_severity)
    {}

    bool FindExtErrorId (
        ErrorId                       inExtErrorId,
        typename ErrorList::iterator& out_rIt,
        ErrorList*&                   out_rpErrorList);
///\endcond

}; // class ErrorEvent


//************************************************************************
//************************************************************************


/// \brief This class stores the error events as they occure during test execution.
/// For more info about usage see \ref GrpErrorEvents.
///
/// \nosubgrouping 
/// \sa ErrorEvents.h (File documentation)
/// \sa GrpTestExtensionsForBoost (unit test using boost.Test and ErrorEvents)
/// \sa GrpErrorEvents (Usage documentation)
///
template<typename T_CATEGORY, typename T_ERROR_ID,typename T_SEVERITY>
class ErrorEvents : public AutoCriticalSection
{
private:

    // Constructor.
    // Access/create instance via static method Get()
    explicit ErrorEvents (void);

public:
///\cond do not document

    typedef T_CATEGORY Category;
    typedef T_ERROR_ID ErrorId;
    typedef T_SEVERITY Severity;
    typedef ErrorEvent<Category,ErrorId,Severity> ErrorEventType;

    //*****  Construction and initialization  *****

    // Destructor
    ~ErrorEvents()
    {
        TRCF("ErrorEvents::~ErrorEvents");
        TRC(TL_DEBUG, "Destructor");
    }


    // Get the pointer to the only instance of this class
    static ErrorEvents* Get (void)
    {if (!s_pErrorEvents) s_pErrorEvents = new ErrorEvents;
     return s_pErrorEvents;}
    static ErrorEvents* s_pErrorEvents;

    static void Cleanup (void)
    {delete s_pErrorEvents; s_pErrorEvents = 0;}
///\endcond


    //---------------------------------------------------------------
    /// \name Configuration
    /// \{

    /// \brief Activates or deactivates a synchronization event
    /// for each received error message which is not filtered out.
    void SetErrorSync (
        bool in_syncOnError)
    {m_syncOnError = in_syncOnError;}

    /// \brief Activates or deactivates the immediate logging
    /// of an error as an informational message in the moment of
    /// error creation.
    void SetImmediateErrorLog (
        bool in_immediateLog)
    {m_immediateLog = in_immediateLog;}

    void DeleteStoredErrorsAfterReport (bool in_autoDelete)
    {m_deleteStoredErrorsAfterReport = in_autoDelete;}

    void SetNotificationActionForErrorMsgNum (
        long               in_errorMsgNum,
        NotificationAction in_notificationAction);

    void IgnoreErrorContainingTextPattern(
        std::string const & in_text);

    void ClearStoredTextPatterns (void);

    /// \}


    //---------------------------------------------------------------
    /// \name Methods to be used indirectly from production code
    /// \{

    void CreateError (
        std::string const & in_rDescription,
        long                in_errMsgNum    = 0,
        ErrorId             in_extErrorId   = ErrorId(),
        long                in_intErrorId   = 0,
        Category            in_category     = Category(),
        Severity            in_severity     = Severity());

    void AddAsChildError (
        ErrorId inExtErrorIdParent,
        ErrorId inExtErrorIdChild);
    /// \}

    //---------------------------------------------------------------
    /// \name Methods to be used from test scripts
    /// \{

    /// Report all stored errros as TestEvents
    void ReportStoredErrors (void);

    /// Delete all stored errros
    void DeleteStoredErrors (void);

    /// \brief Checks if the given id represents an error (i.e. id
    /// is different from 0). In case of error the error chain is written
    /// to test events and false is returned
    bool ErrorOk (
        T_ERROR_ID in_extErrorId);

    /// \}

private:
///\cond

    typedef std::list<ErrorEventType> ErrorList;
///\endcond

    /// List of errors of type \ref ErrorEvent
    ErrorList m_errorList;

///\cond

    bool m_immediateLog;
    bool m_syncOnError;
    bool m_deleteStoredErrorsAfterReport;

    HandlingInstruction m_defaultHandlingInstruction;

    // if a error message contains one of the following patterns
    // the error will be ignored
    std::set<std::string> m_errorTextPatternsToIgnore;

    std::map<long,HandlingInstruction> m_instructionForErrorMsgNum;
    std::map<Category,HandlingInstruction> m_instructionForCategory;
    std::map<Severity,HandlingInstruction> m_instructionForSeverity;

    friend class ErrorEvent<T_CATEGORY,T_ERROR_ID,T_SEVERITY>;
///\endcond

private:
///\cond do not document

    bool FindExtErrorId (
        ErrorId                       inExtErrorId,
        typename ErrorList::iterator& out_rIt,
        ErrorList*&                   out_rpErrorList);

    HandlingInstruction GetHandlingInstruction (
        typename ErrorEventType const & in_rErrorEvent);
///\endcond

}; // class ErrorEvents


//************************************************************************
//************************************************************************


}; // namespace TestToolBox


/// @} // end group GrpTestEvents

---