simgear/structure/exception.hxx

   1 /**
   2  * \file exception.hxx
   3  * Interface definition for SimGear base exceptions.
   4  * Started Spring 2001 by David Megginson, david@megginson.com
   5  * This code is released into the Public Domain.
   6  *
   7  * $Id$
   8  */
   9
  10 #ifndef __SIMGEAR_MISC_EXCEPTION_HXX
  11 #define __SIMGEAR_MISC_EXCEPTION_HXX 1
  12
  13 #include <simgear/compiler.h>
  14 #include STL_STRING
  15
  16 SG_USING_STD(string);
  17
  18
  19 /**
  20  * Information encapsulating a single location in an external resource
  21  *
  22  * A position in the resource my optionally be provided, either by
  23  * line number, line number and column number, or byte offset from the
  24  * beginning of the resource.
  25  */
  26 class sg_location
  27 {
  28 public:
  29   sg_location ();
  30   sg_location (const string &path, int line = -1, int column = -1);
  31   virtual ~sg_location ();
  32   virtual const string &getPath () const;
  33   virtual void setPath (const string &path);
  34   virtual int getLine () const;
  35   virtual void setLine (int line);
  36   virtual int getColumn () const;
  37   virtual void setColumn (int column);
  38   virtual int getByte () const;
  39   virtual void setByte (int byte);
  40   virtual string asString () const;
  41 private:
  42   string _path;
  43   int _line;
  44   int _column;
  45   int _byte;
  46 };
  47
  48
  49 /**
  50  * Abstract base class for all throwables.
  51  */
  52 class sg_throwable
  53 {
  54 public:
  55   sg_throwable ();
  56   sg_throwable (const string &message, const string &origin = "");
  57   virtual ~sg_throwable ();
  58   virtual const string &getMessage () const;
  59   virtual const string getFormattedMessage () const;
  60   virtual void setMessage (const string &message);
  61   virtual const string &getOrigin () const;
  62   virtual void setOrigin (const string &origin);
  63 private:
  64   string _message;
  65   string _origin;
  66 };
  67
  68
  69
  70 /**
  71  * An unexpected fatal error.
  72  *
  73  * Methods and functions show throw this exception when something
  74  * very bad has happened (such as memory corruption or
  75  * a totally unexpected internal value).  Applications should catch
  76  * this exception only at the top level if at all, and should
  77  * normally terminate execution soon afterwards.
  78  */
  79 class sg_error : public sg_throwable
  80 {
  81 public:
  82   sg_error ();
  83   sg_error (const string &message, const string &origin = "");
  84   virtual ~sg_error ();
  85 };
  86
  87
  88 /**
  89  * Base class for all SimGear exceptions.
  90  *
  91  * SimGear-based code should throw this exception only when no
  92  * more specific exception applies.  It may not be caught until
  93  * higher up in the application, where it is not possible to
  94  * resume normal operations if desired.
  95  *
  96  * A caller can catch sg_exception by default to ensure that
  97  * all exceptions are caught.  Every SimGear exception can contain
  98  * a human-readable error message and a human-readable string
  99  * indicating the part of the application causing the exception
 100  * (as an aid to debugging, only).
 101  */
 102 class sg_exception : public sg_throwable
 103 {
 104 public:
 105   sg_exception ();
 106   sg_exception (const string &message, const string &origin = "");
 107   virtual ~sg_exception ();
 108 };
 109
 110
 111 /**
 112  * An I/O-related SimGear exception.
 113  *
 114  * SimGear-based code should throw this exception when it fails
 115  * to read from or write to an external resource, such as a file,
 116  * socket, URL, or database.
 117  *
 118  * In addition to the functionality of sg_exception, an
 119  * sg_io_exception may contain location information, such as the name
 120  * of a file or URL, and possible also a location in that file or URL.
 121  */
 122 class sg_io_exception : public sg_exception
 123 {
 124 public:
 125   sg_io_exception ();
 126   sg_io_exception (const string &message, const string &origin = "");
 127   sg_io_exception (const string &message, const sg_location &location,
 128                    const string &origin = "");
 129   virtual ~sg_io_exception ();
 130   virtual const string getFormattedMessage () const;
 131   virtual const sg_location &getLocation () const;
 132   virtual void setLocation (const sg_location &location);
 133 private:
 134   sg_location _location;
 135 };
 136
 137
 138 /**
 139  * A format-related SimGear exception.
 140  *
 141  * SimGear-based code should throw this exception when a string
 142  * does not appear in the expected format (for example, a date
 143  * string does not conform to ISO 8601).
 144  *
 145  * In addition to the functionality of sg_exception, an
 146  * sg_format_exception can contain a copy of the original malformated
 147  * text.
 148  */
 149 class sg_format_exception : public sg_exception
 150 {
 151 public:
 152   sg_format_exception ();
 153   sg_format_exception (const string &message, const string &text,
 154                        const string &origin = "");
 155   virtual ~sg_format_exception ();
 156   virtual const string &getText () const;
 157   virtual void setText (const string &text);
 158 private:
 159   string _text;
 160 };
 161
 162
 163 /**
 164  * A range-related SimGear exception.
 165  *
 166  * SimGear-based code should throw this exception when a value falls
 167  * outside the range where it can reasonably be handled; examples
 168  * include longitude outside the range -180:180, unrealistically high
 169  * forces or velocities, an illegal airport code, etc.  A range
 170  * exception usually means that something has gone wrong internally.
 171  */
 172 class sg_range_exception : public sg_exception
 173 {
 174 public:
 175   sg_range_exception ();
 176   sg_range_exception (const string &message, const string &origin = "");
 177   virtual ~sg_range_exception ();
 178 };
 179
 180 #endif
 181
 182 // end of exception.hxx