c++_api/inc/opals/Exception.hpp

#pragma once
 
//opals
#include "opals/config.hpp"
 
//stl
#include <stdexcept>
 
// Exception guidelines for opals programmers:
//
// Exception classes allow applications to react programmatically on specific error types (without analysing the error message).
// The organisation of exception classes into a hierarchy allows applications to react on groups of more specific errors.
//
//  It can be assumed that most errors are caused by incorrect or missing input parameters. So there should be a fine
//  granulation of classes concerning those errors. All exception classes must be derived from opals::Exceptions::Base,
//  either directly or indirectly. Exceptions are only throw if the program cannot continue safely. For other "problematic" 
//  situations use a warning log message:
//    OPALS_LOG(opals::LogLevel::warning) << message
//
//  Opals exception classes provide an error code, which will be the return code of opals executables.
//  So if you add a new exception class, also add a new opals::ErrorCode enumerator!
//  To avoid different messages for the same error, offer as few text input as possible. Which means that the exception
//  itself should set its text in the constructor (see e.g. opals::Exceptions::FileExistence).
//
//  For errors that can only appear if opals module programmers don't use the opals framework correctly, it is
//  appropriate to simply throw opals::Exception::Internal.  
//  Since the opals framework translates any exceptions to opals exceptions, it 
//  is necessary to add new opals exceptions to the OPALS_EXCEPTIONS preprocessor list in ExceptionProxy.hpp
//  
//  Task list when adding a new exception class:
//  Is there already an exception describing my error? If not, then define a new exception class:
//    1) If the new exception describes an existing exception more precisely, then derive from that existing class.
//       Otherwise, derive from opals::Exceptions::Base
//    2) Add a corresponding enumerator to the enumeration opals::ErrorCode
//    3) In the constructor, specify a textual description of the error as a prefix to the constructor argument (const char*)
//    4) Add the new exception class to the preprocessor list OPALS_EXCEPTIONS in ExceptionProxy.hpp
 
#ifdef _MSC_VER
#  define _GLIBCXX_USE_NOEXCEPT
 
// disable C4275 warning non dll-interface class  for opals::Exceptions::Base
#  pragma warning( push )
#  pragma warning( disable : 4275)
#endif
 
namespace opals {
 
  /// error codes that identify an Exception
  /** opals executables return these values (instead of exceptions).
      To be used as return value of the main function. Hence unscoped, with implicit conversion to int.*/
  namespace ErrorCode
  {
    enum Enum
    {
      ok = 0,                ///< no error    
                                    
      unknown,               ///< unknown error number, which may appear if exceptions are throw inside used library
      internally,            ///< programming error which appears if the opals framework wasn't used correctly;
      
      parameter = 1000,      ///< a general parameter error (usually comes from boost::program_options)
      unknownParameter,      ///< thrown if an unknown parameter was set as a command line parameter
      ambiguousParameter,    ///< thrown if there are ambiguities amoung several possible parameter names
      invalidSyntax,         ///< thrown if the command line parameters contain an invalid syntax
      paramQueriedBeforeSet, ///< thrown if a parameter value is queried although the value has not been set (neither internally, nor externally)
      fileExistence,         ///< thrown if the provided filename doesn't exist.
      fileReadAccess,        ///< thrown if the provided file cannot be accessed for reading.
      fileWriteAccess,       ///< thrown if the provided file cannot be accessed for writing.
      aliasColumnName,       ///< thrown if an alias is set for unknown column name (only predefined column name are allowed)
      aliasAlreadyDefined,   ///< thrown if an alias is used multiple times
      gdalReadAccess,        ///< thrown if the provided file cannot be opened as a GDAL raster (GDALOpen returns NULL)
      unknownStripName,      ///< thrown if a strip name was provided that is unknown
      xmlParsing,            ///< thrown if the provided xml file could not be parsed
      fileFormatDefinition,  ///< thrown if an error in the OPALS file format definition was detected.
      unknownAttribute,      ///< thrown a specified attribute doesn't exists in the corresponding odm.
      odmReadAccess,         ///< thrown if the provided file cannot be opened as an ODM 
      differentCRS,          ///< thrown if input data set have different coordinate reference systems  
      missingCRS,            ///< thrown if a module requires a coordinate reference systems to be set
                                    
