CLHEP VERSION Reference Documentation
   
CLHEP Home Page     CLHEP Documentation     CLHEP Bug Reports

Exceptions/ZMexception.h
Go to the documentation of this file.
1 #ifndef ZMEXCEPTION_H
2 #define ZMEXCEPTION_H
3 
4 
5 // ----------------------------------------------------------------------
6 //
7 // ZMexception.h - class declaration for the ZOOM Exception base classes,
8 // and macros to help set up specific exceptions definitions.
9 //
10 // class ZMexception: This is the public base type of all exceptions.
11 // In particular this is the interface seen by
12 // handler and logger. Methods are defined in
13 // a macro ZMexClassStaticMethods, in ZMexception.icc,
14 // or in .../Exceptions/src/ZMexception.cc:
15 //
16 // in the macro ZMexception.icc src/ZMexception.cc
17 // ------------ --------------- ------------------
18 // setHandler() ZMexception
19 // getHandler() message()
20 // setLogger()
21 // getLogger() count()
22 // isTypeOf() wasThrown() logMessage(optText)
23 // isBaseOf() severity()
24 // isDerivedFrom location(line, file)
25 // logNMore() fileName()
26 // handleMe() line()
27 // logMe() name()
28 // facility()
29 // OKtoLog()
30 //
31 // ZMexClassStaticMethods is defined here. It is used not only by the base
32 // class definition (ZMexception) but also by a couple of macros established
33 // for the convenience of creators of ZMex exceptions:
34 //
35 // ZMexStandardContents contains definitions of all the functions in the
36 // interface for exception creators which are implemented
37 // via methods in classInfo. See technical notes 2 - 5.
38 //
39 // ZMexStandardDefinition defines an exception in the inheritance hierarchy,
40 // with no specific data or member functions beyond
41 // the standard contents. If more members are needed,
42 // use this macro as an example and add them after the
43 // ZMexStandardContents.
44 //
45 // See technical note 1 for instructions on how to use these macros to define
46 // ZOOM exceptions. (Technical notes are in file technical-notes in the
47 // doc area of the Exceptions product).
48 //
49 // One further key macro should be known:
50 //
51 // ZMthrow(x) in ZMthrow.h calls ZMthrow_ but adds on the line and file
52 // arguments. ZMthrow_(x,line,file) does the dispatching of the exception
53 // handling.
54 //
55 // Related structures include:
56 //
57 // ZMexClassInfo contains the definitions of the classInfo structure.
58 // ZMexClassInfo.h
59 //␌
60 // Revision History:
61 // 970912 MF Initial version after separating out classInfo etc.
62 // 970914 MF Corrected isBaseOf method, which needs isDerivedFrom.
63 // 970916 WEB Updated per code review
64 // 970917 WEB Updated per code review 2
65 // 970918 WEB Updated per code review 3
66 // 970918 PGC Updated per code review 4
67 // 971112 WEB Updated for conformance to standard and the zoom
68 // compatability headers
69 // 971211 WEB Updated per code walkthrough
70 // 971215 WEB Gave names to the default handler & logger
71 // 980219 WEB Corrected return types of get/set Handler/Logger
72 // to match those of those classes' methods
73 // 980304 WEB Cleaned up logMessage() & related stuff
74 // 980421 WEB Moved name() and facility() from .icc to .cc
75 // 980615 WEB Added namespace support
76 // 990318 MF Added virtual destructor
77 // 990801 JVR Added logObject() for augmented exception purposes
78 // 000217 WEB Improve C++ standards compliance
79 // 000503 WEB Avoid global using
80 // 010413 MF Vetted for proper namespace behavior:
81 // all macros need to use the equivalent of ZM_QUAL_NAME
82 // to append zmex if (and only if) namespaces are enabled.
83 // 010626 MF ctor from ostringstream for syntactic convenience
84 // 010626 MF Have ctor use string& rather than string
85 // 011012 MF Include ZMutility/sstream so ostringstream& is OK
86 // (KCC somehow survived the omission; gcc does not)
87 // 011217 MF logMe() for base class does
88 // ZMexception::classInfo().getLogger().emit(*this);
89 // instead of emit(msg). This significantly improves
90 // the look of the output when this path is taken, and
91 // when logging to an ErrorLog allows statistics to work.
92 // 031105 LG Get rid of all ZMutility references
93 // 051117 LG Always use <sstream>
94 //
95 // ----------------------------------------------------------------------
96 
97 #include "CLHEP/Exceptions/defs.h"
98 
99 #include <iosfwd>
100 
101 #ifndef STRING_INCLUDED
102  #define STRING_INCLUDED
103  #include <string>
104 #endif
105 
106 #ifndef ZMEXSEVERITY_H
108 #endif
109 
110 #ifndef ZMEXLOGRESULT_H
112 #endif
113 
114 #ifndef ZMEXACTION_H
116 #endif
117 
118 #ifndef ZMEXCLASSINFO_H
120 #endif
121 
122 #include <sstream>
123 
124 
125 #ifdef ZM_USE_NAMESPACES
126 #define ZMEX zmex
127 #else
128 #define ZMEX
129 #endif
130 
131 namespace zmex {
132 
133 
134 class ZMexHandler;
135 class ZMexLogger;
136 class ZMexNoParent;
137 
138 // **************************************
139 //
140 // ZMexUserActivity, ZMexUserNumericalTag
141 //
142 // **************************************
143 
144 extern std::string ZMexUserActivity;
146 
147 
148 // *******************
149 //
150 // ZMhandler, ZMlogger
151 //
152 // *******************
153 
155 ZMexLogger & ZMlogger();
156 ␌
157 // ***********
158 //
159 // ZMexception
160 //
161 // ***********
162 
163 class ZMexception {
164 
165 protected:
166  static ZMexClassInfo _classInfo;
167  // The base class has these static members for its class information.
168 
169  const std::string message_;
170  // Indicates reason for the exception. Should be unique to the line of
171  // code doing ZMthrow. Multiple lines can throw the same ZMexception,
172  // but normally supply different messages.
173 
174  #ifndef DEFECT_NO_MUTABLE
175  mutable
176  #endif
177  int line_;
178  #ifndef DEFECT_NO_MUTABLE
179  mutable
180  #endif
181  std::string sourceFileName_;
182  // Indicate location of the source of the exception
183 
184  // Copy for each instance of the class-wide data to snapshot them.
186  const int myCount_;
187  #ifndef DEFECT_NO_MUTABLE
188  mutable
189  #endif
190  std::string handlerUsed_;
191  #ifndef DEFECT_NO_MUTABLE
192  mutable
193  #endif
194  bool wasThrown_;
195 
196 
197 ␌
198 public:
199  // ********************** //
200  // Constructor/Destructor //
201  // ********************** //
202 
204  const std::string & mesg
205  , const ZMexSeverity howBad = ZMexSEVERITYenumLAST
206  , int icount = ZMexception::_classInfo.nextCount()
207  );
208 
209  explicit
211  const std::ostringstream & msg
212  , const ZMexSeverity howBad = ZMexSEVERITYenumLAST
213  , int icount = ZMexception::_classInfo.nextCount()
214  );
215 
216  virtual ~ZMexception() {}
217 
218  // ********************** //
219  // Instance Methods //
220  // ********************** //
221 
222  void location( int line, const std::string file ) const;
223  // Set the location of the creator of the exception
224 
226  // Determine the severity of this exception.
227 
228  int line() const;
229  std::string fileName() const;
230  // Determine the file/line number of the ZMthrow of this exception.
231 
232  std::string message() const;
233  int count() const;
234 
235  std::string handlerUsed() const;
236  bool wasThrown() const;
237 
238  // The following are for internal use of the exception mechanism routines:
239  void handlerUsed( const std::string handlerName ) const;
240  void wasThrown( bool b ) const;
241 
242  virtual std::string logMessage( const std::string optText = "" ) const;
243 
244  virtual std::string facility() const;
245  // Return the class facility preamble string.
246 
247  virtual std::string name() const;
248  // Return the exception name string, e.g., "ZMexWhatever".
249 
250  bool OKtoLog() const;
251 
252 ␌
253  // ****************************
254  //
255  // Methods dealt with in the
256  // ZMexClassStaticMethods macro
257  //
258  // ****************************
259 
260 public:
261  // ********************** //
262  // Class static Methods //
263  // ********************** //
264 
265  // This declares the standard static methods and the virtual
266  // functions that depend on the static member of exception class --
267  // classInfo. Technical note 5 explains why we will
268  // need to use a macro defining these methods, rather than using simple
269  // virtual methods or using templates.
270 
271  // Note - These declarations become moot for every class derived from
272  // ZMexception, because the methods of the same names are explicitly
273  // declared and defined in the ZMexClassStaticMethods macro. However,
274  // it is useful to have these declarations here in the base class, to
275  // set forth a clean and commented specification of the interface to
276  // these routines. The interface applies to ALL ZOOM exceptions.
277 
278  /*
279  static ZMexHandler setHandler( const ZMexHandler & newHandler );
280  // Replace previous handler; return old handler.
281 
282  static const ZMexHandler getHandler();
283  // Return the current handler.
284 
285  static ZMexLogger setLogger( const ZMexLogger & newLogger );
286  // Replace previous logger; return old logger.
287 
288  static const ZMexLogger getLogger();
289  // Return the current logger.
290 
291  static ZMexSeverity setSeverity ( const ZMexSeverity & newSeverity );
292  // Replace previous severity; return old severity.
293 
294  static const std::string setName ( const std::string & newName );
295  // Replace previous name; return old name.
296 
297  static const std::string setFacility ( const std::string & newFacility );
298  // Replace previous Facility; return old Facility.
299 
300  static bool isTypeOf( const ZMexception & x );
301  // Test if x is this type of exception
302 
303  static bool isBaseOf( const ZMexception & x );
304  // Test if x is exactly or derived from this type of exception
305  */
306 ␌
307  // ************************************************************** //
308  // Virtual instance methods that utilize class static information //
309  // ************************************************************** //
310 
311  // Note - These are just like the class static methods in that they
312  // have to be declared explicitly for each exception class, lest they
313  // incorrectly use the method of that name in the base class ZMexception.
314  // See technical note 6.
315  // The difference is that (letting x be an instance of an exception type X)
316  // these "instance methods" are invoked as x.f(), while the "class static
317  // methods" are invoked by X::f().
318 
319  // These instance methods have to be virtual because the exception x is passed
320  // to a method expecting a ZMexception, which then invokes x.method(). If
321  // method() is not virtual you get ZMexception.method() - which we don't
322  // want - even though X has a method of that same name defined.
323 
324  /*
325  virtual ZMexClassInfo & classInfo();
326  // return the appropriate classInfo
327 
328  virtual ZMexAction handleMe() const;
329  // handle the current instance
330 
331  virtual ZMexLogResult logMe() const;
332  // log the current instance
333 
334  virtual bool isDerivedFrom( const std::string name,
335  const std::string facility );
336  // check if this intance is of class derived form the one qualified
337  // by name and facility.
338  // Test if this exception is derived from an exception with given name
339  */
340 ␌
341  // ****************************
342  // ZMexClassStaticMethods macro
343  // ****************************
344 
345  // This macro contains definitions implementing the standard static methods
346  // (class-wide logically virtual functions) that depend on the static member
347  // of the exception class -- classInfo. Technical note 5
348  // addresses the need to use a macro defining these methods,
349 
350  // CODING NOTE -- THE ROUTINES DEFINED HERE SHOULD MATCH EXACTLY THE
351  // INTERFACE DECLARED ABOVE (except that static methods
352  // may not be declared const).
353 
354 #define ZMexClassStaticMethods \
355  \
356  static zmex::ZMexHandler setHandler( \
357  const zmex::ZMexHandler & newHandler ) { \
358  return _classInfo.setHandler( newHandler); } \
359  static zmex::ZMexHandler getHandler() { \
360  return _classInfo.getHandler(); } \
361  \
362  static zmex::ZMexLogger setLogger( \
363  const zmex::ZMexLogger & newLogger ) { \
364  return _classInfo.setLogger( newLogger ); } \
365  static zmex::ZMexLogger getLogger() { \
366  return _classInfo.getLogger(); } \
367  \
368  static zmex::ZMexSeverity setSeverity ( \
369  const zmex::ZMexSeverity & newSeverity ) { \
370  return _classInfo.setSeverity (newSeverity); } \
371  static const std::string setName ( const std::string & newName ) { \
372  return _classInfo.setName (newName); } \
373  static const std::string setFacility(const std::string& newFacility){ \
374  return _classInfo.setFacility (newFacility); } \
375  static bool isTypeOf( const zmex::ZMexception & x ) { \
376  return ( (_classInfo.name() == x.name()) && \
377  (_classInfo.facility() == x.facility() ) ); } \
378  \
379  static bool isBaseOf( const zmex::ZMexception & x ) { \
380  return ( x.isDerivedFrom (_classInfo.name(), \
381  _classInfo.facility()) ); } \
382  \
383  static void logNMore( const int N ) { \
384  _classInfo.logNMore( N ); } \
385 
386 //
387 // end of ZMexClassStaticMethods macro
388 ␌
389  // ****************************
390  // ZMexVirtualMethods macro
391  // ****************************
392 
393  // This macro contains definitions implementing the standard virtual methods
394  // that depend on the static members of the exception class -- classInfo.
395  // Technical note 5 addresses the need to use a macro defining
396  // these methods,
397 
398  // CODING NOTE -- THE ROUTINES DEFINED HERE SHOULD MATCH EXACTLY THE
399  // INTERFACE DECLARED ABOVE (except that static methods
400  // may not be declared const).
401 
402 #define ZMexVirtualMethods(Parent,Class) \
403  \
404  virtual Class * clone() const { \
405  return new Class( *this ); } \
406  \
407  virtual zmex::ZMexClassInfo & classInfo() const { \
408  return Class::_classInfo; } \
409  \
410  virtual zmex::ZMexAction handleMe() const { \
411  /* DEBUG std::cerr << #Class "::handleMe()" << std::endl; */ \
412  zmex::ZMexAction result = \
413  Class::classInfo().getHandler().takeCareOf( *this ); \
414  return (result == zmex::ZMexHANDLEVIAPARENT) ? \
415  Parent::handleMe() : result; } \
416  \
417  virtual zmex::ZMexLogResult logMe() const { \
418  /* DEBUG std::cerr << #Class "::logMe()" << std::endl; */ \
419  zmex::ZMexLogResult result = \
420  Class::classInfo().getLogger().emit( *this ); \
421  return (result == zmex::ZMexLOGVIAPARENT) ? \
422  Parent::logMe() : result; } \
423  \
424  virtual bool isDerivedFrom( const std::string aName, \
425  const std::string aFacility ) const { \
426  return aName == name() && aFacility == facility() \
427  ? true \
428  : Parent::isDerivedFrom( aName, aFacility ); \
429  } \
430 
431 //
432 // end of ZMexVirtualMethods macro
433 ␌
434 public:
436  // Define all the static methods for the ZMexception base class.
437 
438  // Special cases for the virtual functions for the top exception class.
439  virtual ZMexception * clone() const {
440  return new ZMexception ( *this );
441  }
442 
443  virtual zmex::ZMexClassInfo & classInfo() const {
445  }
446 
447  virtual ZMexAction handleMe() const {
448  // DEBUG std::cerr << "ZMexception::handleMe()" << std::endl;
449  return ZMexception::classInfo().getHandler().takeCareOf( *this );
450  }
451 
452  virtual ZMexLogResult logMe() const {
453  // DEBUG std::cerr << "ZMexception::logMe()" << std::endl;
454  return ZMexception::classInfo().getLogger().emit(*this);
455  }
456 
457  virtual bool isDerivedFrom(
458  const std::string
459  , const std::string
460  ) const {
461  return false;
462  }
463 
464  virtual void logObject() const {} //added
465 
466 }; // ZMexception
467 
468 ␌
469 // *************************************
470 //
471 // Macros for deriving ZOOM exceptions
472 //
473 // *************************************
474 
475 
476 // *******************************
477 // ZMexStandardContents macro
478 // *******************************
479 
480 #define ZMexStandardContents(Parent,Class) \
481 public: \
482  static zmex::ZMexClassInfo _classInfo; \
483 public: \
484  Class( \
485  const std::string & mesg \
486  , const zmex::ZMexSeverity howBad = \
487  zmex::ZMexSEVERITYenumLAST \
488  , int icount = _classInfo.nextCount() \
489  ) : \
490  Parent( \
491  mesg \
492  , (howBad == zmex::ZMexSEVERITYenumLAST ? \
493  _classInfo.severity() : howBad) \
494  , icount \
495  ) \
496  { } \
497  \
498  Class( \
499  const std::ostringstream& msg \
500  , const zmex::ZMexSeverity howBad = \
501  zmex::ZMexSEVERITYenumLAST \
502  , int icount = _classInfo.nextCount() \
503  ) : \
504  Parent( \
505  msg \
506  , (howBad == zmex::ZMexSEVERITYenumLAST ? \
507  _classInfo.severity() : howBad) \
508  , icount \
509  ) \
510  { } \
511  \
512  ZMexClassStaticMethods; \
513  ZMexVirtualMethods(Parent,Class); \
514 
515 //
516 // end of ZMexStandardContents macro
517 
518 
519 // *******************************
520 // ZMexStandardDefinition macro
521 // *******************************
522 
523 #define ZMexStandardDefinition(Parent,Class) \
524  class Class : public Parent { \
525  ZMexStandardContents(Parent,Class) \
526  } \
527 
528 //
529 // end of ZMexStandardDefinition macro
530 
531 
532 } // namespace zmex
533 
534 
535 #define ZMEXCEPTION_ICC
536 #include "CLHEP/Exceptions/ZMexception.icc"
537 #undef ZMEXCEPTION_ICC
538 
539 
540 #endif // ZMEXCEPTION_H
ZMexHandler getHandler() const
ZMexLogger getLogger() const
virtual ZMexAction takeCareOf(const ZMexception &x)
ZMexLogResult emit(const ZMexception &exc)
Definition: ZMexLogger.cc:252
int count() const
std::string fileName() const
int line() const
virtual zmex::ZMexClassInfo & classInfo() const
static ZMexClassInfo _classInfo
virtual ZMexLogResult logMe() const
virtual void logObject() const
std::string handlerUsed() const
void wasThrown(bool b) const
virtual ZMexception * clone() const
ZMexception(const std::string &mesg, const ZMexSeverity howBad=ZMexSEVERITYenumLAST, int icount=ZMexception::_classInfo.nextCount())
virtual std::string name() const
std::string message() const
virtual std::string logMessage(const std::string optText="") const
void handlerUsed(const std::string handlerName) const
virtual bool isDerivedFrom(const std::string, const std::string) const
virtual ZMexAction handleMe() const
bool wasThrown() const
ZMexSeverity severity() const
virtual std::string facility() const
ZMexception(const std::ostringstream &msg, const ZMexSeverity howBad=ZMexSEVERITYenumLAST, int icount=ZMexception::_classInfo.nextCount())
bool OKtoLog() const
void location(int line, const std::string file) const
int ZMexUserNumericalTag
ZMexLogger & ZMlogger()
Definition: ZMexception.cc:68
ZMexHandler & ZMhandler()
Definition: ZMexception.cc:63
std::string ZMexUserActivity
@ b