2 * Copyright 2001-2006 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.
23 #ifndef __xmltooling_exceptions_h__
24 #define __xmltooling_exceptions_h__
30 #include <xmltooling/base.h>
33 * Declares a derived exception class
35 * @param name the exception class
36 * @param ns the exception class C++ namespace
37 * @param base the base class
38 * @param desc documentation comment for class
40 #define DECL_XMLTOOLING_EXCEPTION(name,ns,base,desc) \
41 XMLTOOLING_DOXYGEN(desc) \
42 class XMLTOOL_EXCEPTIONAPI(XMLTOOL_API) name : public base { \
44 XMLTOOLING_DOXYGEN(Constructor) \
45 name(const char* msg=NULL, const xmltooling::params& p=xmltooling::params()) : base(msg,p) {} \
46 XMLTOOLING_DOXYGEN(Constructor) \
47 name(const char* msg, const xmltooling::namedparams& p) : base(msg,p) {} \
48 XMLTOOLING_DOXYGEN(Constructor) \
49 name(const std::string& msg, const xmltooling::params& p=xmltooling::params()) : base(msg,p) {} \
50 XMLTOOLING_DOXYGEN(Constructor) \
51 name(const std::string& msg, const xmltooling::namedparams& p) : base(msg,p) {} \
53 virtual const char* getClassName() const { return #ns"::"#name; } \
54 void raise() const {throw *this;} \
58 * Declares a factory function for an exception class.
60 * @param name the exception class name
61 * @param ns the exception class C++ namespace
63 #define DECL_EXCEPTION_FACTORY(name,ns) \
64 xmltooling::XMLToolingException* name##Factory() \
66 return new ns::name(); \
70 * Registers a factory for an exception class.
72 * @param name the exception class name
73 * @param ns the exception class C++ namespace
75 #define REGISTER_EXCEPTION_FACTORY(name,ns) XMLToolingException::registerFactory(#ns"::"#name,name##Factory)
77 #if defined (_MSC_VER)
78 #pragma warning( push )
79 #pragma warning( disable : 4250 4251 )
82 namespace xmltooling {
85 * Wrapper around a variable number of arguments.
87 class XMLTOOL_API params
91 * Initializes with zero parameters.
96 * Initializes the parameter set.
98 * @param count the number of parameters that follow
100 params(int count,...);
103 * Returns an immutable reference to the set of parameters.
105 * @return the parameter set
107 const std::vector<const char*>& get() const {return v;}
110 /** Contains the parameters being passed. */
111 std::vector<const char*> v;
115 * Wrapper around a variable number of name/value pairs.
117 class XMLTOOL_API namedparams : public params
121 * Initializes with zero parameters.
126 * Initializes the named parameter set.
128 * @param count the number of name/value pairs that follow (must be even)
130 namedparams(int count,...);
133 class XMLTOOL_EXCEPTIONAPI(XMLTOOL_API) XMLToolingException;
135 /** A factory function that returns an empty exception object of a given type. */
136 typedef XMLToolingException* ExceptionFactory();
139 * Base exception class, supports parametrized messages and XML serialization.
140 * Parameters are prefixed with a dollar sign ($) and can be positional ($1)
143 class XMLTOOL_EXCEPTIONAPI(XMLTOOL_API) XMLToolingException
146 virtual ~XMLToolingException() {}
149 * Constructs an exception using a message and positional parameters.
151 * @param msg error message
152 * @param p an ordered set of positional parameter strings
154 XMLToolingException(const char* msg=NULL, const params& p=params());
157 * Constructs an exception using a message and named parameters.
159 * @param msg error message
160 * @param p a set of named parameter strings
162 XMLToolingException(const char* msg, const namedparams& p);
165 * Constructs an exception using a message and positional parameters.
167 * @param msg error message
168 * @param p an ordered set of positional parameter strings
170 XMLToolingException(const std::string& msg, const params& p=params());
173 * Constructs an exception using a message and named parameters.
175 * @param msg error message
176 * @param p a set of named parameter strings
178 XMLToolingException(const std::string& msg, const namedparams& p);
181 * Returns the error message, after processing any parameter references.
183 * @return the processed message
185 const char* getMessage() const;
188 * Returns the error message, after processing any parameter references.
190 * @return the processed message
192 const char* what() const {return getMessage();}
195 * Sets the error message.
197 * @param msg the error message
199 void setMessage(const char* msg);
202 * Sets the error message.
204 * @param msg the error message
206 void setMessage(const std::string& msg) {
207 setMessage(msg.c_str());
211 * Attach a set of positional parameters to the exception.
213 * @param p an ordered set of named parameter strings
215 void addProperties(const params& p);
218 * Attach a set of named parameters to the exception.
220 * @param p a set of named parameter strings
222 void addProperties(const namedparams& p);
225 * Attach a single positional parameter at the next available position.
227 * @param value the parameter value
229 void addProperty(const char* value) {
230 addProperties(params(1,value));
234 * Attach a single named parameter.
236 * @param name the parameter name
237 * @param value the parameter value
239 void addProperty(const char* name, const char* value) {
240 addProperties(namedparams(1,name,value));
244 * Returns the parameter property with the designated position (based from one).
246 * @param index position to access
247 * @return the parameter property or NULL
249 const char* getProperty(unsigned int index) const;
252 * Returns the parameter property with the designated name.
254 * @param name named parameter to access
255 * @return the parameter property or NULL
257 const char* getProperty(const char* name) const;
260 * Raises an exception using itself.
261 * Used to raise an exception of a derived type.
263 virtual void raise() const {
268 * Returns a unique name for the exception class.
272 virtual const char* getClassName() const {
273 return "xmltooling::XMLToolingException";
277 * Returns a string containing a serialized representation of the exception.
279 * @return the serialization
281 std::string toString() const;
285 mutable std::string m_processedmsg;
286 std::map<std::string,std::string> m_params;
290 * Builds an empty exception of the given type.
292 * @param exceptionClass the name of the exception type to build
293 * @return an empty exception object
295 static XMLToolingException* getInstance(const char* exceptionClass);
298 * Builds an exception from a serialized input stream.
300 * @param in input stream
301 * @return the exception object found in the stream
303 static XMLToolingException* fromStream(std::istream& in);
306 * Builds an exception from a serialized input buffer.
308 * @param s input buffer
309 * @return the exception object found in the buffer
311 static XMLToolingException* fromString(const char* s);
314 * Registers a factory to create exceptions of a given class name.
316 * @param exceptionClass name of exception type
317 * @param factory factory function to build exceptions with
319 static void registerFactory(const char* exceptionClass, ExceptionFactory* factory) {
320 m_factoryMap[exceptionClass] = factory;
324 * Unregisters the factory for a given class name.
326 * @param exceptionClass name of exception type
328 static void deregisterFactory(const char* exceptionClass) {
329 m_factoryMap.erase(exceptionClass);
333 * Unregisters all factories.
335 static void deregisterFactories() {
336 m_factoryMap.clear();
340 typedef std::map<std::string,ExceptionFactory*> ExceptionFactoryMap;
341 static ExceptionFactoryMap m_factoryMap;
344 DECL_XMLTOOLING_EXCEPTION(XMLParserException,xmltooling,XMLToolingException,Exceptions related to XML parsing);
345 DECL_XMLTOOLING_EXCEPTION(XMLObjectException,xmltooling,XMLToolingException,Exceptions in basic object usage);
346 DECL_XMLTOOLING_EXCEPTION(MarshallingException,xmltooling,XMLToolingException,Exceptions during object marshalling);
347 DECL_XMLTOOLING_EXCEPTION(UnmarshallingException,xmltooling,XMLToolingException,Exceptions during object unmarshalling);
348 DECL_XMLTOOLING_EXCEPTION(UnknownElementException,xmltooling,XMLToolingException,Exceptions due to processing of unknown element content);
349 DECL_XMLTOOLING_EXCEPTION(UnknownAttributeException,xmltooling,XMLToolingException,Exceptions due to processing of unknown attributes);
350 DECL_XMLTOOLING_EXCEPTION(ValidationException,xmltooling,XMLToolingException,Exceptions during object validation);
354 #if defined (_MSC_VER)
355 #pragma warning( pop )
358 #endif /* __xmltooling_exceptions_h__ */