      fileCorrupt = 2000,    ///< general file corruption error: thrown if a file to be used is not interpretable
      logFileCorrupt,        ///< thrown if an existing log file shall be used, but the correct position to proceed writing cannot be determined
      paramFileCorrupt,      ///< thrown if an existing parameter file shall be appended to, but the correct position to proceed writing cannot be determined, resulting in a probably ill-formed XML-file
                                    
      licence = 3000,        ///< general licence error
 
      python = 4000,         ///< An error occurred during a call to a Python interpreter. Reflects Python's built-in class exceptions.BaseException
      /*
        The hierarchy of Python's built-in Exception classes cannot be represented by only 3 digits.
        Thus, we do not represent the hierarchy in the error codes.
        To avoid future changes of error codes due to changes of Python's exception hierarchy, we separate the codes by 10.
        Note: The following hierarchy is the one of Python 2.7. Since then, exception have been both introduced and removed. Most notably, StandardError has been removed.
        Python exception class                         | error code
          -----------------------------------------------------------
        BaseException                                   | 4000
          +-- SystemExit                                 | 4010
          +-- KeyboardInterrupt                          | 4020
          +-- GeneratorExit                              | 4030
          +-- Exception                                  | 4040
              +-- StopIteration                         | 4050
              +-- StandardError                         | 4060
              |    +-- BufferError                      | 4070
              |    +-- ArithmeticError                  | 4080
              |    |    +-- FloatingPointError          | 4090
              |    |    +-- OverflowError               | 4100
              |    |    +-- ZeroDivisionError           | 4110
              |    +-- AssertionError                   | 4120
              |    +-- AttributeError                   | 4130
              |    +-- EnvironmentError                 | 4140
              |    |    +-- IOError                     | 4150
              |    |    +-- OSError                     | 4160
              |    |         +-- WindowsError (Windows) | 4170
              |    |         +-- VMSError (VMS)         | 4180
              |    +-- EOFError                         | 4190
              |    +-- ImportError                      | 4200
              |    +-- LookupError                      | 4210
              |    |    +-- IndexError                  | 4220
              |    |    +-- KeyError                    | 4230
              |    +-- MemoryError                      | 4240
              |    +-- NameError                        | 4250
              |    |    +-- UnboundLocalError           | 4260
              |    +-- ReferenceError                   | 4270
              |    +-- RuntimeError                     | 4280
              |    |    +-- NotImplementedError         | 4290
              |    +-- SyntaxError                      | 4300
              |    |    +-- IndentationError            | 4310
              |    |         +-- TabError               | 4320
              |    +-- SystemError                      | 4330
              |    +-- TypeError                        | 4340
              |    +-- ValueError                       | 4350
              |         +-- UnicodeError                | 4360
              |              +-- UnicodeDecodeError     | 4370
              |              +-- UnicodeEncodeError     | 4380
              |              +-- UnicodeTranslateError  | 4390
              +-- Warning                               | 4400
                    +-- DeprecationWarning               | 4410
                    +-- PendingDeprecationWarning        | 4420
                    +-- RuntimeWarning                   | 4430
                    +-- SyntaxWarning                    | 4440
                    +-- UserWarning                      | 4450
                    +-- FutureWarning                    | 4460
              +-- ImportWarning                          | 4470
              +-- UnicodeWarning                         | 4480
              +-- BytesWarning                           | 4490
              */
      pythonException       = 4040, ///< Reflects Python's built-in class exceptions.Exception
                                    /**< All of Python's built-in, non-system-exiting exceptions are derived from that class. */
      pythonArithmeticError = 4080, ///< Reflects Python's built-in class exceptions.ArithmeticError
                                    /**< Python's base class for those built-in exceptions that are raised for various arithmetic errors. */
      pythonNameError       = 4250, ///< Reflects Python's built-in class exceptions.NameError
                                    /**< Raised by Python when a local or global name is not found. */
      pythonSyntaxError     = 4300, ///< Reflects Python's built-in class exceptions.SyntaxError
                                    /**< Raised by Python when the parser encounters a syntax error. */
      pythonTypeError       = 4340, ///< Reflects Python's built-in class exceptions.TypeError
                                    /**< Raised by Python when an operation or function is applied to an object of inappropriate type. */
      pythonValueError      = 4350, ///< Reflects Python's built-in class exceptions.ValueError
                                    /**< Raised by Python when a built-in operation or function receives an argument that has the right type but an inappropriate value. */
 
      userInterrupt = 5000,         ///< thrown by user programmer (in C++ or Python) to stop processing
 
