Exceptions.hpp

//
// Copyright (c) 2004-2015 Cloud Software Group, Inc.  All rights reserved.
//

#ifndef STREAMBASE_EXCEPTIONS_H
#define STREAMBASE_EXCEPTIONS_H

#include "StreamBase.hpp"
#include <string>
#include <exception>
#include <NMSTL/ptr.hpp>
#include "Errors.hpp"

SB_INTERNAL_FWD(XMLExceptionBuilder);
SB_INTERNAL_FWD(Errors);
SB_INTERNAL_FWD(StackTrace);

SB_NAMESPACE_BEGIN;

#include "ExceptionCodes.hpp"

#define SB_Throw(x) do { \
    x.file(__FILE__).line(__LINE__).function(__FUNCTION__).throwMyself(); \
    NMSTL_ASSERT_UNREACHABLE(); \
} while(0)

// ________________________________________________________________________
/// The base class for all StreamBaseExceptions.  Currently defined exceptions
/// include
///
/// - StreamBaseNoSuchEntityException: requested an entity which doesn't exist 
/// - StreamBaseBadXmlException: non-well-formed (i.e., unparseable) XML
/// - StreamBaseBadEntityException: semantically invalid entity description (e.g., box doesn't have a type)
/// - StreamBaseTypingException: typechecking failed
/// - StreamBaseIllegalArgumentException: miscellaneous illegal argument provided
///
/// An StreamBaseException should never be thrown directly; use the
/// Throw macro instead.
class StreamBaseException : public std::exception {
  public:
    /// Constructor.  
    ///
    /// @param code see ExceptionsCodes.hpp; use SB_NEW_MESSAGE_CODE if in doubt
    /// @param message the exception message
    /// @param error_type the class of error, for server runtime error handling
    /// @param type the type of the exception
    StreamBaseException(std::string code, std::string message,
                        sb_internal::Errors::Type error_type = sb_internal::Errors::UNKNOWNTYPE,
                        std::string type = "StreamBaseException");

    /// Constructor.  
    ///
    /// @param code see ExceptionsCodes.hpp; use SB_NEW_MESSAGE_CODE if in doubt
    /// @param message the exception message
    /// @param c an exception that is the "cause" of this exception
    /// @param error_type the class of error, for server runtime error handling
    /// @param type the type of the exception
    StreamBaseException(std::string code, std::string message, StreamBaseException& c,
                        sb_internal::Errors::Type error_type = sb_internal::Errors::UNKNOWNTYPE,
                        std::string type = "StreamBaseException");

#ifndef DOXYGEN_SKIP
    /// Create a StreamBaseException from a given xmlstring.  Xmlstring must start with
    /// the <exception> node as produced by asXmlString
    static StreamBaseException fromXmlString(const std::string &xmlstring, NMSTL::ptr<StreamBaseException> cause = NMSTL::ptr<StreamBaseException>());
#endif

    /// Destructor.
    virtual ~StreamBaseException() throw();

    /// Returns the message as a C string.  The string is owned by this
    /// object, so the pointer becomes invalid upon destruction of the
    /// StreamBaseException.
    virtual const char *what() const throw() { return _message.c_str(); }

#ifndef DOXYGEN_SKIP
    /// Returns the message.
    std::string getMessage() const { return _message; }
    std::string getSummary() const { return _summary.empty() ? _message : _summary; }

    /// Returns the source file line number, function in which the exception was
    /// thrown (or an empty string if unknown).
    std::string getFile() const { return _file; }
    unsigned int getLine() const { return _line; }
    std::string getFunction() const { return _function; }

    /// Returns the type of the exception (e.g., "StreamBaseException" or
    /// "StreamBaseNoSuchEntityException").
    std::string getType() const { return _type; }

    /// Returns the Errors::Type of the exception FATAL, NON_FATAL, MEM, etc..
    ///
    sb_internal::Errors::Type getErrorType() const { return _error_type; }

