CLHEP 2.0.4.7 Reference Documentation     CLHEP Home Page     CLHEP Documentation     CLHEP Bug Reports

ZMexception.h

Go to the documentation of this file.

#ifndef ZMEXCEPTION_H
#define ZMEXCEPTION_H


// ----------------------------------------------------------------------
//
// ZMexception.h - class declaration for the ZOOM Exception base classes,
//                 and macros to help set up specific exceptions definitions.
//
//   class ZMexception:  This is the public base type of all exceptions.
//                       In particular this is the interface seen by
//                       handler and logger.  Methods are defined in
//                       a macro ZMexClassStaticMethods, in ZMexception.icc,
//                       or in .../Exceptions/src/ZMexception.cc:
//
//   in the macro       ZMexception.icc         src/ZMexception.cc
//   ------------       ---------------         ------------------
//   setHandler()       ZMexception
//   getHandler()       message()
//   setLogger()
//   getLogger()        count()
//   isTypeOf()         wasThrown()             logMessage(optText)
//   isBaseOf()         severity()
//   isDerivedFrom      location(line, file)
//   logNMore()         fileName()
//   handleMe()         line()
//   logMe()                                    name()
//                                              facility()
//                      OKtoLog()
//
// ZMexClassStaticMethods is defined here.  It is used not only by the base
// class definition (ZMexception) but also by a couple of macros established
// for the convenience of creators of ZMex exceptions:
//
//   ZMexStandardContents contains definitions of all the functions in the
//                        interface for exception creators which are implemented
//                        via methods in classInfo.  See technical notes 2 - 5.
//
//   ZMexStandardDefinition defines an exception in the inheritance hierarchy,
//                         with no specific data or member functions beyond
//                         the standard contents.  If more members are needed,
//                         use this macro as an example and add them after the
//                         ZMexStandardContents.
//
// See technical note 1 for instructions on how to use these macros to define
// ZOOM exceptions.  (Technical notes are in file technical-notes in the
// doc area of the Exceptions product).
//
// One further key macro should be known:
//
//   ZMthrow(x) in ZMthrow.h calls ZMthrow_ but adds on the line and file
//   arguments.  ZMthrow_(x,line,file) does the dispatching of the exception
//   handling.
//
// Related structures include:
//
//   ZMexClassInfo  contains the definitions of the classInfo structure.
//                      ZMexClassInfo.h
//
// Revision History:
//      970912  MF      Initial version after separating out classInfo etc.
//      970914  MF      Corrected isBaseOf method, which needs isDerivedFrom.
//      970916  WEB     Updated per code review
//      970917  WEB     Updated per code review 2
//      970918  WEB     Updated per code review 3
//      970918  PGC     Updated per code review 4
//      971112  WEB     Updated for conformance to standard and the zoom
//                      compatability headers
//      971211  WEB     Updated per code walkthrough
//      971215  WEB     Gave names to the default handler & logger
//      980219  WEB     Corrected return types of get/set Handler/Logger
//                      to match those of those classes' methods
//      980304  WEB     Cleaned up logMessage() & related stuff
//      980421  WEB     Moved name() and facility() from .icc to .cc
//      980615  WEB     Added namespace support
//      990318  MF      Added virtual destructor
//      990801  JVR     Added logObject() for augmented exception purposes
//      000217  WEB     Improve C++ standards compliance
//      000503  WEB     Avoid global using
//      010413  MF      Vetted for proper namespace behavior:
//                      all macros need to use the equivalent of ZM_QUAL_NAME 
//                      to append zmex if (and only if) namespaces are enabled.
//      010626  MF      ctor from ostringstream for syntactic convenience
//      010626  MF      Have ctor use string& rather than string 
//      011012  MF      Include ZMutility/sstream so ostringstream& is OK
//                      (KCC somehow survived the omission; gcc does not)
//      011217  MF      logMe() for base class does 
//                      ZMexception::classInfo().getLogger().emit(*this);
//                      instead of emit(msg).  This significantly improves
//                      the look of the output when this path is taken, and
//                      when logging to an ErrorLog allows statistics to work.
//      031105  LG      Get rid of all ZMutility references
//      051117  LG      Always use <sstream>
//
// ----------------------------------------------------------------------

#include "CLHEP/Exceptions/defs.h"

#include <iosfwd>

#ifndef STRING_INCLUDED
  #define STRING_INCLUDED
  #include <string>
#endif