      riwaveError = 6000            ///< thrown if an error is reported by the RiWave lib
    };
  }
 
  /// \namespace opals::Exceptions
  /// \brief The namespace containing all exception types that may be thrown from within namespace opals
  /** All exceptions derive from Exceptions::Base (except for Base itself, of course). */
  namespace Exceptions
  {
  
    /// The base class of all exceptions thrown by opals.
    class OPALS_API Base : public ::std::runtime_error
    {
    public:
      Base();
      Base(const char *errorMessage, ErrorCode::Enum errorCode = ErrorCode::unknown);
      Base(const Base &ref);
      virtual ~Base() _GLIBCXX_USE_NOEXCEPT;
 
      /// returns the error code
      ErrorCode::Enum errorCode()     const;
      /// returns the actual error message
      const char*     errorMessage() const;
 
      /// returns the full error message including the error code: "Error XXXX: Text..."
      const char*   what() const _GLIBCXX_USE_NOEXCEPT;
  
    protected:
      ErrorCode::Enum e_Code;
      unsigned  u_MessagePos;
 
      friend class ExceptionCloner;
    };
 
    /// \copydoc ErrorCode::unknown
    class OPALS_API Unknown : public Base {
    public:
      Unknown(const char *errorMessage);
    };
 
    /// \copydoc ErrorCode::internally
    class OPALS_API Internal : public Base {
    public:
      Internal(const char *errorMessage);
    };
 
    /// \copydoc ErrorCode::parameter
    class OPALS_API Parameter : public Base {
    public:
      Parameter(const char *errorMessage);
    protected:
      Parameter(const char *errorMessage, ErrorCode::Enum code);   ///< Constructor for child classes
    };
  
    /// \copydoc ErrorCode::unknownParameter
    class OPALS_API UnknownParameter : public Parameter {
    public:
      UnknownParameter(const char *errorMessage);
    };
 
    /// \copydoc ErrorCode::ambiguousParameter
    class OPALS_API AmbiguousParameter : public Parameter {
    public:
      AmbiguousParameter(const char *errorMessage);
    };
 
    /// \copydoc ErrorCode::invalidSyntax
    class OPALS_API InvalidSyntax : public Parameter {
    public:
      InvalidSyntax(const char *errorMessage);
    };
 
    /// \copydoc ErrorCode::paramQueriedBeforeSet
    class OPALS_API ParamQueriedBeforeSet : public Parameter {
    public:
      ParamQueriedBeforeSet(const char *errorMessage);
    };
 
    /// \copydoc ErrorCode::fileExistence
    class OPALS_API FileExistence : public Parameter {
    public:
      FileExistence(const char *filename);
    };
 
    /// \copydoc ErrorCode::fileReadAccess
    class OPALS_API FileReadAccess : public Parameter {
    public:
      FileReadAccess(const char *filename);
    };
 
    /// \copydoc ErrorCode::fileWriteAccess
    class OPALS_API FileWriteAccess : public Parameter {
    public:
      FileWriteAccess(const char *filename);
    };
 
    /// \copydoc ErrorCode::odmReadAccess
    class OPALS_API ODMReadAccess : public Parameter {
    public:
      ODMReadAccess(const char *filename);
      ODMReadAccess(const char *filename, const char *reason);
    };
 
    /// \copydoc ErrorCode::gdalReadAccess
    class OPALS_API GDALReadAccess : public Parameter {
    public:
      GDALReadAccess(const char *filename);
    };
  
    /// \copydoc ErrorCode::aliasColumnName
    class OPALS_API AliasColumnName : public Parameter {
    public:
      AliasColumnName(const char *colname);
    };
 
    /// \copydoc ErrorCode::aliasAlreadyDefined
    class OPALS_API AliasAlreadyDefined : public Parameter {
    public:
      AliasAlreadyDefined(const char *alias);
    };
 
    /// \copydoc ErrorCode::unknownStripName
    class OPALS_API UnknownStripName : public Parameter {
    public:
      UnknownStripName(const char *stripName);
    };
 
    /// \copydoc ErrorCode::xmlParsing
    class OPALS_API XMLParsing : public Parameter {
    public:
      XMLParsing(const char* xmlParser, const char *message);
      XMLParsing(const char *message);
    };
 
    /// \copydoc ErrorCode::fileFormatDefinition
    class OPALS_API OpalsFormatDefinition : public Parameter {
    public:
      OpalsFormatDefinition(const char *message);
    };
 
