2 * Copyright 2001-2009 Internet2
4 * Licensed under the Apache License, Version 2.0 (the "License");
5 * you may not use this file except in compliance with the License.
6 * You may obtain a copy of the License at
8 * http://www.apache.org/licenses/LICENSE-2.0
10 * Unless required by applicable law or agreed to in writing, software
11 * distributed under the License is distributed on an "AS IS" BASIS,
12 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13 * See the License for the specific language governing permissions and
14 * limitations under the License.
18 * @file xmltooling/exceptions.h
23 #ifndef __xmltooling_exceptions_h__
24 #define __xmltooling_exceptions_h__
26 #include <xmltooling/base.h>
34 * Declares a derived exception class
36 * @param name the exception class
37 * @param linkage linkage specification for class
38 * @param ns the exception class C++ namespace
39 * @param base the base class
40 * @param desc documentation comment for class
42 #define DECL_XMLTOOLING_EXCEPTION(name,linkage,ns,base,desc) \
43 XMLTOOLING_DOXYGEN(desc) \
44 class linkage name : public base { \
46 XMLTOOLING_DOXYGEN(Constructor) \
47 name(const char* msg=NULL, const xmltooling::params& p=xmltooling::params()) : base(msg,p) {} \
48 XMLTOOLING_DOXYGEN(Constructor) \
49 name(const char* msg, const xmltooling::namedparams& p) : base(msg,p) {} \
50 XMLTOOLING_DOXYGEN(Constructor) \
51 name(const std::string& msg, const xmltooling::params& p=xmltooling::params()) : base(msg,p) {} \
52 XMLTOOLING_DOXYGEN(Constructor) \
53 name(const std::string& msg, const xmltooling::namedparams& p) : base(msg,p) {} \
54 virtual ~name() throw () {} \
55 virtual const char* getClassName() const { return #ns"::"#name; } \
56 void raise() const {throw *this;} \
60 * Declares a factory function for an exception class.
62 * @param name the exception class name
63 * @param ns the exception class C++ namespace
65 #define DECL_XMLTOOLING_EXCEPTION_FACTORY(name,ns) \
66 xmltooling::XMLToolingException* name##Factory() \
68 return new ns::name(); \
72 * Registers a factory for an exception class.
74 * @param name the exception class name
75 * @param ns the exception class C++ namespace
77 #define REGISTER_XMLTOOLING_EXCEPTION_FACTORY(name,ns) XMLToolingException::registerFactory(#ns"::"#name,name##Factory)
79 #if defined (_MSC_VER)
80 #pragma warning( push )
81 #pragma warning( disable : 4250 4251 )
84 namespace xmltooling {
87 * Wrapper around a variable number of arguments.
89 class XMLTOOL_API params
93 * Initializes with zero parameters.
98 * Initializes the parameter set.
100 * @param count the number of parameters that follow
102 params(int count,...);
105 * Returns an immutable reference to the set of parameters.
107 * @return the parameter set
109 const std::vector<const char*>& get() const {return v;}
112 /** Contains the parameters being passed. */
113 std::vector<const char*> v;
117 * Wrapper around a variable number of name/value pairs.
119 class XMLTOOL_API namedparams : public params
123 * Initializes with zero parameters.
128 * Initializes the named parameter set.
130 * @param count the number of name/value pairs that follow (must be even)
132 namedparams(int count,...);
136 * Base exception class, supports parametrized messages and XML serialization.
137 * Parameters are prefixed with a dollar sign ($) and can be positional ($1)
140 class XMLTOOL_EXCEPTIONAPI(XMLTOOL_API) XMLToolingException : public std::exception
143 virtual ~XMLToolingException() throw () {}
146 * Constructs an exception using a message and positional parameters.
148 * @param msg error message
149 * @param p an ordered set of positional parameter strings
151 XMLToolingException(const char* msg=NULL, const params& p=params());
154 * Constructs an exception using a message and named parameters.
156 * @param msg error message
157 * @param p a set of named parameter strings
159 XMLToolingException(const char* msg, const namedparams& p);
162 * Constructs an exception using a message and positional parameters.
164 * @param msg error message
165 * @param p an ordered set of positional parameter strings
167 XMLToolingException(const std::string& msg, const params& p=params());
170 * Constructs an exception using a message and named parameters.
172 * @param msg error message
173 * @param p a set of named parameter strings
175 XMLToolingException(const std::string& msg, const namedparams& p);
178 * Returns the error message, after processing any parameter references.
180 * @return the processed message
182 const char* getMessage() const;
185 * Returns the error message, after processing any parameter references.
187 * @return the processed message
189 const char* what() const throw () {return getMessage();}
192 * Sets the error message.
194 * @param msg the error message
196 void setMessage(const char* msg);
199 * Sets the error message.
201 * @param msg the error message
203 void setMessage(const std::string& msg) {
204 setMessage(msg.c_str());
208 * Attach a set of positional parameters to the exception.
210 * @param p an ordered set of named parameter strings
212 void addProperties(const params& p);
215 * Attach a set of named parameters to the exception.
217 * @param p a set of named parameter strings
219 void addProperties(const namedparams& p);
222 * Attach a single positional parameter at the next available position.
224 * @param value the parameter value
226 void addProperty(const char* value) {
227 addProperties(params(1,value));
231 * Attach a single named parameter.
233 * @param name the parameter name
234 * @param value the parameter value
236 void addProperty(const char* name, const char* value) {
237 addProperties(namedparams(1,name,value));
241 * Returns the parameter property with the designated position (based from one).
243 * @param index position to access
244 * @return the parameter property or NULL
246 const char* getProperty(unsigned int index) const;
249 * Returns the parameter property with the designated name.
251 * @param name named parameter to access
252 * @return the parameter property or NULL
254 const char* getProperty(const char* name) const;
257 * Raises an exception using itself.
258 * Used to raise an exception of a derived type.
260 virtual void raise() const {
265 * Returns a unique name for the exception class.
269 virtual const char* getClassName() const {
270 return "xmltooling::XMLToolingException";
274 * Returns a string containing a serialized representation of the exception.
276 * @return the serialization
278 std::string toString() const;
281 * Returns a set of query string name/value pairs, URL-encoded, representing the
282 * exception's type, message, and parameters.
284 * @return the query string representation
286 std::string toQueryString() const;
290 mutable std::string m_processedmsg;
291 std::map<std::string,std::string> m_params;
295 * Builds an empty exception of the given type.
297 * @param exceptionClass the name of the exception type to build
298 * @return an empty exception object
300 static XMLToolingException* getInstance(const char* exceptionClass);
303 * Builds an exception from a serialized input stream.
305 * @param in input stream
306 * @return the exception object found in the stream
308 static XMLToolingException* fromStream(std::istream& in);
311 * Builds an exception from a serialized input buffer.
313 * @param s input buffer
314 * @return the exception object found in the buffer
316 static XMLToolingException* fromString(const char* s);
318 /** A factory function that returns an empty exception object of a given type. */
319 typedef XMLToolingException* ExceptionFactory();
322 * Registers a factory to create exceptions of a given class name.
324 * @param exceptionClass name of exception type
325 * @param factory factory function to build exceptions with
327 static void registerFactory(const char* exceptionClass, ExceptionFactory* factory) {
328 m_factoryMap[exceptionClass] = factory;
332 * Unregisters the factory for a given class name.
334 * @param exceptionClass name of exception type
336 static void deregisterFactory(const char* exceptionClass) {
337 m_factoryMap.erase(exceptionClass);
341 * Unregisters all factories.
343 static void deregisterFactories() {
344 m_factoryMap.clear();
348 typedef std::map<std::string,ExceptionFactory*> ExceptionFactoryMap;
349 static ExceptionFactoryMap m_factoryMap;
352 DECL_XMLTOOLING_EXCEPTION(XMLParserException,XMLTOOL_EXCEPTIONAPI(XMLTOOL_API),xmltooling,XMLToolingException,Exceptions related to XML parsing);
353 DECL_XMLTOOLING_EXCEPTION(XMLObjectException,XMLTOOL_EXCEPTIONAPI(XMLTOOL_API),xmltooling,XMLToolingException,Exceptions in basic object usage);
354 DECL_XMLTOOLING_EXCEPTION(MarshallingException,XMLTOOL_EXCEPTIONAPI(XMLTOOL_API),xmltooling,XMLToolingException,Exceptions during object marshalling);
355 DECL_XMLTOOLING_EXCEPTION(UnmarshallingException,XMLTOOL_EXCEPTIONAPI(XMLTOOL_API),xmltooling,XMLToolingException,Exceptions during object unmarshalling);
356 DECL_XMLTOOLING_EXCEPTION(UnknownElementException,XMLTOOL_EXCEPTIONAPI(XMLTOOL_API),xmltooling,XMLToolingException,Exceptions due to processing of unknown element content);
357 DECL_XMLTOOLING_EXCEPTION(UnknownAttributeException,XMLTOOL_EXCEPTIONAPI(XMLTOOL_API),xmltooling,XMLToolingException,Exceptions due to processing of unknown attributes);
358 DECL_XMLTOOLING_EXCEPTION(UnknownExtensionException,XMLTOOL_EXCEPTIONAPI(XMLTOOL_API),xmltooling,XMLToolingException,Exceptions from use of an unrecognized extension/plugin);
359 DECL_XMLTOOLING_EXCEPTION(ValidationException,XMLTOOL_EXCEPTIONAPI(XMLTOOL_API),xmltooling,XMLToolingException,Exceptions during object validation);
360 DECL_XMLTOOLING_EXCEPTION(IOException,XMLTOOL_EXCEPTIONAPI(XMLTOOL_API),xmltooling,XMLToolingException,Exceptions related to physical input/output errors);
362 #ifndef XMLTOOLING_NO_XMLSEC
363 DECL_XMLTOOLING_EXCEPTION(XMLSecurityException,XMLTOOL_EXCEPTIONAPI(XMLTOOL_API),xmltooling,XMLToolingException,Exceptions related to the XML security layer);
367 #if defined (_MSC_VER)
368 #pragma warning( pop )
371 #endif /* __xmltooling_exceptions_h__ */