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