2 * Licensed to the University Corporation for Advanced Internet
3 * Development, Inc. (UCAID) under one or more contributor license
4 * agreements. See the NOTICE file distributed with this work for
5 * additional information regarding copyright ownership.
7 * UCAID licenses this file to you under the Apache License,
8 * Version 2.0 (the "License"); you may not use this file except
9 * in compliance with the License. You may obtain a copy of the
12 * http://www.apache.org/licenses/LICENSE-2.0
14 * Unless required by applicable law or agreed to in writing,
15 * software distributed under the License is distributed on an
16 * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND,
17 * either express or implied. See the License for the specific
18 * language governing permissions and limitations under the License.
22 * @file xmltooling/exceptions.h
27 #ifndef __xmltooling_exceptions_h__
28 #define __xmltooling_exceptions_h__
30 #include <xmltooling/base.h>
38 * Declares a derived exception class
40 * @param name the exception class
41 * @param linkage linkage specification for class
42 * @param ns the exception class C++ namespace
43 * @param base the base class
44 * @param desc documentation comment for class
46 #define DECL_XMLTOOLING_EXCEPTION(name,linkage,ns,base,desc) \
47 XMLTOOLING_DOXYGEN(desc) \
48 class linkage name : public base { \
50 XMLTOOLING_DOXYGEN(Constructor) \
51 name(const char* msg=nullptr, const xmltooling::params& p=xmltooling::params()) : base(msg,p) {} \
52 XMLTOOLING_DOXYGEN(Constructor) \
53 name(const char* msg, const xmltooling::namedparams& p) : base(msg,p) {} \
54 XMLTOOLING_DOXYGEN(Constructor) \
55 name(const std::string& msg, const xmltooling::params& p=xmltooling::params()) : base(msg,p) {} \
56 XMLTOOLING_DOXYGEN(Constructor) \
57 name(const std::string& msg, const xmltooling::namedparams& p) : base(msg,p) {} \
58 virtual ~name() throw () {} \
59 virtual const char* getClassName() const { return #ns"::"#name; } \
60 void raise() const {throw *this;} \
64 * Declares a factory function for an exception class.
66 * @param name the exception class name
67 * @param ns the exception class C++ namespace
69 #define DECL_XMLTOOLING_EXCEPTION_FACTORY(name,ns) \
70 xmltooling::XMLToolingException* name##Factory() \
72 return new ns::name(); \
76 * Registers a factory for an exception class.
78 * @param name the exception class name
79 * @param ns the exception class C++ namespace
81 #define REGISTER_XMLTOOLING_EXCEPTION_FACTORY(name,ns) XMLToolingException::registerFactory(#ns"::"#name,name##Factory)
83 #if defined (_MSC_VER)
84 #pragma warning( push )
85 #pragma warning( disable : 4250 4251 )
88 namespace xmltooling {
91 * Wrapper around a variable number of arguments.
93 class XMLTOOL_API params
97 * Initializes with zero parameters.
102 * Initializes the parameter set.
104 * @param count the number of parameters that follow
106 params(int count,...);
109 * Returns an immutable reference to the set of parameters.
111 * @return the parameter set
113 const std::vector<const char*>& get() const {return v;}
116 /** Contains the parameters being passed. */
117 std::vector<const char*> v;
121 * Wrapper around a variable number of name/value pairs.
123 class XMLTOOL_API namedparams : public params
127 * Initializes with zero parameters.
132 * Initializes the named parameter set.
134 * @param count the number of name/value pairs that follow (must be even)
136 namedparams(int count,...);
140 * Base exception class, supports parametrized messages and XML serialization.
141 * Parameters are prefixed with a dollar sign ($) and can be positional ($1)
144 class XMLTOOL_EXCEPTIONAPI(XMLTOOL_API) XMLToolingException : public std::exception
147 virtual ~XMLToolingException() throw () {}
150 * Constructs an exception using a message and positional parameters.
152 * @param msg error message
153 * @param p an ordered set of positional parameter strings
155 XMLToolingException(const char* msg=nullptr, const params& p=params());
158 * Constructs an exception using a message and named parameters.
160 * @param msg error message
161 * @param p a set of named parameter strings
163 XMLToolingException(const char* msg, const namedparams& p);
166 * Constructs an exception using a message and positional parameters.
168 * @param msg error message
169 * @param p an ordered set of positional parameter strings
171 XMLToolingException(const std::string& msg, const params& p=params());
174 * Constructs an exception using a message and named parameters.
176 * @param msg error message
177 * @param p a set of named parameter strings
179 XMLToolingException(const std::string& msg, const namedparams& p);
182 * Returns the error message, after processing any parameter references.
184 * @return the processed message
186 const char* getMessage() const;
189 * Returns the error message, after processing any parameter references.
191 * @return the processed message
193 const char* what() const throw () {return getMessage();}
196 * Sets the error message.
198 * @param msg the error message
200 void setMessage(const char* msg);
203 * Sets the error message.
205 * @param msg the error message
207 void setMessage(const std::string& msg) {
208 setMessage(msg.c_str());
212 * Attach a set of positional parameters to the exception.
214 * @param p an ordered set of named parameter strings
216 void addProperties(const params& p);
219 * Attach a set of named parameters to the exception.
221 * @param p a set of named parameter strings
223 void addProperties(const namedparams& p);
226 * Attach a single positional parameter at the next available position.
228 * @param value the parameter value
230 void addProperty(const char* value) {
231 addProperties(params(1,value));
235 * Attach a single named parameter.
237 * @param name the parameter name
238 * @param value the parameter value
240 void addProperty(const char* name, const char* value) {
241 addProperties(namedparams(1,name,value));
245 * Returns the parameter property with the designated position (based from one).
247 * @param index position to access
248 * @return the parameter property or nullptr
250 const char* getProperty(unsigned int index) const;
253 * Returns the parameter property with the designated name.
255 * @param name named parameter to access
256 * @return the parameter property or nullptr
258 const char* getProperty(const char* name) const;
261 * Raises an exception using itself.
262 * Used to raise an exception of a derived type.
264 virtual void raise() const {
269 * Returns a unique name for the exception class.
273 virtual const char* getClassName() const {
274 return "xmltooling::XMLToolingException";
278 * Returns a string containing a serialized representation of the exception.
280 * @return the serialization
282 std::string toString() const;
285 * Returns a set of query string name/value pairs, URL-encoded, representing the
286 * exception's type, message, and parameters.
288 * @return the query string representation
290 std::string toQueryString() const;
294 mutable std::string m_processedmsg;
295 std::map<std::string,std::string> m_params;
299 * Builds an empty exception of the given type.
301 * @param exceptionClass the name of the exception type to build
302 * @return an empty exception object
304 static XMLToolingException* getInstance(const char* exceptionClass);
307 * Builds an exception from a serialized input stream.
309 * @param in input stream
310 * @return the exception object found in the stream
312 static XMLToolingException* fromStream(std::istream& in);
315 * Builds an exception from a serialized input buffer.
317 * @param s input buffer
318 * @return the exception object found in the buffer
320 static XMLToolingException* fromString(const char* s);
322 /** A factory function that returns an empty exception object of a given type. */
323 typedef XMLToolingException* ExceptionFactory();
326 * Registers a factory to create exceptions of a given class name.
328 * @param exceptionClass name of exception type
329 * @param factory factory function to build exceptions with
331 static void registerFactory(const char* exceptionClass, ExceptionFactory* factory) {
332 m_factoryMap[exceptionClass] = factory;
336 * Unregisters the factory for a given class name.
338 * @param exceptionClass name of exception type
340 static void deregisterFactory(const char* exceptionClass) {
341 m_factoryMap.erase(exceptionClass);
345 * Unregisters all factories.
347 static void deregisterFactories() {
348 m_factoryMap.clear();
352 typedef std::map<std::string,ExceptionFactory*> ExceptionFactoryMap;
353 static ExceptionFactoryMap m_factoryMap;
356 DECL_XMLTOOLING_EXCEPTION(XMLParserException,XMLTOOL_EXCEPTIONAPI(XMLTOOL_API),xmltooling,XMLToolingException,Exceptions related to XML parsing);
357 DECL_XMLTOOLING_EXCEPTION(XMLObjectException,XMLTOOL_EXCEPTIONAPI(XMLTOOL_API),xmltooling,XMLToolingException,Exceptions in basic object usage);
358 DECL_XMLTOOLING_EXCEPTION(MarshallingException,XMLTOOL_EXCEPTIONAPI(XMLTOOL_API),xmltooling,XMLToolingException,Exceptions during object marshalling);
359 DECL_XMLTOOLING_EXCEPTION(UnmarshallingException,XMLTOOL_EXCEPTIONAPI(XMLTOOL_API),xmltooling,XMLToolingException,Exceptions during object unmarshalling);
360 DECL_XMLTOOLING_EXCEPTION(UnknownElementException,XMLTOOL_EXCEPTIONAPI(XMLTOOL_API),xmltooling,XMLToolingException,Exceptions due to processing of unknown element content);
361 DECL_XMLTOOLING_EXCEPTION(UnknownAttributeException,XMLTOOL_EXCEPTIONAPI(XMLTOOL_API),xmltooling,XMLToolingException,Exceptions due to processing of unknown attributes);
362 DECL_XMLTOOLING_EXCEPTION(UnknownExtensionException,XMLTOOL_EXCEPTIONAPI(XMLTOOL_API),xmltooling,XMLToolingException,Exceptions from use of an unrecognized extension/plugin);
363 DECL_XMLTOOLING_EXCEPTION(ValidationException,XMLTOOL_EXCEPTIONAPI(XMLTOOL_API),xmltooling,XMLToolingException,Exceptions during object validation);
364 DECL_XMLTOOLING_EXCEPTION(IOException,XMLTOOL_EXCEPTIONAPI(XMLTOOL_API),xmltooling,XMLToolingException,Exceptions related to physical input/output errors);
366 #ifndef XMLTOOLING_NO_XMLSEC
367 DECL_XMLTOOLING_EXCEPTION(XMLSecurityException,XMLTOOL_EXCEPTIONAPI(XMLTOOL_API),xmltooling,XMLToolingException,Exceptions related to the XML security layer);
371 #if defined (_MSC_VER)
372 #pragma warning( pop )
375 #endif /* __xmltooling_exceptions_h__ */