    /// \copydoc ErrorCode::unknownAttribute
    class OPALS_API UnknownAttribute : public Parameter {
    public:
      UnknownAttribute(const char *attribute);
      UnknownAttribute(unsigned count, const char **attributes);
      UnknownAttribute(const char *filename, unsigned count, const char **attributes);
    };
 
    /// \copydoc ErrorCode::differentCRS
    class OPALS_API DifferentCRS : public Parameter {
    public:
      DifferentCRS(unsigned count, const char **dataSets);
    };
 
    /// \copydoc ErrorCode::missingCRS
    class OPALS_API MissingCRS : public Parameter {
    public:
      MissingCRS();
      MissingCRS(const char *errorMessage);
    };
 
    /// \copydoc ErrorCode::fileCorrupt
    class OPALS_API FileCorrupt : public Base {
    public:
      FileCorrupt(const char *errorMessage);
    protected:
      FileCorrupt(const char *errorMessage, ErrorCode::Enum code);   ///< Constructor for child classes
    };
 
    /// \copydoc ErrorCode::logFileCorrupt
    class OPALS_API LogFileCorrupt : public FileCorrupt {
    public:
      LogFileCorrupt(const char *filename);
    };
 
    /// \copydoc ErrorCode::paramFileCorrupt
    class OPALS_API ParamFileCorrupt : public FileCorrupt {
    public:
      ParamFileCorrupt(const char *filename, const char *message = 0 );
    };
 
    /// \copydoc ErrorCode::licence
    class OPALS_API Licence : public Base {
    public:
      Licence(const char *errorMessage);
    protected:
      Licence(const char *errorMessage, ErrorCode::Enum code);        ///< Constructor for child classes
    };
 
    /// \copydoc ErrorCode::python
    class OPALS_API Python : public Base {
    public:
      Python(const char *errorMessage);
    protected:
      Python(const char *errorMessage, ErrorCode::Enum code);        ///< Constructor for child classes
    };
 
    /// \copydoc ErrorCode::pythonException
    class OPALS_API PythonException : public Python {
    public:
      PythonException(const char *errorMessage);
    protected:
      PythonException(const char *errorMessage, ErrorCode::Enum code);
    };
 
    // Python 3 does not define StandardError, so we derive all Python* exceptions directly from PythonException.
    /// \copydoc ErrorCode::pythonArithmeticError
    class OPALS_API PythonArithmeticError : public PythonException {
    public:
      PythonArithmeticError(const char *errorMessage);
    protected:
      PythonArithmeticError(const char *errorMessage, ErrorCode::Enum code);
    };
 
    /// \copydoc ErrorCode::pythonNameError
    class OPALS_API PythonNameError : public PythonException {
    public:
      PythonNameError(const char *errorMessage);
    protected:
      PythonNameError(const char *errorMessage, ErrorCode::Enum code);
    };
 
    /// \copydoc ErrorCode::pythonSyntaxError
    class OPALS_API PythonSyntaxError : public PythonException {
    public:
      PythonSyntaxError(const char *errorMessage);
    protected:
      PythonSyntaxError(const char *errorMessage, ErrorCode::Enum code);
    };
 
    /// \copydoc ErrorCode::pythonTypeError
    class OPALS_API PythonTypeError : public PythonException {
    public:
      PythonTypeError(const char *errorMessage);
    protected:
      PythonTypeError(const char *errorMessage, ErrorCode::Enum code);
    };
 
    /// \copydoc ErrorCode::pythonValueError
    class OPALS_API PythonValueError : public PythonException {
    public:
      PythonValueError(const char *errorMessage);
    protected:
      PythonValueError(const char *errorMessage, ErrorCode::Enum code);
    };
 
    /// \copydoc ErrorCode::userInterrupt
    class OPALS_API UserInterrupt : public Base {
    public:
      UserInterrupt(const char *errorMessage = 0);
    protected:
      UserInterrupt(const char *errorMessage, ErrorCode::Enum code);        ///< Constructor for child classes
    };
 
    /// \copydoc ErrorCode::riwaveError
    class OPALS_API RiwaveError : public Base {
    public:
      RiwaveError(const char *errorMessage = 0);
    protected:
      RiwaveError(const char *errorMessage, ErrorCode::Enum code);        ///< Constructor for child classes
    };
  } // namespace Exceptions
}
 
#ifdef _MSC_VER
# pragma warning( pop ) 
#endif