#ifndef ZMEXSEVERITY_H
  #include "CLHEP/Exceptions/ZMexSeverity.h"
#endif

#ifndef ZMEXLOGRESULT_H
  #include "CLHEP/Exceptions/ZMexLogResult.h"
#endif

#ifndef ZMEXACTION_H
  #include "CLHEP/Exceptions/ZMexAction.h"
#endif

#ifndef ZMEXCLASSINFO_H
  #include "CLHEP/Exceptions/ZMexClassInfo.h"
#endif

#include <sstream>


#ifdef ZM_USE_NAMESPACES
#define ZMEX zmex
#else
#define ZMEX
#endif

namespace zmex  {


class ZMexHandler;
class ZMexLogger;
class ZMexNoParent;

// **************************************
//
// ZMexUserActivity, ZMexUserNumericalTag
//
// **************************************

extern std::string ZMexUserActivity;
extern int ZMexUserNumericalTag;


// *******************
//
// ZMhandler, ZMlogger
//
// *******************

ZMexHandler &  ZMhandler();
ZMexLogger  &  ZMlogger();

// ***********
//
// ZMexception
//
// ***********

class ZMexception {

protected:
  static ZMexClassInfo _classInfo;
    // The base class has these static members for its class information.

  const std::string message_;
    // Indicates reason for the exception.  Should be unique to the line of
    // code doing ZMthrow.  Multiple lines can throw the same ZMexception,
    // but normally supply different messages.

  #ifndef DEFECT_NO_MUTABLE
  mutable
  #endif
  int    line_;
  #ifndef DEFECT_NO_MUTABLE
  mutable
  #endif
  std::string sourceFileName_;
    // Indicate location of the source of the exception

    // Copy for each instance of the class-wide data to snapshot them.
  const ZMexSeverity mySeverity_;
  const int          myCount_;
  #ifndef DEFECT_NO_MUTABLE
  mutable
  #endif
  std::string     handlerUsed_;
  #ifndef DEFECT_NO_MUTABLE
  mutable
  #endif
  bool       wasThrown_;



public:
  // ********************** //
  // Constructor/Destructor //
  // ********************** //

  ZMexception(
    const std::string &      mesg
  , const ZMexSeverity howBad = ZMexSEVERITYenumLAST
  , int                count  = ZMexception::_classInfo.nextCount()
  );

  explicit
  ZMexception(
    const std::ostringstream & msg
  , const ZMexSeverity howBad = ZMexSEVERITYenumLAST
  , int                count  = ZMexception::_classInfo.nextCount()
  );

  virtual ~ZMexception() {}

  // ********************** //
  // Instance Methods       //
  // ********************** //

  void location( int line, const std::string file ) const;
    // Set the location of the creator of the exception

  ZMexSeverity severity() const;
    // Determine the severity of this exception.

  int line() const;
  std::string fileName() const;
    // Determine the file/line number of the ZMthrow of this exception.

  std::string message() const;
  int count() const;

  std::string handlerUsed() const;
  bool   wasThrown() const;

  // The following are for internal use of the exception mechanism routines:
  void handlerUsed( const std::string handlerName ) const;
  void wasThrown( bool b ) const;

  virtual std::string logMessage( const std::string optText = "" ) const;

  virtual std::string facility() const;
    // Return the class facility preamble string.

  virtual std::string name() const;
    // Return the exception name string, e.g., "ZMexWhatever".

  bool OKtoLog() const;


  // ****************************
  //
  // Methods dealt with in the
  // ZMexClassStaticMethods macro
  //
  // ****************************

public:
  // ********************** //
  // Class static Methods   //
  // ********************** //

  // This declares the standard static methods and the virtual
  // functions that depend on the static member of exception class --
  // classInfo.  Technical note 5 explains why we will
  // need to use a macro defining these methods, rather than using simple
  // virtual methods or using templates.

  // Note - These declarations become moot for every class derived from
  // ZMexception, because the methods of the same names are explicitly
  // declared and defined in the ZMexClassStaticMethods macro.  However,
  // it is useful to have these declarations here in the base class, to
  // set forth a clean and commented specification of the interface to
  // these routines.  The interface applies to ALL ZOOM exceptions.