    /// Returns a description containing all known information about the message.
    std::string as_string() const;

    /// Returns a stack trace describing where the exception was
    /// thrown.  Uses external programs; may be very slow.
    std::string getStackTrace() const;

    // Find exception in chain that matches type. Return NULL
    StreamBaseException *findByType(const std::string type);
    // Return deepest exception in chain
    StreamBaseException& getDeepest();

    // Return exception chain as a string, for various contexts
    virtual std::string asXmlStringSingle() const;
    virtual std::string asXmlString() const;     // return chain as XML tree, for wire
    virtual std::string chainAsString() const;   // return chain, as printable string
    virtual std::string linkAsString() const;    // return single link of chain, as string
    virtual std::string getChainOfMessages() const; // chain all exception messages together

    std::string getCode() const { return _code; }
    StreamBaseException& getCause() const { return *_cause; }
    bool hasCause() const { return _cause; } // does this exception have a cause?

    const std::string getParam(const std::string name) const;
    // some convenience param getters
    const std::string getBoxParam() const;
    const std::string getBoxName() const;
    const std::string getFieldName() const;

    StreamBaseException& param(const std::string name, const std::string val);
    StreamBaseException& param(const std::string name, int val);
    StreamBaseException& code(std::string val);
    StreamBaseException& code(int val);
    StreamBaseException& file(const char *val);
    StreamBaseException& file(std::string val);
    StreamBaseException& line(int val);
    StreamBaseException& function(const char *val);
    StreamBaseException& function(std::string val);
    StreamBaseException& type(std::string val);
    StreamBaseException& message(std::string val);
    StreamBaseException& cause(const StreamBaseException& val);

    StreamBaseException& summary(std::string val);

    // some convenience param setters
    StreamBaseException& boxparam(std::string name);
    StreamBaseException& boxname(std::string name);
    StreamBaseException& fieldname(std::string name);

    virtual void throwMyself();
#endif

  protected:
    virtual std::string causeAsXmlString() const;  // create an xmlstring for the cause
  private:
    struct StackTraceHolder {
        NMSTL::ptr<sb_internal::StackTrace> _trace;
        StackTraceHolder(const NMSTL::ptr<sb_internal::StackTrace>&);
        StackTraceHolder(const StackTraceHolder&);
        StackTraceHolder& operator = (const StackTraceHolder&);
        ~StackTraceHolder();
    };

    std::string _message;
    std::string _file;
    unsigned int _line;
    std::string _function;
    std::string _type;
    StackTraceHolder _trace;
    sb_internal::Errors::Type _error_type;
    std::map<std::string,std::string> _params;
    std::string _code;
    std::string _summary;
    NMSTL::ptr<StreamBaseException> _cause;
    std::string _xmlNodeLocation;
    friend class sb_internal::XMLExceptionBuilder;
};

#ifdef DOXYGEN_SKIP
#define STREAMBASE_EXCEPTION_SUBTYPE(cl, parent, error_type) class cl : public parent {};
#else

