xmltooling/exceptions.h

   1 /*\r
   2  *  Copyright 2001-2006 Internet2\r
   3  * \r
   4  * Licensed under the Apache License, Version 2.0 (the "License");\r
   5  * you may not use this file except in compliance with the License.\r
   6  * You may obtain a copy of the License at\r
   7  *\r
   8  *     http://www.apache.org/licenses/LICENSE-2.0\r
   9  *\r
  10  * Unless required by applicable law or agreed to in writing, software\r
  11  * distributed under the License is distributed on an "AS IS" BASIS,\r
  12  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\r
  13  * See the License for the specific language governing permissions and\r
  14  * limitations under the License.\r
  15  */\r
  16 \r
  17 /**\r
  18  * @file exceptions.h\r
  19  * \r
  20  * Exception classes\r
  21  */\r
  22  \r
  23 #if !defined(__xmltooling_exceptions_h__)\r
  24 #define __xmltooling_exceptions_h__\r
  25 \r
  26 #include <map>\r
  27 #include <string>\r
  28 #include <vector>\r
  29 #include <iostream>\r
  30 #include <xmltooling/base.h>\r
  31 \r
  32 /**\r
  33  * Declares a derived exception class\r
  34  * \r
  35  * @param name  the exception class\r
  36  * @param base  the base class\r
  37  */\r
  38 #define DECL_XMLTOOLING_EXCEPTION(name,base) \\r
  39     class XMLTOOL_EXCEPTIONAPI(XMLTOOL_API) name : public xmltooling::base { \\r
  40     public: \\r
  41         name(const char* msg=NULL, const xmltooling::params& p=xmltooling::params()) \\r
  42             : xmltooling::base(msg,p) {} \\r
  43         name(const char* msg, const xmltooling::namedparams& p) \\r
  44             : xmltooling::base(msg,p) {} \\r
  45         name(const std::string& msg, const xmltooling::params& p=xmltooling::params()) \\r
  46             : xmltooling::base(msg,p) {} \\r
  47         name(const std::string& msg, const xmltooling::namedparams& p) \\r
  48             : xmltooling::base(msg,p) {} \\r
  49         virtual ~name() {} \\r
  50         virtual const char* getClassName() const { return "xmltooling::"#name; } \\r
  51         void raise() const {throw *this;} \\r
  52     }\r
  53 \r
  54 /**\r
  55  * Declares a factory function for an exception class.\r
  56  * \r
  57  * @param name  the exception class name\r
  58  */\r
  59 #define DECL_EXCEPTION_FACTORY(name) \\r
  60     xmltooling::XMLToolingException* name##Factory() \\r
  61     { \\r
  62         return new xmltooling::name(); \\r
  63     }\r
  64 \r
  65 /**\r
  66  * Registers a factory for an exception class.\r
  67  * \r
  68  * @param name  the exception class name\r
  69  */\r
  70 #define REGISTER_EXCEPTION_FACTORY(name) XMLToolingException::registerFactory("xmltooling::"#name,name##Factory)\r
  71 \r
  72 #if defined (_MSC_VER)\r
  73     #pragma warning( push )\r
  74     #pragma warning( disable : 4250 4251 )\r
  75 #endif\r
  76 \r
  77 namespace xmltooling {\r
  78     \r
  79     /**\r
  80      * Wrapper around a variable number of arguments.\r
  81      */\r
  82     class XMLTOOL_API params\r
  83     {\r
  84     public:\r
  85         /**\r
  86          * Initializes with zero parameters.\r
  87          */\r
  88         params() {}\r
  89         \r
  90         /**\r
  91          * Initializes the parameter set.\r
  92          * \r
  93          * @param count     the number of parameters that follow\r
  94          */\r
  95         params(int count,...);\r
  96         \r
  97         /**\r
  98          * Returns an immutable reference to the set of parameters.\r
  99          * \r
 100          * @return the parameter set\r
 101          */\r
 102         const std::vector<const char*>& get() const {return v;}\r
 103         \r
 104     protected:\r
 105         std::vector<const char*> v;\r
 106     };\r
 107     \r
 108     /**\r
 109      * Wrapper around a variable number of name/value pairs.\r
 110      */\r
 111     class XMLTOOL_API namedparams : public params\r
 112     {\r
 113     public:\r
 114         /**\r
 115          * Initializes with zero parameters.\r
 116          */\r
 117         namedparams() {}\r
 118 \r
 119         /**\r
 120          * Initializes the named parameter set.\r
 121          * \r
 122          * @param count     the number of name/value pairs that follow (must be even)\r
 123          */\r
 124         namedparams(int count,...);\r
 125     };\r
 126 \r
 127     /**\r
 128      * Base exception class, supports parametrized messages and XML serialization.\r
 129      * Parameters are prefixed with a dollar sign ($) and can be positional ($1)\r
 130      * or named ($info).\r
 131      */\r
 132     class XMLTOOL_EXCEPTIONAPI(XMLTOOL_API) XMLToolingException;\r
 133     typedef XMLToolingException* ExceptionFactory();\r
 134     \r
 135     class XMLTOOL_EXCEPTIONAPI(XMLTOOL_API) XMLToolingException\r
 136     {\r
 137     public:\r
 138         virtual ~XMLToolingException() {}\r
 139 \r
 140         /**\r
 141          * Constructs an exception using a message and positional parameters.\r
 142          * \r
 143          * @param msg   error message\r
 144          * @param p     an ordered set of positional parameter strings\r
 145          */\r
 146         XMLToolingException(const char* msg=NULL, const params& p=params());\r
 147 \r
 148         /**\r
 149          * Constructs an exception using a message and named parameters.\r
 150          * \r
 151          * @param msg   error message\r
 152          * @param p     a set of named parameter strings\r
 153          */\r
 154         XMLToolingException(const char* msg, const namedparams& p);\r
 155 \r
 156         /**\r
 157          * Constructs an exception using a message and positional parameters.\r
 158          * \r
 159          * @param msg   error message\r
 160          * @param p     an ordered set of positional parameter strings\r
 161          */\r
 162         XMLToolingException(const std::string& msg, const params& p=params());\r
 163 \r
 164         /**\r
 165          * Constructs an exception using a message and named parameters.\r
 166          * \r
 167          * @param msg   error message\r
 168          * @param p     a set of named parameter strings\r
 169          */\r
 170         XMLToolingException(const std::string& msg, const namedparams& p);\r
 171 \r
 172         /**\r
 173          * Returns the error message, after processing any parameter references.\r
 174          * \r
 175          * @return  the processed message\r
 176          */\r
 177         const char* getMessage() const;\r
 178 \r
 179         /**\r
 180          * Returns the error message, after processing any parameter references.\r
 181          * \r
 182          * @return  the processed message\r
 183          */\r
 184         const char* what() const {return getMessage();}\r
 185 \r
 186         /**\r
 187          * Sets the error message.\r
 188          * \r
 189          * @param msg   the error message\r
 190          */\r
 191         void setMessage(const char* msg);\r
 192 \r
 193         /**\r
 194          * Sets the error message.\r
 195          * \r
 196          * @param msg   the error message\r
 197          */\r
 198         void setMessage(const std::string& msg) {\r
 199             setMessage(msg.c_str());\r
 200         }\r
 201 \r
 202         /**\r
 203          * Attach a set of positional parameters to the exception.\r
 204          * \r
 205          * @param p     an ordered set of named parameter strings\r
 206          */\r
 207         void addProperties(const params& p);\r
 208         \r
 209         /**\r
 210          * Attach a set of named parameters to the exception.\r
 211          * \r
 212          * @param p     a set of named parameter strings\r
 213          */\r
 214         void addProperties(const namedparams& p);\r
 215 \r
 216         /**\r
 217          * Attach a single positional parameter at the next available position.\r
 218          * \r
 219          * @param value the parameter value\r
 220          */\r
 221         void addProperty(const char* value) {\r
 222             addProperties(params(1,value));\r
 223         }\r
 224 \r
 225         /**\r
 226          * Attach a single named parameter.\r
 227          * \r
 228          * @param name  the parameter name\r
 229          * @param value the parameter value\r
 230          */\r
 231         void addProperty(const char* name, const char* value) {\r
 232             addProperties(namedparams(1,name,value));\r
 233         }\r
 234 \r
 235         /**\r
 236          * Returns the parameter property with the designated position (based from one).\r
 237          * \r
 238          * @param index     position to access\r
 239          * @return  the parameter property or NULL\r
 240          */\r
 241         const char* getProperty(unsigned int index) const;\r
 242 \r
 243         /**\r
 244          * Returns the parameter property with the designated name.\r
 245          * \r
 246          * @param name     named parameter to access\r
 247          * @return  the parameter property or NULL\r
 248          */\r
 249         const char* getProperty(const char* name) const;\r
 250 \r
 251         /**\r
 252          * Raises an exception using itself.\r
 253          * Used to raise an exception of a derived type.\r
 254          */\r
 255         virtual void raise() const {\r
 256             throw *this;\r
 257         }\r
 258 \r
 259         /**\r
 260          * Returns a unique name for the exception class.\r
 261          * \r
 262          * @return class name\r
 263          */\r
 264         virtual const char* getClassName() const {\r
 265             return "xmltooling::XMLToolingException";\r
 266         }\r
 267         \r
 268         /**\r
 269          * Returns a string containing a serialized representation of the exception.\r
 270          * \r
 271          * @return  the serialization\r
 272          */\r
 273         std::string toString() const;\r
 274 \r
 275     private:\r
 276         std::string m_msg;\r
 277         mutable std::string m_processedmsg;\r
 278         std::map<std::string,std::string> m_params;\r
 279 \r
 280     public:\r
 281         /**\r
 282          * Builds an empty exception of the given type.\r
 283          * \r
 284          * @param exceptionClass    the name of the exception type to build\r
 285          * @return an empty exception object\r
 286          */\r
 287         static XMLToolingException* getInstance(const char* exceptionClass);\r
 288 \r
 289         /**\r
 290          * Builds an exception from a serialized input stream.\r
 291          * \r
 292          * @param in    input stream\r
 293          * @return the exception object found in the stream\r
 294          */\r
 295         static XMLToolingException* fromStream(std::istream& in);\r
 296         \r
 297         /**\r
 298          * Builds an exception from a serialized input buffer.\r
 299          * \r
 300          * @param s   input buffer\r
 301          * @return the exception object found in the buffer\r
 302          */\r
 303         static XMLToolingException* fromString(const char* s);\r
 304                 \r
 305         /**\r
 306          * Registers a factory to create exceptions of a given class name.\r
 307          * \r
 308          * @param exceptionClass    name of exception type\r
 309          * @param factory           factory function to build exceptions with\r
 310          */\r
 311         static void registerFactory(const char* exceptionClass, ExceptionFactory* factory) {\r
 312             m_factoryMap[exceptionClass] = factory;\r
 313         }\r
 314         \r
 315         /**\r
 316          * Unregisters the factory for a given class name.\r
 317          * \r
 318          * @param exceptionClass    name of exception type\r
 319          */\r
 320         static void deregisterFactory(const char* exceptionClass) {\r
 321             m_factoryMap.erase(exceptionClass);\r
 322         }\r
 323 \r
 324     private:\r
 325         typedef std::map<std::string,ExceptionFactory*> ExceptionFactoryMap;\r
 326         static ExceptionFactoryMap m_factoryMap;\r
 327     };\r
 328 \r
 329     DECL_XMLTOOLING_EXCEPTION(XMLParserException,XMLToolingException);\r
 330     DECL_XMLTOOLING_EXCEPTION(XMLObjectException,XMLToolingException);\r
 331     DECL_XMLTOOLING_EXCEPTION(MarshallingException,XMLToolingException);\r
 332     DECL_XMLTOOLING_EXCEPTION(UnmarshallingException,XMLToolingException);\r
 333     DECL_XMLTOOLING_EXCEPTION(UnknownElementException,XMLToolingException);\r
 334     DECL_XMLTOOLING_EXCEPTION(UnknownAttributeException,XMLToolingException);\r
 335     DECL_XMLTOOLING_EXCEPTION(ValidationException,XMLToolingException);\r
 336     DECL_XMLTOOLING_EXCEPTION(SignatureException,XMLToolingException);\r
 337 \r
 338 };\r
 339 \r
 340 #if defined (_MSC_VER)\r
 341     #pragma warning( pop )\r
 342 #endif\r
 343 \r
 344 #endif /* __xmltooling_exceptions_h__ */\r