  /*
  static ZMexHandler setHandler( const ZMexHandler & newHandler );
    // Replace previous handler; return old handler.

  static const ZMexHandler getHandler();
    // Return the current handler.

  static ZMexLogger setLogger( const ZMexLogger & newLogger );
    // Replace previous logger; return old logger.

  static const ZMexLogger getLogger();
    // Return the current logger.

  static ZMexSeverity setSeverity ( const ZMexSeverity & newSeverity );
    // Replace previous severity; return old severity.

  static const std::string setName ( const std::string & newName );
    // Replace previous name; return old name.

  static const std::string setFacility ( const std::string & newFacility );
    // Replace previous Facility; return old Facility.

  static bool isTypeOf( const ZMexception & x );
    // Test if x is this type of exception

  static bool isBaseOf( const ZMexception & x );
    // Test if x is exactly or derived from this type of exception
  */

  // ************************************************************** //
  // Virtual instance methods that utilize class static information //
  // ************************************************************** //

  // Note - These are just like the class static methods in that they
  // have to be declared explicitly for each exception class, lest they
  // incorrectly use the method of that name in the base class ZMexception.
  // See technical note 6.
  // The difference is that (letting x be an instance of an exception type X)
  // these "instance methods" are invoked as x.f(), while the "class static
  // methods" are invoked by X::f().

  // These instance methods have to be virtual because the exception x is passed
  // to a method expecting a ZMexception, which then invokes x.method().  If
  // method() is not virtual you get ZMexception.method() - which we don't
  // want - even though X has a method of that same name defined.

  /*
  virtual ZMexClassInfo & classInfo();
    // return  the appropriate classInfo

  virtual ZMexAction handleMe() const;
    // handle the current instance

  virtual ZMexLogResult logMe() const;
    // log the current instance

  virtual bool isDerivedFrom( const std::string name,
                              const std::string facility );
    // check if this intance is of class derived form the one qualified
    // by name and facility.
    // Test if this exception is derived from an exception with given name
  */

  // ****************************
  // ZMexClassStaticMethods macro
  // ****************************

  // This macro contains definitions implementing the standard static methods
  // (class-wide logically virtual functions) that depend on the static member
  // of the exception class -- classInfo.  Technical note 5
  // addresses the need to use a macro defining these methods,

  // CODING NOTE -- THE ROUTINES DEFINED HERE SHOULD MATCH EXACTLY THE
  //                INTERFACE DECLARED ABOVE (except that static methods
  //                may not be declared const).

#define ZMexClassStaticMethods                                          \
                                                                        \
  static zmex::ZMexHandler setHandler(                  \
                const zmex::ZMexHandler & newHandler ) {        \
    return  _classInfo.setHandler( newHandler); }                       \
  static zmex::ZMexHandler getHandler() {                       \
    return  _classInfo.getHandler(); }                                  \
                                                                        \
  static zmex::ZMexLogger setLogger(                    \
                const zmex::ZMexLogger & newLogger ) {  \
    return _classInfo.setLogger( newLogger ); }                         \
  static zmex::ZMexLogger getLogger() {                 \
    return  _classInfo.getLogger(); }                                   \
                                                                        \
  static zmex::ZMexSeverity setSeverity (                       \
        const zmex::ZMexSeverity & newSeverity ) {              \
    return _classInfo.setSeverity (newSeverity); }                      \
  static const std::string setName ( const std::string & newName ) {    \
    return _classInfo.setName (newName); }                              \
  static const std::string setFacility(const std::string& newFacility){ \
    return _classInfo.setFacility (newFacility); }                      \
  static bool isTypeOf( const zmex::ZMexception & x ) { \
    return  ( (_classInfo.name() == x.name()) &&                        \
              (_classInfo.facility() == x.facility() ) ); }             \
                                                                        \
  static bool isBaseOf( const zmex::ZMexception & x ) { \
    return  ( x.isDerivedFrom (_classInfo.name(),                       \
                               _classInfo.facility()) ); }              \
                                                                        \
  static void logNMore( const int N )  {                                \
    _classInfo.logNMore( N ); }                                         \

//
// end of ZMexClassStaticMethods macro

  // ****************************
  // ZMexVirtualMethods macro
  // ****************************

  // This macro contains definitions implementing the standard virtual methods
  // that depend on the static members of the exception class -- classInfo.
  // Technical note 5 addresses the need to use a macro defining
  // these methods,