#define STREAMBASE_EXCEPTION_SUBTYPE(cl, parent, error_type) \
class cl : public parent { \
  public: \
    cl(std::string code, std::string message, sb_internal::Errors::Type a_error_type=error_type, const char *type=#cl) : \
        parent(code, message, a_error_type, type ? type : #cl) {} \
    cl(std::string code, std::string message, StreamBaseException& c, sb_internal::Errors::Type a_error_type=error_type, const char *type=#cl) : \
        parent(code, message, c, a_error_type, type ? type : #cl) {} \
    void throwMyself() { throw(*this); }; \
}

#endif // DOXYGEN_SKIP

#define STREAMBASE_EXCEPTION_TYPE(cl, error_type) \
  STREAMBASE_EXCEPTION_SUBTYPE(cl, StreamBaseException, error_type)


/// Requested an entity which doesn't exist.
STREAMBASE_EXCEPTION_TYPE(StreamBaseNoSuchEntityException, sb_internal::Errors::NON_FATAL_ERROR);

/// Non-well-formed XML.
STREAMBASE_EXCEPTION_TYPE(StreamBaseBadXmlException, sb_internal::Errors::XML_ERROR);

/// Semantically invalid XML (e.g., box doesn't have a type).
STREAMBASE_EXCEPTION_TYPE(StreamBaseBadEntityException, sb_internal::Errors::NON_FATAL_ERROR);

/// Typechecking failed.
STREAMBASE_EXCEPTION_TYPE(StreamBaseTypingException, sb_internal::Errors::TYPECHECK_ERROR);

/// Miscellaneous illegal argument.
STREAMBASE_EXCEPTION_TYPE(StreamBaseIllegalArgumentException, sb_internal::Errors::XMLRPC_ERROR);

/// A feature is not implemented.
STREAMBASE_EXCEPTION_TYPE(StreamBaseNotImplementedException, sb_internal::Errors::NON_FATAL_ERROR);

/// A feature is not supported.
STREAMBASE_EXCEPTION_TYPE(StreamBaseNotSupportedException, sb_internal::Errors::NON_FATAL_ERROR);

/// A network (TCP/IP) error was encountered.
STREAMBASE_EXCEPTION_TYPE(StreamBaseNetworkException, sb_internal::Errors::XMLRPC_ERROR);

/// A network timeout error was encountered.
STREAMBASE_EXCEPTION_TYPE(StreamBaseTimeoutException, sb_internal::Errors::NETWORK_ERROR);

/// A dequeued result was not available in the time allowed
STREAMBASE_EXCEPTION_TYPE(StreamBaseDequeueTimeoutException, sb_internal::Errors::NETWORK_ERROR);

/// Illegal Argument 
STREAMBASE_EXCEPTION_TYPE(IllegalArgumentException, sb_internal::Errors::NON_FATAL_ERROR);

/// Null value encountered
STREAMBASE_EXCEPTION_TYPE(NullValueException, sb_internal::Errors::NON_FATAL_ERROR);

/// An XML/RPC error has occurred.
class StreamBaseXmlRpcFault : public StreamBaseException { 
  public: 
    StreamBaseXmlRpcFault(int fault_code, std::string fault_string);
    StreamBaseXmlRpcFault(std::string code, std::string message,
                          sb_internal::Errors::Type error_type = sb_internal::Errors::UNKNOWNTYPE,
                          std::string type = "StreamBaseXmlRpcFault");

    StreamBaseXmlRpcFault(std::string code, std::string message, StreamBaseException& c,
                          sb_internal::Errors::Type error_type = sb_internal::Errors::UNKNOWNTYPE,
                          std::string type = "StreamBaseXmlRpcFault");

#ifndef DOXYGEN_SKIP
    //const StreamBaseXmlRpcFault& throwMyself() { throw(*this); return *this; }
    void throwMyself() { throw(*this); }
#endif
};

/// An Exception which contains a list of cause exceptions
class StreamBaseListException : public StreamBaseException { 
  private:
    std::vector<StreamBaseException> causes;
  protected:
    virtual std::string causeAsXmlString() const;  // create an xmlstring for the cause
  public: 
    StreamBaseListException(std::string code, std::string message, const std::vector<StreamBaseException>& causes,
                            sb_internal::Errors::Type error_type = sb_internal::Errors::UNKNOWNTYPE,
                            std::string type = "StreamBaseListException");

    virtual ~StreamBaseListException() throw();

    const std::vector<StreamBaseException> &getCauses() const { return causes; }
    std::string getChainOfMessages() const; // chain all exception messages together
    std::string chainAsString() const;

#ifndef DOXYGEN_SKIP
    void throwMyself() { throw(*this); }
#endif
};
SB_NAMESPACE_END;
#endif