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 #ifndef __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  * @param desc\r
  38  */\r
  39 #define DECL_XMLTOOLING_EXCEPTION(name,base,desc) \\r
  40     /##** desc */ \\r
  41     class XMLTOOL_EXCEPTIONAPI(XMLTOOL_API) name : public xmltooling::base { \\r
  42     public: \\r
  43         /##** base##::##base(const char*,const xmltooling::params&) */ \\r
  44         name(const char* msg=NULL, const xmltooling::params& p=xmltooling::params()) \\r
  45             : xmltooling::base(msg,p) {} \\r
  46         /##** base##::##base(const char*,const xmltooling::namedparams&) */ \\r
  47         name(const char* msg, const xmltooling::namedparams& p) \\r
  48             : xmltooling::base(msg,p) {} \\r
  49         /##** base##::##base(const std::string&,const xmltooling::params&) */ \\r
  50         name(const std::string& msg, const xmltooling::params& p=xmltooling::params()) \\r
  51             : xmltooling::base(msg,p) {} \\r
  52         /##** base##::##base(const std::string&,const xmltooling::namedparams&) */ \\r
  53         name(const std::string& msg, const xmltooling::namedparams& p) \\r
  54             : xmltooling::base(msg,p) {} \\r
  55         virtual ~name() {} \\r
  56         virtual const char* getClassName() const { return "xmltooling::"#name; } \\r
  57         void raise() const {throw *this;} \\r
  58     }\r
  59 \r
  60 /**\r
  61  * Declares a factory function for an exception class.\r
  62  * \r
  63  * @param name  the exception class name\r
  64  */\r
  65 #define DECL_EXCEPTION_FACTORY(name) \\r
  66     xmltooling::XMLToolingException* name##Factory() \\r
  67     { \\r
  68         return new xmltooling::name(); \\r
  69     }\r
  70 \r
  71 /**\r
  72  * Registers a factory for an exception class.\r
  73  * \r
  74  * @param name  the exception class name\r
  75  */\r
  76 #define REGISTER_EXCEPTION_FACTORY(name) XMLToolingException::registerFactory("xmltooling::"#name,name##Factory)\r
  77 \r
  78 #if defined (_MSC_VER)\r
  79     #pragma warning( push )\r
  80     #pragma warning( disable : 4250 4251 )\r
  81 #endif\r
  82 \r
  83 namespace xmltooling {\r
  84     \r
  85     /**\r
  86      * Wrapper around a variable number of arguments.\r
  87      */\r
  88     class XMLTOOL_API params\r
  89     {\r
  90     public:\r
  91         /**\r
  92          * Initializes with zero parameters.\r
  93          */\r
  94         params() {}\r
  95         \r
  96         /**\r
  97          * Initializes the parameter set.\r
  98          * \r
  99          * @param count     the number of parameters that follow\r
 100          */\r
 101         params(int count,...);\r
 102         \r
 103         /**\r
 104          * Returns an immutable reference to the set of parameters.\r
 105          * \r
 106          * @return the parameter set\r
 107          */\r
 108         const std::vector<const char*>& get() const {return v;}\r
 109         \r
 110     protected:\r
 111         /** Contains the parameters being passed. */\r
 112         std::vector<const char*> v;\r
 113     };\r
 114     \r
 115     /**\r
 116      * Wrapper around a variable number of name/value pairs.\r
 117      */\r
 118     class XMLTOOL_API namedparams : public params\r
 119     {\r
 120     public:\r
 121         /**\r
 122          * Initializes with zero parameters.\r
 123          */\r
 124         namedparams() {}\r
 125 \r
 126         /**\r
 127          * Initializes the named parameter set.\r
 128          * \r
 129          * @param count     the number of name/value pairs that follow (must be even)\r
 130          */\r
 131         namedparams(int count,...);\r
 132     };\r
 133 \r
 134     class XMLTOOL_EXCEPTIONAPI(XMLTOOL_API) XMLToolingException;\r
 135     \r
 136     /** A factory function that returns an empty exception object of a given type. */\r
 137     typedef XMLToolingException* ExceptionFactory();\r
 138     \r
 139     /**\r
 140      * Base exception class, supports parametrized messages and XML serialization.\r
 141      * Parameters are prefixed with a dollar sign ($) and can be positional ($1)\r
 142      * or named ($info).\r
 143      */\r
 144     class XMLTOOL_EXCEPTIONAPI(XMLTOOL_API) XMLToolingException\r
 145     {\r
 146     public:\r
 147         virtual ~XMLToolingException() {}\r
 148 \r
 149         /**\r
 150          * Constructs an exception using a message and positional parameters.\r
 151          * \r
 152          * @param msg   error message\r
 153          * @param p     an ordered set of positional parameter strings\r
 154          */\r
 155         XMLToolingException(const char* msg=NULL, const params& p=params());\r
 156 \r
 157         /**\r
 158          * Constructs an exception using a message and named parameters.\r
 159          * \r
 160          * @param msg   error message\r
 161          * @param p     a set of named parameter strings\r
 162          */\r
 163         XMLToolingException(const char* msg, const namedparams& p);\r
 164 \r
 165         /**\r
 166          * Constructs an exception using a message and positional parameters.\r
 167          * \r
 168          * @param msg   error message\r
 169          * @param p     an ordered set of positional parameter strings\r
 170          */\r
 171         XMLToolingException(const std::string& msg, const params& p=params());\r
 172 \r
 173         /**\r
 174          * Constructs an exception using a message and named parameters.\r
 175          * \r
 176          * @param msg   error message\r
 177          * @param p     a set of named parameter strings\r
 178          */\r
 179         XMLToolingException(const std::string& msg, const namedparams& p);\r
 180 \r
 181         /**\r
 182          * Returns the error message, after processing any parameter references.\r
 183          * \r
 184          * @return  the processed message\r
 185          */\r
 186         const char* getMessage() const;\r
 187 \r
 188         /**\r
 189          * Returns the error message, after processing any parameter references.\r
 190          * \r
 191          * @return  the processed message\r
 192          */\r
 193         const char* what() const {return getMessage();}\r
 194 \r
 195         /**\r
 196          * Sets the error message.\r
 197          * \r
 198          * @param msg   the error message\r
 199          */\r
 200         void setMessage(const char* msg);\r
 201 \r
 202         /**\r
 203          * Sets the error message.\r
 204          * \r
 205          * @param msg   the error message\r
 206          */\r
 207         void setMessage(const std::string& msg) {\r
 208             setMessage(msg.c_str());\r
 209         }\r
 210 \r
 211         /**\r
 212          * Attach a set of positional parameters to the exception.\r
 213          * \r
 214          * @param p     an ordered set of named parameter strings\r
 215          */\r
 216         void addProperties(const params& p);\r
 217         \r
 218         /**\r
 219          * Attach a set of named parameters to the exception.\r
 220          * \r
 221          * @param p     a set of named parameter strings\r
 222          */\r
 223         void addProperties(const namedparams& p);\r
 224 \r
 225         /**\r
 226          * Attach a single positional parameter at the next available position.\r
 227          * \r
 228          * @param value the parameter value\r
 229          */\r
 230         void addProperty(const char* value) {\r
 231             addProperties(params(1,value));\r
 232         }\r
 233 \r
 234         /**\r
 235          * Attach a single named parameter.\r
 236          * \r
 237          * @param name  the parameter name\r
 238          * @param value the parameter value\r
 239          */\r
 240         void addProperty(const char* name, const char* value) {\r
 241             addProperties(namedparams(1,name,value));\r
 242         }\r
 243 \r
 244         /**\r
 245          * Returns the parameter property with the designated position (based from one).\r
 246          * \r
 247          * @param index     position to access\r
 248          * @return  the parameter property or NULL\r
 249          */\r
 250         const char* getProperty(unsigned int index) const;\r
 251 \r
 252         /**\r
 253          * Returns the parameter property with the designated name.\r
 254          * \r
 255          * @param name     named parameter to access\r
 256          * @return  the parameter property or NULL\r
 257          */\r
 258         const char* getProperty(const char* name) const;\r
 259 \r
 260         /**\r
 261          * Raises an exception using itself.\r
 262          * Used to raise an exception of a derived type.\r
 263          */\r
 264         virtual void raise() const {\r
 265             throw *this;\r
 266         }\r
 267 \r
 268         /**\r
 269          * Returns a unique name for the exception class.\r
 270          * \r
 271          * @return class name\r
 272          */\r
 273         virtual const char* getClassName() const {\r
 274             return "xmltooling::XMLToolingException";\r
 275         }\r
 276         \r
 277         /**\r
 278          * Returns a string containing a serialized representation of the exception.\r
 279          * \r
 280          * @return  the serialization\r
 281          */\r
 282         std::string toString() const;\r
 283 \r
 284     private:\r
 285         std::string m_msg;\r
 286         mutable std::string m_processedmsg;\r
 287         std::map<std::string,std::string> m_params;\r
 288 \r
 289     public:\r
 290         /**\r
 291          * Builds an empty exception of the given type.\r
 292          * \r
 293          * @param exceptionClass    the name of the exception type to build\r
 294          * @return an empty exception object\r
 295          */\r
 296         static XMLToolingException* getInstance(const char* exceptionClass);\r
 297 \r
 298         /**\r
 299          * Builds an exception from a serialized input stream.\r
 300          * \r
 301          * @param in    input stream\r
 302          * @return the exception object found in the stream\r
 303          */\r
 304         static XMLToolingException* fromStream(std::istream& in);\r
 305         \r
 306         /**\r
 307          * Builds an exception from a serialized input buffer.\r
 308          * \r
 309          * @param s   input buffer\r
 310          * @return the exception object found in the buffer\r
 311          */\r
 312         static XMLToolingException* fromString(const char* s);\r
 313                 \r
 314         /**\r
 315          * Registers a factory to create exceptions of a given class name.\r
 316          * \r
 317          * @param exceptionClass    name of exception type\r
 318          * @param factory           factory function to build exceptions with\r
 319          */\r
 320         static void registerFactory(const char* exceptionClass, ExceptionFactory* factory) {\r
 321             m_factoryMap[exceptionClass] = factory;\r
 322         }\r
 323         \r
 324         /**\r
 325          * Unregisters the factory for a given class name.\r
 326          * \r
 327          * @param exceptionClass    name of exception type\r
 328          */\r
 329         static void deregisterFactory(const char* exceptionClass) {\r
 330             m_factoryMap.erase(exceptionClass);\r
 331         }\r
 332 \r
 333     private:\r
 334         typedef std::map<std::string,ExceptionFactory*> ExceptionFactoryMap;\r
 335         static ExceptionFactoryMap m_factoryMap;\r
 336     };\r
 337 \r
 338     DECL_XMLTOOLING_EXCEPTION(XMLParserException,XMLToolingException,Exceptions related to XML parsing);\r
 339     DECL_XMLTOOLING_EXCEPTION(XMLObjectException,XMLToolingException,Exceptions in basic object usage);\r
 340     DECL_XMLTOOLING_EXCEPTION(MarshallingException,XMLToolingException,Exceptions during object marshalling);\r
 341     DECL_XMLTOOLING_EXCEPTION(UnmarshallingException,XMLToolingException,Exceptions during object unmarshalling);\r
 342     DECL_XMLTOOLING_EXCEPTION(UnknownElementException,XMLToolingException,Exceptions due to processing of unknown element content);\r
 343     DECL_XMLTOOLING_EXCEPTION(UnknownAttributeException,XMLToolingException,Exceptions due to processing of unknown attributes);\r
 344     DECL_XMLTOOLING_EXCEPTION(ValidationException,XMLToolingException,Exceptions during object validation);\r
 345     DECL_XMLTOOLING_EXCEPTION(SignatureException,XMLToolingException,Exceptions in signature processing);\r
 346 \r
 347 };\r
 348 \r
 349 #if defined (_MSC_VER)\r
 350     #pragma warning( pop )\r
 351 #endif\r
 352 \r
 353 #endif /* __xmltooling_exceptions_h__ */\r