  // CODING NOTE -- THE ROUTINES DEFINED HERE SHOULD MATCH EXACTLY THE
  //                INTERFACE DECLARED ABOVE (except that static methods
  //                may not be declared const).

#define ZMexVirtualMethods(Parent,Class)                                \
                                                                        \
  virtual Class *                                 clone() const {       \
    return  new Class( *this ); }                                       \
                                                                        \
  virtual zmex::ZMexClassInfo & classInfo() const {     \
    return  Class::_classInfo; }                                        \
                                                                        \
  virtual zmex::ZMexAction handleMe() const {           \
          /* DEBUG  std::cerr << #Class "::handleMe()" << std::endl; */ \
    zmex::ZMexAction result =                           \
                Class::classInfo().getHandler().takeCareOf( *this );    \
    return  (result == zmex::ZMexHANDLEVIAPARENT) ?     \
                        Parent::handleMe() : result; }                  \
                                                                        \
  virtual zmex::ZMexLogResult logMe() const {           \
        /* DEBUG  std::cerr << #Class "::logMe()" << std::endl; */      \
    zmex::ZMexLogResult result =                                \
                Class::classInfo().getLogger().emit( *this );           \
    return  (result == zmex::ZMexLOGVIAPARENT) ?                \
                                Parent::logMe() : result; }             \
                                                                        \
  virtual bool isDerivedFrom( const std::string aName,                  \
                              const std::string aFacility ) const {     \
    return  aName == name()  &&  aFacility == facility()                \
      ? true                                                            \
      : Parent::isDerivedFrom( aName, aFacility );                      \
  }                                                                     \

//
// end of ZMexVirtualMethods macro

public:
  ZMexClassStaticMethods;
    // Define all the static methods for the ZMexception base class.

  // Special cases for the virtual functions for the top exception class.
  virtual ZMexception * clone() const {
    return  new ZMexception ( *this );
  }

  virtual zmex::ZMexClassInfo & classInfo() const {
    return  ZMexception::_classInfo;
  }

  virtual ZMexAction handleMe() const {
    // DEBUG  std::cerr << "ZMexception::handleMe()" << std::endl;
    return  ZMexception::classInfo().getHandler().takeCareOf( *this );
  }

  virtual ZMexLogResult logMe() const {
    // DEBUG  std::cerr << "ZMexception::logMe()" << std::endl;
    return ZMexception::classInfo().getLogger().emit(*this);
  }

  virtual bool isDerivedFrom(
    const std::string name
  , const std::string facility
  ) const {
    return  false;
  }

  virtual void logObject() const {}                                //added

};  // ZMexception


// *************************************
//
// Macros for deriving ZOOM exceptions
//
// *************************************


// *******************************
// ZMexStandardContents macro
// *******************************

#define ZMexStandardContents(Parent,Class)                              \
public:                                                                 \
  static zmex::ZMexClassInfo _classInfo;                        \
public:                                                                 \
  Class(                                                                \
    const std::string  & mesg                                           \
  , const zmex::ZMexSeverity howBad =                   \
                        zmex::ZMexSEVERITYenumLAST              \
  , int                      count = _classInfo.nextCount()             \
  )  :                                                                  \
    Parent(                                                             \
      mesg                                                              \
    , (howBad == zmex::ZMexSEVERITYenumLAST ?           \
                        _classInfo.severity() : howBad)                 \
    , count                                                             \
    )                                                                   \
  { }                                                                   \
                                                                        \
  Class(                                                                \
    const std::ostringstream&  msg                                      \
  , const zmex::ZMexSeverity howBad =                   \
                        zmex::ZMexSEVERITYenumLAST              \
  , int                      count = _classInfo.nextCount()             \
  )  :                                                                  \
    Parent(                                                             \
      msg                                                               \
    , (howBad == zmex::ZMexSEVERITYenumLAST ?           \
                        _classInfo.severity() : howBad)                 \
    , count                                                             \
    )                                                                   \
  { }                                                                   \
                                                                        \
  ZMexClassStaticMethods;                                               \
  ZMexVirtualMethods(Parent,Class);                                     \

//
// end of ZMexStandardContents macro


// *******************************
// ZMexStandardDefinition macro
// *******************************

#define ZMexStandardDefinition(Parent,Class)                            \
  class Class : public Parent {                                         \
    ZMexStandardContents(Parent,Class)                                  \
  }                                                                     \

//
// end of ZMexStandardDefinition macro


}  // namespace zmex


#define ZMEXCEPTION_ICC
#include "CLHEP/Exceptions/ZMexception.icc"
#undef ZMEXCEPTION_ICC


#endif  // ZMEXCEPTION_H

---